文档目的说明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 连接、加载修正文件。如果放在主线程界面会卡死。用QThreadmoveToThread把LidarWorker移到工作线程执行UI 保持流畅。三、LidarWorker 封装层核心LidarWorker是整个封装的关键把禾赛 SDK 包成三个简单操作3.1 对外接口接口类型作用start()槽函数启动 SDK加载配置 → 初始化 → 连接雷达requestCapture()槽函数请求保存下一帧设置标志位frameUpdated信号每帧触发通知 UI 更新帧数/点数frameCaptured信号一帧保存完成通知 UI 弹提示statusChanged信号连接状态变化通知3.2 关键成员classLidarWorker:publicQObject{private:HesaiLidarSdkLidarPointXYZICRT*sdk_;// 禾赛 SDK 实例std::atomicboolcapture_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(constLidarDecodedFrameframe){// 每帧都更新状态栏实时性emitframeUpdated(frame.points_num,frame.frame_index);// 检查是否有采集请求if(capture_flag_.load()frame.points_num0){capture_flag_false;// 立刻复位防止存多帧QString pathsaveFrameAsPCD(frame);emitframeCaptured(path,frame.points_num);// 通知主线程}}4.3 工作时序时间 → SDK 后台: ─帧─帧─帧─帧─帧─帧─帧─帧─帧─帧─→ (每秒10帧) ↓ 回调检查: flag0 flag0 flag1 flag0(存!) flag0 ... ↑ 用户点击: 点击按钮→flag1 ↓ 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 头部ofsVERSION 0.7\nFIELDS x y z intensity confidence ring\nWIDTH frame.points_num\nDATA ascii\n;// 遍历点数组for(uint32_ti0;iframe.points_num;i){ofspts[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 停止八、构建与运行依赖组件版本Qt5.15.2 (msvc2019_64)Visual Studio2019/2022HesaiLidar_SDK_2.0v2.0.12编译cdqt_capture/build cmake-GVisual Studio 17 2022-Ax64..cmake--build.--configRelease运行cdbuild/ReleasesetPATHC:\Qt\5.15.2\msvc2019_64\bin;%PATH% qt_capture.exe九、常见问题问题原因解决方案界面中文乱码源文件编码CMake 加/utf-8选项源文件存 UTF-8 BOM一直显示正在连接端口被占用或雷达异常taskkill /IM qt_capture.exe /F重启雷达收不到数据雷达未发数据或端口不对用 PowerShell UDP 监听验证检查 config.ini 端口关闭后下次连不上僵尸进程占端口用窗口 X 正常关闭勿强制结束十、扩展指南连续保存多帧修改回调去掉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 自动识别协议。