# PointCloudTools

**Repository Path**: qulee/point-cloud-tools

## Basic Information

- **Project Name**: PointCloudTools
- **Description**: 点云处理工具库
- **Primary Language**: C++
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-17
- **Last Updated**: 2026-08-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PointCloudTools

## 注意

README文件一直没有更新，相关用法请参考测试用例

C++17 网格点云处理、坐标变换、可视化、三维点云数据处理代码汇总

## 相关功能

- **C++17 标准**
- **使用 CMake 和 CPM** 进行项目管理和依赖处理
- **GridDataManager**: 线程安全的三维网格数据结构
- **GridDataTools**: 三维点云与网格数据转换、网格点云补全、模拟堆取料建模、GLTF/GLB 格式模型导出等方法
- **PointCloudTransformer**: 多关节坐标变换器，变换链
- **PointCloudTools**: 三维点云处理代码汇总，还没有整理
- **点云可视化**（通过 PointCloudDebugger）

## 组件

### 1. GridDataManager - 网格数据管理器

线程安全的三维网格数据管理器，支持高效的批量操作：

```cpp
#include <PointCloudTools/GridDataManager.h>

// 创建网格数据管理器
const size_t stockYardNum = 3;    // 场地数量
const size_t rowNum = 1000;       // 行数
const size_t colNum = 1000;       // 列数
auto gridManager = std::make_unique<GridDataManager>(stockYardNum, rowNum, colNum);

// 基本读写操作
(*gridManager)[0][10][20] = 123;  // 写入数据
short value = (*gridManager)[0][10][20];  // 读取数据

// 批量操作
short testData[10] = {0, 10, 20, 30, 40, 50, 60, 70, 80, 90};
gridManager->bulkSetRow(0, 5, testData, 10);  // 批量写入行数据
gridManager->bulkGetRow(0, 5, testData, 10);  // 批量读取行数据

// 批量读写多行数据
std::vector<std::vector<unsigned char>> blobList;
gridManager->bulkGetRows(0, 10, 15, blobList, 100);  // 读取多行
gridManager->bulkSetRows(0, 10, blobList, 100);      // 写入多行
```

### 2. GridDataTools - 网格数据处理工具

提供点云与网格数据转换、补全、建模等功能：

```cpp
#include <PointCloudTools/GridDataTools.h>
#include <pcl/io/pcd_io.h>

// 创建网格数据工具
const size_t stockYardNum = 1;
const size_t rowNum = 1000;
const size_t colNum = 1000;
const float grid_interval = 0.2f;  // 网格间隔(米)
auto tools = std::make_unique<GridDataTools>(stockYardNum, rowNum, colNum, grid_interval);

// 读取点云数据
auto cloud = std::make_shared<pcl::PointCloud<pcl::PointXYZ>>();
pcl::io::loadPCDFile("test.pcd", *cloud);

// 点云转网格数据
tools->getGridDataFrmPointCloud(cloud, *(tools->PileData), 0, rowNum, colNum);

// 网格数据补全（基于止息角）
tools->completeGridData(*(tools->PileData), 0, rowNum, colNum, 35.6f);

// 网格数据插值补全
tools->completeGridDataByInterpolation(
    *(tools->PileData), 0, rowNum, colNum,
    0,     // 插值方法（0: IDW, 1: RBF, 2: 自适应混合）
    8.0f,  // 搜索半径
    0.6f,  // 平滑因子
    12     // 最大迭代次数
);

// 堆料模型生成
auto stackResult = tools->stackingModel(
    0,          // 场地索引
    50.0,       // 堆积中心点X坐标(米)
    50.0,       // 堆积中心点Y坐标(米)
    10.0,       // 堆积高度(米)
    37.0,       // 止息角(度)
    0.0, 0.0    // X,Y偏移量(米)
);

// 取料模型生成
auto reclaimResult = tools->reclaimingModel(
    0,          // 场地索引
    50.0, 50.0, 1.0,  // 设备位置XYZ(米)
    45.0,       // 回转角度(度)
    10.0,       // 俯仰角度(度)
    45.0,       // 臂长(米)
    0.5, 0.5,   // 左右宽度(米)
    0.1         // 臂厚(米)
);

// 生成GLTF模型文件
tools->generateGLTFWithTinyGLTF(
    "terrain.gltf",   // 输出路径
    0,                // 场地索引
    0, rowNum-1,      // 起始行、结束行
    0, colNum-1,      // 起始列、结束列
    0.2,              // 网格间隔
    5                 // 采样步长
);

// 生成圆形堆料GLTF
tools->generateCircularPileGLTF(
    "circular_pile.gltf",  // 输出路径
    0,                     // 场地索引
    rowNum/2, colNum/2,    // 圆心坐标
    100.0,                 // 半径
    0.0, 360.0,           // 起始角、结束角
    0.2, 1                // 网格间隔、采样步长
);
```

