折根妙妙屋

1.1 什么是 CloudCompare#

CloudCompare 是一款由法国电力集团研发部门（EDF R&D）和巴黎 Telecom 联合维护的开源 3D 点云与网格处理软件，采用 GPL v2 许可证。它提供了点云可视化、分割、测量、配准、重建等一整套功能，在测绘、BIM、工业检测领域用得极广。

它的核心架构大致可以拆成几块：

1.2 我们项目里的 NsCCLib 是什么#

在公司项目中，NsCCLib 看起来是把 CloudCompare 的 CCDb 以及部分核心库抽出来、重新命名空间后封装成的内部基础库。文件命名依然保留了 CC 的 cc 前缀（如 ccHObject、ccGenericPointCloud），但可能经过了裁剪或增补，以适配业务需求。

这意味着：

1. 接口风格要对齐：我后续写的车厢分割模块，如果也要挂进这个项目，最好遵循 ccXXX 的命名习惯和 QCC_DB_LIB_API 式的导出宏设计。
2. 数据类型要兼容：点云输入可能不是裸的 PCL pcl::PointCloud，而是 CC 的 ccPointCloud 或 ccGenericPointCloud。
3. 许可证要注意：GPL v2 具有传染性。如果我的算法以独立进程或独立 DLL 的形式存在，不链接 CC 的 GPL 代码，则可以保持闭源；如果直接修改 CC 源码并随软件分发，则修改部分需开源。具体怎么集成，需要后续和主管确认架构方案。

1.3 主管让我学什么#

主管的原话是让我看 CCDb 里 .h 文件的接口设计。翻译一下，核心就这几点：

• 导出宏的包装：看 QCC_DB_LIB_API 是怎么用条件编译切换 dllexport/dllimport 的。
• 基类与继承体系：看 ccHObject 怎么当”万物之父”，以及 ccGenericPointCloud 这类抽象基类怎么定义接口。
• Qt 的融合：看 CC 怎么在算法层使用 QString、QRect 等 Qt 类型，而不是裸 std::string。
• 多继承与接口分离：看一个类怎么同时继承实体基类和交互接口（如 cc2DLabel : public ccHObject, public ccInteractor）。

3.1 #pragma once是什么？#

防止头文件被重复包含，避免编译报错。

1
#include "carriage_api.h"
2

3
// carriage_impl.cpp
4
#include "carriage_api.h"
5

6
// test.cpp
7
#include "carriage_api.h"

1
error C2011: "ISegmentor": "class" 类型重定义

1
#ifndef CARRIAGE_API_H      // 如果没定义这个宏
2
#define CARRIAGE_API_H      // 那就定义它
3
// ... 头文件内容 ...
4
#endif                      // 结束

1
#pragma once          ← 第 1 行
2

3
// 版权注释
4
// include 其他头文件
5
// 类声明...

3.2 导出宏#

导出宏就是 Windows DLL 的”开关”：编译 DLL 时它把符号推出去，别人用 DLL 时它把符号拉进来。没有它，你的类/函数对别人不可见。

1
// carriage_export.h  （建议单独一个文件，或放在 carriage_api.h 顶部）
2

3
#pragma once
4

5
// 关键：编译你的 DLL 项目时，VS 项目属性里预处理器定义了 CARRIAGE_EXPORTS
6
// 所以编译 DLL 时走 #ifdef 分支，用 dllexport
7
// 主管编译主程序时，没定义 CARRIAGE_EXPORTS，走 #else 分支，用 dllimport
8

9
#ifdef CARRIAGE_EXPORTS
10
    #define CARRIAGE_API __declspec(dllexport)
11
#else
12
    #define CARRIAGE_API __declspec(dllimport)
13
#endif

3.3 具体怎么用#

Step 1：定义宏（一次）

创建 carriage_export.h：

1
#pragma once
2

3
#ifdef CARRIAGE_EXPORTS
4
    #define CARRIAGE_API __declspec(dllexport)
5
#else
6
    #define CARRIAGE_API __declspec(dllimport)
7
#endif

Step 2：给要暴露的类/函数”挂牌”

在 carriage_api.h 里：

1
#include "carriage_export.h"
2

