From 89372e8cf64e869b791d71230cd259bc59990758 Mon Sep 17 00:00:00 2001 From: gitee-bot Date: Fri, 6 Feb 2026 04:00:16 +0000 Subject: [PATCH] Update README.md --- README.md | 311 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 274 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 4c8c246..d9c93db 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,274 @@ -# osgPotree - -osgPotree 是基于 OpenSceneGraph（OSG）开发的插件，能够直接加载由 PotreeConverter 2.0 生成的点云数据，为 OSG 用户提供了便捷的点云渲染支持，并集成了点云编辑、目标识别等一系列相关辅助工具。 -本代码库包含用于构建 osgPotree 库的 C++ 头文件、源文件以及 CMake 构建脚本。当前仅依赖OpenSceneGraph。于OpenSceneGraph一致，该软件支持在Linux、Windows、Android、macOS下构建。 - -## 详细信息链接 - -osgPotree 项目的详细功能特性、教程于设计文档，请访问以下链接获取。本代码库则提供了用于构建该库的全部源代码及编译支持。 -* [osgPotree] https://blog.csdn.net/CPWWHSU/article/details/157363010 -* [pointCloudExtractor] https://blog.csdn.net/CPWWHSU/article/details/157363010 - - -## osgPotree 构建快速指南 - -### 环境准备: -* 必要: 支持 C++11 标准的编译器，例如 g++ 4.8.1 或更高版本、Clang 3.3 或更高版本、Visual Studio 2017 或更高版本。 -* 必要： [CMake](https://www.cmake.org) 3.7或以后。 -* 必要: [OpenSceneGraph](https://github.com/openscenegraph/OpenSceneGraph.git) 3.4.0及以后。 - -以上列出的依赖版本均为经验证可用的版本，因此被设定为当前的最低要求。使用更早的版本进行构建也有可能成功。若您使用更旧的版本成功完成构建，请告知我们，以便更新版本信息。 - -### 命令行编译指南: - -在源码目录中构建并安装osgPotree 库，以windows 11下为例，首先将编译好的OSG库(https://pan.baidu.com/s/1vi3SUza6KZVsL77H0X699Q?pwd=qtpj)下载到本地并解压到当前文件夹，接着在当前文件夹下运行如下命令(cmd not powershell)： - - git clone https://gitee.com/osg_opensource/osg-potree.git - cd osg-potree - cmake . -DCMAKE_BUILD_TYPE=Release -DTHIRD_PARTY_DIR=..\OSG_INSTALL -DCMAKE_INSTALL_PREFIX=../OSG_INSTALL - cmake --build . -j 16 -t install --config Release - -## 特性 -在安装目录bin文件夹下，以cmd模式运行。 -### 大体量点云显示: - osgviewer ../assets/PointExtractor.potree - -### 局部点云提取: - pointCloudExtractor --potree ../assets/PointExtractor --cubepath ../assets/PointExtractor/box.txt --outpath ../assets/PointExtractor/out.txt \ No newline at end of file + + +# osgPotree + +osgPotree 是一个基于 OpenSceneGraph（OSG）开发的插件，能够直接加载由 PotreeConverter 2.0 生成的点云数据。该项目为 OSG 用户提供了便捷的点云渲染支持，并集成了点云编辑、目标识别等一系列相关辅助工具。 + +本代码库包含用于构建 osgPotree 库的 C++ 头文件、源文件以及 CMake 构建脚本。当前仅依赖 OpenSceneGraph。秉持 OpenSceneGraph 的一致性设计原则，该软件支持在 Linux、Windows、Android、macOS 等主流操作系统下构建运行。 + +## 项目特性 + +### 核心功能 + +**点云格式支持** +- **Potree 格式**：完整支持 PotreeConverter 2.0 生成的点云数据，包括层级结构解析、动态加载、视锥体裁剪等功能 +- **COPC 格式**：支持 Cloud Optimized Point Cloud 格式，这是一种经过优化的点云格式，适合大规模点云数据的 web 端可视化 + +**点云渲染** +- 基于 OSG 的高效点云渲染管线 +- 支持多细节层次（LOD）动态加载 +- 视锥体裁剪优化，减少不必要的渲染开销 +- 支持大体量点云数据的流畅显示 + +**点云处理工具** +- **pointCloudExtractor**：提供局部点云提取功能，支持从大体量点云中提取指定立方体区域内的点云数据 +- 支持将提取结果输出为标准格式，便于后续分析和处理 + +### 技术实现 + +**osgPotree 插件** +- 使用层次化节点（HNode）结构管理点云数据 +- 支持八叉树（Octree）空间索引 +- 灵活的属性（Attributes）系统，支持多种点属性格式 +- 基于 PagedLOD 的动态数据加载机制 + +**osgCopc 插件** +- 支持 COPC 格式的分层页面（HPage）结构 +- 高效的 VoxelKey 空间索引 +- 异步点数据加载，支持大数据集处理 +- 支持 LAZ（Laszip）压缩格式的点云数据 + +## 环境准备 + +### 必要依赖 + +**编译器要求** +- 支持 C++11 标准的编译器 +- 推荐版本：g++ 4.8.1 或更高版本、Clang 3.3 或更高版本、Visual Studio 2017 或更高版本 + +**构建工具** +- CMake 3.7 或更高版本 +- Git 版本控制工具 + +**核心依赖** +- OpenSceneGraph 3.4.0 或更高版本 + - 官方仓库：https://github.com/openscenegraph/OpenSceneGraph.git + - 推荐使用预编译版本或从源码编译安装 + +### 可选依赖 + +- **LASzip**：用于支持 LAZ 压缩格式（COPC 格式必需） +- **OpenGL**：操作系统提供的图形驱动支持 + +## 命令行编译指南 + +### Linux/macOS 平台 + +```bash +# 1. 克隆源码 +git clone https://gitee.com/osg_opensource/osg-potree.git +cd osg-potree + +# 2. 创建构建目录 +mkdir build +cd build + +# 3. 配置 CMake（请根据实际 OSG 安装路径调整 THIRD_PARTY_DIR） +cmake .. \ + -DCMAKE_BUILD_TYPE=Release \ + -DTHIRD_PARTY_DIR=/path/to/osg_install \ + -DCMAKE_INSTALL_PREFIX=/path/to/osg_install + +# 4. 编译并安装 +cmake --build . -j $(nproc) +cmake --install . +``` + +### Windows 平台 + +```cmd +:: 1. 克隆源码 +git clone https://gitee.com/osg_opensource/osg-potree.git +cd osg-potree + +:: 2. 配置 CMake（请根据实际 OSG 安装路径调整） +cmake . ^ + -DCMAKE_BUILD_TYPE=Release ^ + -DTHIRD_PARTY_DIR=..\OSG_INSTALL ^ + -DCMAKE_INSTALL_PREFIX=../OSG_INSTALL + +:: 3. 编译并安装 +cmake --build . -j 16 --config Release --target install +``` + +**注意**：请确保 OSG 库已正确安装，并将安装目录下的 bin 文件夹添加到系统 PATH 环境变量中，以便运行时能够找到 OSG 动态链接库。 + +## 使用方法 + +### 大体量点云显示 + +使用 osgviewer 加载 Potree 或 COPC 格式的点云数据： + +```bash +# 加载 Potree 格式点云 +osgviewer ../assets/PointExtractor.potree + +# 加载 COPC 格式点云 +osgviewer ../assets/pointCloud.copc.laz +``` + +### 局部点云提取 + +使用 pointCloudExtractor 工具从点云中提取指定立方体区域内的点： + +```bash +pointCloudExtractor \ + --potree ../assets/PointExtractor \ + --cubepath ../assets/PointExtractor/box.txt \ + --outpath ../assets/PointExtractor/out.txt +``` + +**参数说明** +- `--potree`：指定 Potree 点云数据目录路径 +- `--cubepath`：指定立方体定义文件路径（包含立方体的角点和轴向信息） +- `--outpath`：指定输出文件路径（提取结果将保存为此文件） + +### 立方体定义文件格式 + +立方体定义文件（box.txt）应包含以下信息，每行一个三维向量： + +``` +corner_x corner_y corner_z +x_axis_x x_axis_y x_axis_z +y_axis_x y_axis_y y_axis_z +z_axis_z z_axis_y z_axis_z +``` + +其中： +- `corner`：立方体的一个角点坐标 +- `x_axis`、`y_axis`、`z_axis`：分别表示立方体三个边的方向向量 + +## 项目结构 + +``` +osg-potree/ +├── CMakeLists.txt # 主 CMake 配置文件 +├── CMakeModules/ # CMake 辅助模块 +│ └── FindOSG.cmake # OSG 库查找脚本 +├── README.md # 项目说明文档 +├── LICENSE # 开源许可证 +├── assets/ # 示例数据目录 +│ ├── PointExtractor.potree # Potree 格式示例点云 +│ └── PointExtractor/ # PointExtractor 示例数据 +│ ├── box.txt # 立方体定义文件 +│ ├── hierarchy.bin # 层级结构文件 +│ ├── metadata.json # 元数据文件 +│ └── octree.bin # 八叉树数据文件 +├── osgPotree/ # Potree 格式支持插件 +│ ├── CMakeLists.txt +│ ├── PotreeView.cpp # 点云查看器主程序 +│ ├── ReaderWriterPotree.cpp # Potree 读写器实现 +│ ├── Attributes.h # 点属性定义 +│ └── json.hpp # JSON 处理库 +├── osgCopc/ # COPC 格式支持插件 +│ ├── CMakeLists.txt +│ └── ReaderWriterCopc.cpp # COPC 读写器实现 +└── pointCloudExtractor/ # 点云提取工具 + ├── CMakeLists.txt + ├── pointCloudExtractor.cpp # 主程序入口 + ├── ExtractVisitor.cpp # 节点遍历访问器 + ├── ExtractVisitor.h + ├── Extractor.h # 提取器基类 + ├── BoxExtractor.cpp # 立方体提取器实现 + └── BoxExtractor.h +``` + +## API 参考 + +### osgPotree 插件 + +**Container 类** +osgPotree 插件的核心数据结构，用于存储点云的分层节点信息和属性。 + +```cpp +// 创建 Container +osg::ref_ptr container = new Container(hNode, attributes); + +// 获取分层节点 +osg::ref_ptr node = container->node(); + +// 获取属性信息 +osg::ref_ptr attributes = container->attributes(); +``` + +**Attributes 类** +定义点云数据中包含的各种属性及其格式。 + +```cpp +// 属性类型枚举 +enum AttributeType { + INT8, INT16, INT32, INT64, + UINT8, UINT16, UINT32, UINT64, + FLOAT, DOUBLE, + UNDEFINED = 123456 +}; +``` + +### pointCloudExtractor 工具 + +**ExtractVisitor 类** +用于遍历场景图并收集点数据的访问器。 + +```cpp +// 创建提取访问器 +ExtractVisitor visitor(extractor, readCallback); + +// 设置数据库缓存回调 +visitor.setReadCallback(new DatabaseCacheReadCallback()); + +// 执行遍历 +node->accept(visitor); +``` + +**BoxExtractor 类** +从点云中提取指定立方体区域内的点数据。 + +```cpp +// 创建立方体提取器 +BoxExtractor extractor(corner, xAxis, yAxis, zAxis); + +// 执行提取 +extractor.extract(visitor); + +// 获取提取结果 +std::vector points = extractor.getPoints(); +``` + +## 详细信息链接 + +osgPotree 项目的详细功能特性、教程与设计文档，请访问以下链接获取： + +- **osgPotree 项目主页**：https://blog.csdn.net/CPWWHSU/article/details/157363010 +- **pointCloudExtractor 工具说明**：https://blog.csdn.net/CPWWHSU/article/details/157363010 + +## 贡献指南 + +欢迎社区贡献者参与项目开发。请遵循以下步骤： + +1. Fork 本仓库 +2. 创建您的功能分支（`git checkout -b feature/AmazingFeature`） +3. 提交您的更改（`git commit -m 'Add some AmazingFeature'`） +4. 推送到分支（`git push origin feature/AmazingFeature`） +5. 创建一个 Pull Request + +## 许可证 + +本项目采用 MIT 许可证开源。详情请参阅 LICENSE 文件。 + +## 版本兼容性 + +| osgPotree 版本 | OpenSceneGraph 版本 | 最低 C++ 标准 | +|----------------|---------------------|---------------| +| 1.0.x | 3.4.0+ | C++11 | + +**注意**：以上列出的版本均为经验证可用的版本。使用更早的版本进行构建也有可能成功。若您使用更旧的版本成功完成构建，请告知我们，以便更新版本信息。 \ No newline at end of file -- Gitee