# SGPointCloud

**Repository Path**: lurkerwzc/sgpoint-cloud

## Basic Information

- **Project Name**: SGPointCloud
- **Description**: pcl点云库wrapper，提取为单独的库方便不同项目快速搭建所需算法。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2022-06-09
- **Last Updated**: 2025-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 总览

pcl的一个自用wrapper库，用于pcl库的简化使用，同时为各基础算法提供参数序列化和可视化封装，方便后续有需要快速搭建点云算法。同时本文档也是作为点云算法学习过程的梳理。

考虑到兼容性（本工程大量依赖第三方开源库）和未来可能出现的linux环境部署需求，本项目并未直接使用**Visual Studio**自带的工具链做项目管理，而是使用**cmake**配置跨平台的开发环境和项目管理，用c++包管理工具**vcpkg**统一管理第三方开源库（**vcpkg**是windows平台下的C++包管理工具，如需linux部署，可使用linux下的任意c++包管理工具），**cmake**本身可根据需要自动生成**Visual Studio**的项目工程文件如 .vsproj、.sln 等文件，并且从**Visual Studio 2015**开始也支持直接对**cmake**项目进行开发，具体可参考[链接](https://docs.microsoft.com/zh-cn/cpp/build/cmake-projects-in-visual-studio?view=msvc-140)。

本工作目录旨在建立跨平台编译的cpp工程，尽量少的减少操作系统依赖。目前除了可视化模块部分涉及到Windows依赖，算法部分只有第三方开源库依赖，无操作系统依赖，方便直接在linux环境下编译部署。

本项目中涉及到的第三方开源库除了**hnswlib**为纯头文件库，直接包含在3rd子目录中，其他各库推荐由**c++包管理工具**（如windows下的**vcpkg**、linux下的**Conan**等）统一管理，方便在**CMakeLists.txt**文件中用**find_package**函数进行自动导入并配置相关的头文件目录、bin目录和lib目录。

本工作目录下各模块及开发环境的依赖关系如下图所示：

![模块依赖关系](doc/依赖图.png)

整个工程架构分为四层，以期减少模块耦合，提高代码复用，避免不同项目的重复开发工作。其中数学算法层皆为第三方开源库，本项目的主要开发内容集中在点云算法层、项目算法层和接口层上。由于项目算法层和接口层涉及具体公司项目，不对外开源，本工程目录主要局限于sgpcl模块。

<br>

# 1. 数学算法层

[使用的第三方库列表](doc/数学算法层.md)

# 2. 点云算法层

## 2.1 [pcl](https://pointclouds.org/)（Point Cloud Library）库

第三方开源点云算法库，[BSD](https://codedocs.org/what-is/bsd-licenses)协议，类似于3D版本的OpenCV，主要提供各种三维点云数据的底层算法支持。
该库所有算法分成了12个模块，分别为：滤波、特征值计算、关键点提取、配准、kdtree搜索、octree搜索、点云分割、一致性采样（拟合）、表面构建、模式识别、IO和可视化。

## 2.2 sgpcl模块

[<font size=5>**算法文档**</font>](doc/sgpcl.md)（**点云底层算法说明文档，建议优先阅读**）

[sgpcl子目录](/sgpcl)

对pcl库的wrapper，主旨是为了简化pcl库的算法使用，并将算法本身、算法参数及序列化、算法可视化进行封装处理。
包含常用的点云底层算法，如滤波、下采样、拟合等，以类的形式提供给不同项目客户程序使用，并且提供了配套的参数配置方法和可视化方法方便算法调试。

# 3. 项目算法层

这里**项目算法**的意思是**针对不同的工程问题，选择合适的点云算法和算法组合，对目标点云进行处理的更高一层的算法**。例如掌子面识别算法，就是通过点云拟合、分割等底层算法的组合，实现掌子面上结构面的识别、分组功能，并计算同组结构面的间距、JRC等参数；而隧道扫描点云的处理算法，关注的是每环扫描断面的坐标配准、断面识别、侵入点云提取等功能，使用的底层算法更多是配准、凸包计算、多边形包含等算法。

点云算法的一大特点是每个底层算法都有各自的算法内参数，某些内参数针对特定的工程问题可能具有较为明确的物理意义，但更一般的情况下内参数只具有数学意义而不具有物理意义，对于这些内参数只能基于大量算例进行率定（俗称调参），因此，该层工作不仅包括点云数据的处理流程的尝试和编写，也包括算法的参数率定工作。

其中，掌子面算法又分为1.0和2.0（开发中）版本。

## 3.1 掌子面识别算法1.0模块

[<font size=5>**算法文档**</font>](doc/掌子面算法1.0.md)

[sgtunnelface1.0子目录](/sgtunnelface1.0)

掌子面自动识别算法流程1.0版本。该模块最初是直接对同济教室的matlab代码进行的cpp实现，因此该库除了依赖**Eigen**库矩阵运算和**hnswlib**库做空间搜索，其他算法均为自行编写并且由于该库最初目的只为了掌子面识别算法，因此既包括点云层算法，也包括掌子面识别算法，没有进行分开解耦处理。

### 3.1.1 掌子面分析算法模块

该模块算法流程与同济教研室的matlab代码基本一致。

### 3.1.2 二维出图模块

[visualization子目录](/sgtunnelface1.0/visualization)

该部分为宋树祥开发，该模块基于OpenCV实现数据的二维可视化能。代码具有一定的Windows依赖，如有跨平台需求则需对该模进行排查。且后期对展示数据的需求发生变化，但相应的出图代并未进行更新。因此这块功能有待进一步跟进，或是使用别的具/库来实现出图功能（例如pcl库自带的可视化模块）。

## 3.2 **掌子面识别算法2.0模块（开发中）**

[<font size=5>**算法文档**</font>](doc/岩壁剔除2.0.md)。

[sgtunnelface2.0子目录](/sgtunnelface2.0)

该库旨在完全基于pcl库提供的底层算法，达到与1.0库相似的目的。由于pcl库从算法专业程度、鲁棒性、计算效率及代码覆盖率上都远远高于自编代码，因此期望该库能够比1.0版本算法更为稳定，效率更高。

# 4. 接口层

[SGTFRecognizerAPI子目录](SGTFRecognizerAPI)

接口层主要对接掌子面只能识别算法模块和服务器端的C#代码，主要功能为来回对接的数据结构的相互解析、处理异常、打印分析状态等功能。其中又分为接口1.0版、2.0版（计划中，未进行）和1.5版本。

4.1 [1.0版本](SGTFRecognizerAPI/API1.0/)

处理掌子面识别算法1.0模块和服务器端C#代码的数据对接、异常处理等工作。

4.2 [2.0版本（待开发）](SGTFRecognizerAPI/API2.0/)

计划中待掌子面识别算法2.0模块完善之后，处理其和服务器端C#代码的对接。由于掌子面算法2.0版本只完成了点云预处理部分，因此该部分还未启动。

4.3 [1.5版本](SGTFRecognizerAPI/API1.5/)

虽然掌子面算法2.0版本尚未开发完成，但2.0版本的点云预处理（包括岩壁点云剔除功能、噪点剔除、坐标配准、下采样等工作）模块已经完成并获得比1.0版本更好的结果，因此将掌子面算法2.0版本的预处理模块和1.0版本的识别算法模块拼接，对外形成1.5版本的接口。

各接口版本对外保持一致，使得核心分析模块可以顺利从1.0转到1.5和未来的2.0，实现增量式开发，服务器端的C#代码不需做更改。基本接口函数为：
```cpp
extern "C" TYPALMFACEANALYSIS_API int __stdcall TYPF_TunnelFaceRecognizer(const char* strInputFile,
const char* strOutputPath, SAnalyseParam& faceData, SAnalyseSucess& faceSucess,
fCallback callBac);
```
其中形参`strInputFile`为输入点云obj文件路径，strOutputPath为输出文件夹路径，faceData为分析模块所需的输入参数，包括：
```cpp
    struct SAnalyseParam
    {
        float Height;           // 掌子面垂直尺寸（用于坐标率定）
        float Width;            // 掌子面水平尺寸（用于坐标率定）
        float fDipDirection;    // 掌子面倾向（角度）
        float fDipAngle;        // 掌子面倾角（角度）
        SBQParam bqParam;       // [BQ]值计算所需其他参数，包括岩体强度值、地下水、地应力等参数
        SGSIParam gsiParam;     // GSI值计算所需其他参数，目前无GSI计算需求，不起作用
        SRMRParam rmrParam;     // RMR值计算所需其他参数，目前无RMR计算需求，不起作用
    } 
```
`faceSucess`为计算输出数据：
```cpp
    struct SAnalyseSucess
    {
        float Jv; // 计算的Jv值
        float JRC; // 掌子面各结构面分组的平均粗糙度
        float RQD; // 计算的RQD值，目前只计算[BQ]，该项不起作用
        SBQResult bqResult; // 计算的BQ相关结果，
        SGSIResult gsiResult; // 计算的GSI相关结果，目前只计算[BQ]，该项不起作用
        SRMRResult rmrResult; // 计算的RMR相关结果，目前只计算[BQ]，该项不起作用

        SJointResult Joint1; // 第1组节理面(包括结构面组的间距、JRC)
        SJointResult Joint2; // 第2组节理面
        SJointResult Joint3; // 第3组节理面
        SJointResult Joint4; // 第4组节理面
        SJointResult Joint5; // 第5组节理面
    };

    struct SBQResult
    {
        float UCS;
        float Kv;
        float BQ;
        float BQModified;
        float K1;
        float K2;
        float K3;
    };
```