文档目的

说明qt_capture程序如何封装禾赛HesaiLidar_SDK_2.0，实现"点击按钮采集一帧点云"的功能。帮助快速理解架构、维护和扩展。

一、程序概览

功能

• 启动后自动连接禾赛 QT128C2X 雷达
• 实时显示帧数、点数、连接状态
• 点击"采集一帧"按钮 → 保存当前一帧点云为 PCD 文件

文件结构

qt_capture/ ├── CMakeLists.txt # 构建配置（链接 SDK + Qt） ├── config.ini # 雷达连接配置（IP/端口） ├── main.cpp # 程序入口 ├── MainWindow.h/.cpp # 主窗口界面 ├── LidarWorker.h/.cpp # SDK 封装层（核心） └── pointcloud_output/ # PCD 输出目录

二、整体架构

程序采用双线程 + 信号槽架构，UI 与数据采集分离：

┌─────────────────────────────────────────────────┐ │ 主线程 (UI 线程) │ │ │ │ MainWindow │ │ ├── 界面控件 (按钮/状态标签) │ │ ├── 按钮点击 → 调用 worker->requestCapture() │ │ └── 接收信号 → 更新界面 │ │ │ └───────────────────▲─────────────────────────────┘ │ Qt 信号/槽 (跨线程队列) ┌───────────────────┴─────────────────────────────┐ │ 工作线程 (QThread) │ │ │ │ LidarWorker ← SDK 封装层 │ │ ├── 管理一个 HesaiLidarSdk 实例 │ │ ├── 注册回调函数 │ │ └── 通过 emit 信号通知主线程 │ │ │ │ ┌────────────────────┐ │ │ │ HesaiLidarSdk │ │ │ │ (禾赛官方 SDK) │ │ │ │ 内部自带收数线程 │ │ │ └────────────────────┘ │ └─────────────────────────────────────────────────┘

为什么需要工作线程？

禾赛 SDK 的Init()和Start()会阻塞等待 PTC 连接、加载修正文件。如果放在主线程，界面会卡死。用QThread+moveToThread把LidarWorker移到工作线程执行，UI 保持流畅。

三、LidarWorker 封装层（核心）

LidarWorker是整个封装的关键，把禾赛 SDK 包成三个简单操作：

3.1 对外接口

3.2 关键成员

classLidarWorker:publicQObject{private:HesaiLidarSdk<LidarPointXYZICRT>*sdk_;// 禾赛 SDK 实例std::atomic<bool>capture_flag_;// 采集请求标志（线程安全）std::string output_dir_;// PCD 输出目录};

3.3 启动流程start()

start() │ ├─ 1. 读 config.ini → DriverParam ├─ 2. 创建 SDK 实例：sdk_ = new HesaiLidarSdk() ├─ 3. 初始化：sdk_->Init(param) ├─ 4. 注册点云回调：sdk_->RegRecvCallback(...) ├─ 5. 启动：sdk_->Start() ← SDK 内部开线程收 UDP └─ 6. emit statusChanged("已连接")

四、核心机制：标志位 + 回调

这是整个封装最巧妙的设计。

4.1 问题

禾赛 SDK 是持续推数据模型 — 启动后每秒发 10 帧到回调函数。但用户需求是点击才存一帧。

4.2 解决方案

用一个原子标志位capture_flag_作为"开关"：

// ① 用户点击按钮 → 只设标志（瞬时操作，不阻塞）voidLidarWorker::requestCapture(){capture_flag_=true;}// ② SDK 每收到一帧都进这里voidLidarWorker::onFrameCallback(constLidarDecodedFrame&frame){// 每帧都更新状态栏（实时性）emitframeUpdated(frame.points_num,frame.frame_index);// 检查是否有采集请求if(capture_flag_.load()&&frame.points_num>0){capture_flag_=false;// 立刻复位，防止存多帧QString path=saveFrameAsPCD(frame);emitframeCaptured(path,frame.points_num);// 通知主线程}}

4.3 工作时序

时间 → SDK 后台: ─帧─帧─帧─帧─帧─帧─帧─帧─帧─帧─→ (每秒10帧) ↓ 回调检查: flag=0 flag=0 flag=1 flag=0(存!) flag=0 ... ↑ 用户点击: 点击按钮→flag=1 ↓ emit frameCaptured → UI弹框

优点：

• SDK 持续运行，无需反复建连/断开
• 点击后最多等 100ms（下一帧）即保存
• 标志位用std::atomic保证线程安全

五、跨线程通信

SDK 回调运行在SDK 内部线程，界面在主线程。通过 Qt 信号槽安全通信：

// MainWindow 构造函数中连接信号connect(worker_,&LidarWorker::frameUpdated,this,&MainWindow::onFrameUpdated,Qt::QueuedConnection);// ← 关键：跨线程自动排队

工作原理

Qt::QueuedConnection让信号在接收线程（主线程）的事件队列里执行，Qt 自动处理线程安全。因此回调函数里可以直接emit，不必担心 UI 操作的线程冲突。

六、PCD 保存

saveFrameAsPCD()把一帧点云写成标准 PCD v0.7 格式：

// 写 PCD 头部ofs<<"VERSION 0.7\n"<<"FIELDS x y z intensity confidence ring\n"<<"WIDTH "<<frame.points_num<<"\n"<<"DATA ascii\n";// 遍历点数组for(uint32_ti=0;i<frame.points_num;++i){ofs<<pts[i].x<<" "<<pts[i].y<<" "<<pts[i].z<<" "<<(int)pts[i].intensity<<" "<<(int)pts[i].confidence<<" "<<pts[i].ring<<"\n";}

文件命名：frame_<时间戳>_<序号>.pcd，避免重复点击覆盖。

七、界面交互流程

程序启动 │ ├─ 创建 LidarWorker，移到工作线程 ├─ 线程启动 → worker->start() │ └─ 连接雷达（按钮禁用，状态："正在连接..."） │ ├─ 收到第一帧 → emit frameUpdated │ └─ 按钮启用，状态："已连接"，显示帧数/点数 │ ├─ 用户点击按钮 → worker->requestCapture() │ └─ 状态："采集请求已发送，等待下一帧..." │ ├─ 下一帧回调 → 存 PCD → emit frameCaptured │ └─ 弹出成功框，显示文件路径 │ └─ 用户关闭窗口 → 退出工作线程 → SDK 停止

八、构建与运行

依赖

编译

cdqt_capture/build cmake-G"Visual Studio 17 2022"-Ax64..cmake--build.--configRelease

运行

cdbuild/ReleasesetPATH=C:\Qt\5.15.2\msvc2019_64\bin;%PATH% qt_capture.exe

九、常见问题

十、扩展指南

连续保存多帧

修改回调，去掉capture_flag_复位或加帧数计数：

if(capture_flag_){saveFrameAsPCD(frame);if(++saved_count_>=target_count_){// 存够 N 帧capture_flag_=false;}}

添加实时可视化

在MainWindow添加 OpenGL Widget，收到frameCaptured信号后渲染点云（需引入 PCL 或自写 OpenGL）。

改用其他雷达型号

只需改config.ini中的device_ip_address、udp_port和 correction 文件路径，代码无需改动（SDK 自动识别协议）。