3
namespace CarriageSegment {
4

5
// 类前面挂 CARRIAGE_API，表示"这个类要导出到 DLL 外"
6
class CARRIAGE_API ISegmentor {
7
public:
8
    virtual bool Initialize(const std::string& config_path) = 0;
9
    virtual float Process(const std::string& pcd_path) = 0;
10
    virtual void Release() = 0;
11
    virtual ~ISegmentor() = default;
12
};
13

14
// 工厂函数也要挂牌
15
extern "C" CARRIAGE_API ISegmentor* CreateSegmentor();
16

17
} // namespace

3.4 CloudCompare 里怎么写的（对照）#

你之前看的 cc2DLabel.h 里：

1
class QCC_DB_LIB_API cc2DLabel : public ccHObject...

QCC_DB_LIB_API 就是 CC 的导出宏，定义在某个 ccLibDefines.h 里：

1
#ifdef QCC_DB_LIB_BUILD
2
    #define QCC_DB_LIB_API __declspec(dllexport)
3
#else
4
    #define QCC_DB_LIB_API __declspec(dllimport)
5
#endif

3.5 我的产出动作#

看完 cc2DLabel.h 的前 50 行后，立刻在我的 CarriageAlgoTest 项目里新建 carriage_api.h，照抄这个结构：

1
#pragma once
2

3
// 1. 导出宏（照抄 QCC_DB_LIB_API 的模式）
4
#ifdef CARRIAGE_EXPORTS
5
    #define CARRIAGE_API __declspec(dllexport)
6
#else
7
    #define CARRIAGE_API __declspec(dllimport)
8
#endif
9

10
// 2. include 顺序：本地 → 第三方 → 标准库
11
// （先空着，后续需要再加）
12

13
// 3. 命名空间（学 CC 的 namespace 风格）
14
namespace CarriageSegment {
15

16
// 4. 前向声明（如果有复杂类型，先声明不 include）
17
class IAlgorithm;  // 占位
18

19
// 5. 你的接口类骨架（仿 cc2DLabel 的继承风格）
20
class CARRIAGE_API ISegmentor {
21
public:
22
    // 构造函数/析构函数
23
    ISegmentor() = default;
24
    virtual ~ISegmentor() = default;
25

26
    // 生命周期三段式（仿 CC 的 Init/Process/Release 套路）
27
    virtual bool Initialize(const std::string& config_path) = 0;
28
    virtual float Process(const std::string& pcd_path) = 0;
29
    virtual void Release() = 0;
30
};
31

32
} // namespace CarriageSegment

4.1 ccHObject 的核心骨架#

打开 ccHObject.h，别被长度吓到，找这 4 个特征：

你的学习重点：虚析构函数 + 纯虚接口 + 克隆接口。父子树是 CC 做界面用的，你不用抄。

4.2 映射到你的车厢模块：哪些要抄，哪些不要#

4.3 你的 ISegmentor 基类代码（直接复制用）#

1
#pragma once
2
#include "carriage_export.h"
3
#include <string>
4

5
namespace CarriageSegment {
6

7
// 配置结构体（仿 CC 的 metaData，但更简单）
8
struct CarriageConfig {
9
    float voxel_size = 0.05f;       // 体素大小
10
    float min_height = 0.3f;        // 车厢最低高度（过滤地面）
11
    float max_height = 4.5f;        // 车厢最高高度
12
    int min_cluster_size = 100;     // 最小聚类点数
13
    std::string model_path;         // 模型路径（如果有深度学习模型）
14
};
15

16
// 结果结构体
17
struct CarriageInfo {
18
    float volume_m3 = 0.0f;         // 体积
19
    float length = 0.0f;            // 长
20
    float width = 0.0f;             // 宽
21
    float height = 0.0f;            // 高
22
    bool success = false;
23
    std::string error_msg;
24
};
25

26
// 基类接口（仿 ccHObject 的纯虚接口设计）
27
class CARRIAGE_API ISegmentor {
28
public:
29
    // 1. 虚析构函数（必须！抄 ccHObject 的 ~ccHObject()）
30
    virtual ~ISegmentor() = default;
31

32
    // 2. 生命周期三段式（纯虚，强制子类实现）
33
    virtual bool Initialize(const CarriageConfig& config) = 0;
34
    virtual CarriageInfo Process(const std::string& pcd_file_path) = 0;
35
    virtual void Release() = 0;
36

37
    // 3. 克隆接口（可选，仿 ccHObject::clone）
38
    // 如果你需要"保存当前配置，复制一份去处理下一帧"，就加上
39
    // virtual ISegmentor* Clone() const = 0;
40

41
    // 4. 信息接口（仿 ccHObject::toString，调试用）
42
    virtual std::string GetVersion() const { return "1.0.0"; }
43
};
44

45
// 工厂函数（仿 CC 的 Create 模式，外部用这行创建对象）
46
extern "C" CARRIAGE_API ISegmentor* CreateSegmentor();
47

48
} // namespace CarriageSegment

