# D330Viewer - D330M深度相机控制系统

## 项目简介

D330Viewer 是一个基于Qt6的深度相机控制和可视化系统，用于D330M深度相机的实时数据采集、处理和显示。系统采用OpenCL GPU加速进行点云计算，支持实时显示深度图像和3D点云。

## 技术栈

### 核心库版本
- **Qt6**: 6.10.1 (msvc2022_64)
- **PCL**: 1.15.1 (Point Cloud Library)
- **OpenCV**: 4.13.0
- **OpenCL**: 3.0 (GPU加速)
- **DkamSDK**: 1.6.83 (D330M相机SDK)

### 开发环境
- **操作系统**: Windows 10/11 (64位)
- **编译器**: Visual Studio 2026 (MSVC)
- **构建工具**: CMake 3.15+
- **GPU**: 支持OpenCL的GPU（NVIDIA/AMD/Intel）

## 快速开始

### 1. 环境准备

确保已安装以下软件：
- Visual Studio 2022 以上（包含C++桌面开发工作负载）
- CMake 3.15或更高版本
- 支持OpenCL的GPU驱动

### 2. 库依赖安装

**必需的库**：
- Qt6 6.10.1 (msvc2022_64)
- PCL 1.15.1
- OpenCV 4.13.0
- OpenCL 3.0（通常随GPU驱动自动安装）

**安装路径**（默认）：
- Qt6: `C:\Qt\6.10.1\msvc2022_64`
- PCL: `C:\Program Files\PCL 1.15.1`
- OpenCV: `C:\opencv\build`

### 3. 配置项目

**方式1：使用配置脚本（推荐）**
```bash
# 需根据本地情况修改库路径，编辑configure.bat
configure.bat
```

**方式2：手动配置**
```bash
cmake -B build -S . ^
  -G "Visual Studio 18 2026" ^
  -A x64 ^
  -DPCL_DIR="C:/Program Files/PCL 1.15.1/cmake" ^
  -DOpenCV_DIR="C:/opencv/build" ^
  -DCMAKE_PREFIX_PATH="C:/Qt/6.10.1/msvc2022_64"
```

**注意**：
- 如果系统安装了VS 2022，可使用 `-G "Visual Studio 17 2022"`

### 4. 编译项目

```bash
# Release版本（推荐）
cmake --build build --config Release

# Debug版本 需自行复制Debug版本库文件
cmake --build build --config Debug
```

编译输出：
- Release: `bin/D330Viewer.exe`
- Debug: `bin/Debug/D330Viewer.exe`

### 5. 运行程序

```bash
cd bin
D330Viewer.exe
```

**注意**：首次运行需要确保所有DLL文件都在bin目录下。

### 6. 生成MSI安装程序（可选）

项目支持生成Windows MSI安装程序，方便在其他电脑上部署。

**前置要求**：需要安装 WiX Toolset v3.x

**安装WiX Toolset**：
1. 访问 GitHub Release 页面：https://github.com/wixtoolset/wix3/releases
2. 下载最新版本的安装包：
   - `wix3xx-binaries.zip`
   - 或 `wix3xx.exe`
3. 如果下载zip文件：
   - 解压到 `C:\Program Files (x86)\WiX Toolset v3.14\`
   - 添加bin目录到系统PATH：`C:\Program Files (x86)\WiX Toolset v3.14\bin`
4. 如果下载exe文件：
   - 直接运行安装程序，安装后会自动添加到PATH

**验证安装**：
```bash
candle.exe -?
```

**生成MSI安装程序**：

```bash
# 编译完成后，在build目录运行
cd build
cpack -G WIX -C Release
```

生成的安装程序：`build/D330Viewer-0.1.0-win64.msi`

**MSI安装程序包含**：
- D330Viewer.exe（主程序）
- 所有必需的DLL
- Qt平台插件（platforms目录）
- 开始菜单快捷方式
- 桌面快捷方式
- 卸载程序快捷方式（开始菜单）

**安装目录结构**：
```
C:\Program Files\D330Viewer\
├── D330Viewer.exe          # 主程序
├── *.dll                   # 所有依赖库
└── platforms\              # Qt平台插件
    └── qwindows.dll