### 3. PointCloudTransformer - 点云坐标变换器

支持多关节变换链的坐标变换系统：

```cpp
#include <PointCloudTools/PointCloudTransformer.h>

using namespace PointCloudTransformers;

// 创建变换器
PointCloudTransformer transformer;

// 添加静态关节（基座）
int baseJoint = transformer.addJoint("Base",
    Eigen::Vector3f(0.0f, 0.0f, 5.0f),   // 平移向量
    Eigen::Vector3f(0.0f, 0.0f, 0.0f),   // 旋转角度(度)
    Joint::Type::STATIC
);

// 添加动态关节（回转台）
int turntableJoint = transformer.addJoint("Turntable",
    Eigen::Vector3f(0.0f, 0.0f, 45.0f),  // 绕Z轴旋转45度
    Eigen::Vector3f(0.0f, 0.0f, 0.0f),   // 平移向量
    Joint::Type::DYNAMIC
);

// 添加臂架关节
int armJoint = transformer.addJoint("Arm",
    Eigen::Vector3f(0.0f, 0.0f, 0.0f),
    Eigen::Vector3f(10.0f, 0.0f, 0.0f),  // 臂架延伸
    Joint::Type::STATIC
);

// 变换单个点
Eigen::Vector3f testPoint(1.0f, 0.0f, 0.0f);
Eigen::Vector3f transformedPoint = transformer.transformPoint(testPoint);

// 变换PCL点云
pcl::PointCloud<pcl::PointXYZ>::Ptr inputCloud(new pcl::PointCloud<pcl::PointXYZ>);
pcl::PointCloud<pcl::PointXYZ>::Ptr outputCloud(new pcl::PointCloud<pcl::PointXYZ>);
transformer.transformPointCloud(inputCloud, outputCloud);

// 更新动态关节参数
transformer.updateJointRotation(turntableJoint, Eigen::Vector3f(0.0f, 0.0f, 90.0f));

// 获取完整变换矩阵
Eigen::Matrix4f completeTransform = transformer.getCompleteTransformMatrix();

// 优化变换链（合并连续的静态关节）
transformer.optimizeTransformChain();
```

### 4. PointCloudTools - 综合点云处理工具

没整理完

## 依赖项

- **PCL 1.14.0** 或更高版本（点云处理库）
- **spdlog**（日志库）
- **nlohmann_json**（JSON处理库）
- **PointCloudDebugger v1.6**（点云可视化库）
- **Eigen3**（线性代数库）
- **httplib**

## 安装

1. 确保已安装 PCL 1.14.0 或更高版本
2. 在CMAKE项目中使用CPM引入库：
```
# 使用CPM
# 如果CPM.cmake不存在则自动下载
if(NOT EXISTS "${CMAKE_SOURCE_DIR}/cmake/CPM.cmake")
    file(DOWNLOAD 
         "https://github.com/cpm-cmake/CPM.cmake/releases/latest/download/CPM.cmake"
         "${CMAKE_SOURCE_DIR}/cmake/CPM.cmake")
endif()
include("${CMAKE_SOURCE_DIR}/cmake/CPM.cmake")

# 查找并引入 PCL
set(PCL_DIR "C:/Program Files/PCL 1.14.1/cmake")

CPMAddPackage(
    NAME PointCloudTools
    GIT_REPOSITORY https://gitee.com/qulee/point-cloud-tools.git
    GIT_TAG v4.8 # 替换为需要的版本
    OPTIONS
        "BUILD_TESTS_ONLY=OFF"  # 不引入和构建测试用例
)
```
CMAKE + CPM 构建项目示例： https://gitee.com/qulee/cmake_-cpm_-sample.git

## 测试

项目包有完整的单元测试，具体用法看请测试代码：

```bash
# 运行所有测试
./build/bin/PointCloudToolsTests

# 测试覆盖的功能
# - GridDataManager: 基本读写、批量操作、边界条件
# - GridDataTools: 数据转换、补全、建模、GLTF生成
# - PointCloudTransformer: 关节管理、坐标变换、优化
# - PointCloudTools: 综合点云处理流程
```

## 注意事项

1. 别加入与对应组件无关的代码，注意保证方法的通用性。

## 贡献

欢迎提交问题和改进建议！请确保：
- 遵循 C++17 标准和 RAII 原则
- 添加相应的单元测试
- 使用现代 C++ 特性和智能指针
- 提供清晰的代码注释