4.4 为什么这样设计（逐行解释）#

4.5 实现类怎么写（对应 ccHObject 的子类如 ccPointCloud）#

1
#pragma once
2
#include "carriage_api.h"
3

4
namespace CarriageSegment {
5

6
// 实现类（仿 ccPointCloud 继承 ccHObject）
7
class CARRIAGE_API SegmentorImpl : public ISegmentor {
8
public:
9
    SegmentorImpl() = default;
10
    ~SegmentorImpl() override;  // override 关键字，编译器帮你检查是否真的覆盖了基类虚函数
11

12
    bool Initialize(const CarriageConfig& config) override;
13
    CarriageInfo Process(const std::string& pcd_file_path) override;
14
    void Release() override;
15

16
    std::string GetVersion() const override { return "1.0.0-pcl"; }
17

18
private:
19
    CarriageConfig config_;       // 保存配置
20
    bool is_initialized_ = false; // 状态标记
21
    // 后续加 PCL 成员变量
22
};
23

24
} // namespace

注意 override 关键字：这是现代 C++11 特性，写在子类虚函数后面，编译器会检查”基类里到底有没有这个虚函数”。如果基类函数签名写错了，override 会直接编译报错，防止你”以为覆盖了，其实没覆盖”的隐藏 bug。

4.6 你现在立刻做的#

1. 在 VS/VS Code 里打开 ccHObject.h，找到：

   • virtual ~ccHObject(); 在哪一行？
   • clone() 函数怎么声明的？
   • 有没有 override 关键字？（CC 可能用旧标准没有，但你的项目应该用）

2. 把上面的 carriage_api.h + carriage_impl.h 复制进你的项目。

3. 创建 carriage_impl.cpp，写空实现（返回假数据），编译测试：

   1
   #include "carriage_impl.h"
   2
   
   3
   namespace CarriageSegment {
   4
   
   5
   SegmentorImpl::~SegmentorImpl() {
   6
       Release();
   7
   }
   8
   
   9
   bool SegmentorImpl::Initialize(const CarriageConfig& config) {
   10
       config_ = config;
   11
       is_initialized_ = true;
   12
       return true;
   13
   }
   14
   
   15
   CarriageInfo SegmentorImpl::Process(const std::string& pcd_file_path) {
   16
       CarriageInfo info;
   17
       info.volume_m3 = 42.0f;  // 假数据
   18
       info.success = true;
   19
       return info;
   20
   }
   21
   
   22
   void SegmentorImpl::Release() {
   23
       is_initialized_ = false;
   24
   }
   25
   
   26
   ISegmentor* CreateSegmentor() {
   27
       return new SegmentorImpl();
   28
   }
   29
   
   30
   } // namespace

4. 修改 main.cpp 调用：

   1
   #include "carriage_api.h"
   2
   #include <iostream>
   3
   
   4
   int main() {
   5
       CarriageSegment::ISegmentor* seg = CarriageSegment::CreateSegmentor();
   6
   
   7
       CarriageSegment::CarriageConfig cfg;
   8
       cfg.voxel_size = 0.05f;
   9
   
   10
       if (seg->Initialize(cfg)) {
   11
           auto result = seg->Process("test.pcd");
   12
           std::cout << "Volume: " << result.volume_m3 << std::endl;
   13
       }
   14
   
   15
       seg->Release();
   16
       delete seg;  // 工厂创建，外部释放。后续可改用智能指针
   17
   
   18
       return 0;
   19
   }

5. 编译：Ctrl + Shift + B。如果报错，把错误信息发给我。

这套代码跑通后，你的接口骨架就完整了。后续只需要往 SegmentorImpl::Process() 里填 PCL 算法逻辑，接口纹丝不动。

跑通了告诉我，进入 Step 3：数据结构定义（看 ccGenericPointCloud 怎么抽象点云容器）。