```

**快捷方式**：
- 桌面：D330Viewer（卸载时自动删除）
- 开始菜单：D330Viewer 文件夹
  - D330Viewer（启动程序）
  - 卸载 D330Viewer（卸载程序）

## 功能特性

### ✅ 已完成功能

#### 网络通信
- ✅ UDP网络通信（GVSP协议解析）
- ✅ 自动设备扫描和发现
- ✅ 相机连接管理（连接/断开）
- ✅ 命令发送（START/STOP）
- ✅ 下位机动态切换IP，可随时切换上位机

#### 可视化
- ✅ 实时左红外、右红外相机图像显示
- ✅ 实时RGB相机图像显示
- ✅ 实时3D点云显示（自定义OpenGL渲染）
- ✅ 正交投影视角（平面视图）
- ✅ 交互式点云操作：
  - 左键拖动：旋转视角
  - 右键拖动：平移
  - 滚轮：缩放（范围100-10000）

#### 用户界面
- ✅ Qt6 GUI主窗口（三栏布局）
- ✅ 相机控制面板（START/STOP按钮）
- ✅ 曝光时间调节（滑块，范围460-100000μs）
- ✅ 网络配置（IP地址、端口设置）
- ✅ 连接状态指示
- ✅ 配置持久化（QSettings）
- ✅ 点云颜色映射（深度着色）
- ✅ 多视角预设（正视、侧视、俯视）

### 🚧 当前开发计划

根据需求文档和用户反馈，后续待添加功能如下：

- 录制功能（连续保存多帧）
- 点云滤波选项（降噪、平滑）
- 测量工具（距离、角度测量）
- 性能监控（CPU/GPU使用率、内存使用）
- 其他相机参数调节（增益、白平衡等）

## 点云去噪原理与参数说明

### 去噪处理流程（当前版本）

当前点云去噪不是单一滤波器，而是多阶段组合策略，目标是在保留主体结构的同时抑制放射状无效点和外围杂点。

1. 有效点预筛：去掉非有限值和 `z<=0` 的点，得到基础有效掩码。
2. 中心ROI深度门控：基于中心区域中位深度自适应裁剪深度窗口，先去掉明显离群深度。
3. 邻域一致性筛选：统计每个点在局部窗口内“深度相近邻居”的数量，邻域支持不足的点剔除。
4. 形态学轻清理：移除局部孤立残点，减少毛刺。
5. 近距离尾部裁剪：对低深度尾部进行比例裁剪，抑制中心放射状噪点。
6. 连通簇筛选：按面积、深度一致性和中心重叠等条件保留主簇及相关簇，抑制周边散簇。
7. 最终细枝清理：对近距离且邻居不足的细枝点做额外抑制。
8. 时序稳定：对关键阈值做帧间平滑和限跳，减少块状点云“时有时无”的闪烁。

### 三个参数的作用与范围

参数都在“曝光与拍照 -> 拍照参数 -> 点云去噪参数”中，实时生效。

1. 邻域支持阈值
- 范围：`3 ~ 12`
- 含义：一个点要保留，局部邻域内至少需要多少个深度相近邻居。
- 调大：噪点更少，但边缘和细小结构更容易被吃掉。
- 调小：细节更多，但散点噪声会增加。

2. 射线裁剪强度 (‰)
- 范围：`5 ~ 50`
- 含义：近距离低深度尾部的裁剪比例（千分比）。
- 调大：中心放射状噪点减少更明显，但近距离真实细节可能减少。
- 调小：近距离细节保留更多，但放射状点可能增多。

3. 周边抑制带宽 (‰)
- 范围：`40 ~ 180`
- 含义：控制连通簇保留深度带宽、回补范围和近距离毛刺门限。
- 调小：抑制更激进，周边杂点更少，但主体可能偏“硬”、易丢块。
- 调大：主体与细节更完整，但外围杂点回升概率更高。

### 推荐起始参数

用于室内桌椅等常见场景，可先从以下值起步，再按效果微调：

- 邻域支持阈值：`8 ~ 10`
- 射线裁剪强度：`12 ~ 18`
- 周边抑制带宽：`90 ~ 130`

## 项目结构

```
d330viewer/
├── src/                      # 源代码
│   ├── main.cpp             # 程序入口
│   ├── gui/                 # GUI相关
│   │   ├── MainWindow.cpp   # 主窗口
│   │   ├── PointCloudWidget.cpp        # 点云显示组件
│   │   └── PointCloudGLWidget.cpp      # OpenGL点云渲染
│   ├── core/                # 核心功能
│   │   ├── NetworkManager.cpp          # 网络通信
│   │   ├── GVSPParser.cpp              # GVSP协议解析
│   │   ├── PointCloudProcessor.cpp     # OpenCL点云计算
│   │   └── DeviceScanner.cpp           # 设备扫描
│   └── config/              # 配置管理
│       └── ConfigManager.cpp           # 配置持久化
├── include/                 # 头文件
│   ├── gui/                 # GUI头文件
│   └── core/                # 核心功能头文件
├── bin/                     # 可执行文件和DLL
│   ├── D330Viewer.exe       # 主程序
│   └── *.dll                # 依赖库
├── build/                   # CMake构建目录
├── CMakeLists.txt           # CMake配置
├── configure.bat            # 快速配置脚本
└── README.md                # 本文件
```

## 相机配置

### 硬件信息
- **相机型号**: D330M
- **控制端口**: 6790 (UDP)
- **数据端口**: 3957 (UDP)
- **分辨率**: 1224 x 1024
- **深度范围**: 155mm - 3000mm

### 网络配置
确保PC和相机在同一网段即可。

### 相机参数
- **曝光时间**: 460 - 100000 μs
- **Z缩放因子**: 0.2 (深度值需除以5)
- **相机内参**:
  - fx = 1432.8957
  - fy = 1432.6590
  - cx = 637.5117
  - cy = 521.8720

### 下位机程序修改
下位机程序保存在`/root/msk/20260113/` 。具体安装和使用详见根目录内`INSTALL.md`文件。当前版本程序修改功能如下：
   - 添加`DISCOVER`命令，允许上位机对相机进行自动扫描。保持上位机下位机均DHCP能够正常使用。
   - 将程序添加到系统服务中，可以使用`systemctl`进行运行和管理

## 使用说明

### 基本操作流程

1. **启动程序**
   - 运行 `bin/D330Viewer.exe`
   - 程序会自动扫描网络中的D330M相机

2. **连接相机**
   - 在设备列表中选择相机
   - 点击"连接"按钮
   - 状态指示变为绿色"已连接"

3. **开始采集**
   - 点击"启动"按钮开始实时采集
   - 深度图显示在中间区域
   - 点云显示在右侧区域

4. **调整参数**
   - 拖动曝光滑块调整曝光时间
   - 使用鼠标操作点云视角

5. **停止采集**
   - 点击"停止"按钮停止采集

### 点云交互操作

- **旋转视角**: 左键拖动
- **平移**: 右键拖动
- **缩放**: 滚轮上下滚动
- **复位**: 重新启动采集

## 故障排除

### 常见问题

#### 1. 无法接收数据
**问题**: 点击"启动"后没有图像和点云显示

**解决方案**:
- 图像在长时间传输后有概率卡住，不相应任何命令，具体可监控下位机日志。重启系统服务即可解决。

## 开发文档

### 代码规范
- 使用Qt6信号槽机制进行模块间通信
- OpenCL kernel代码内联在C++源文件中
- 配置使用QSettings持久化
- 日志输出到 `%LOCALAPPDATA%/Viewer/Viewer/viewer.log`（例如 `C:/Users/<用户名>/AppData/Local/Viewer/Viewer/viewer.log`）