257 lines
7.5 KiB
Markdown
257 lines
7.5 KiB
Markdown
# Orbbec D2C Batch Converter (软件对齐)
|
||
|
||
将奥比中光相机采集的深度图（Depth）批量软件对齐到彩色图（Color）坐标系，输出与 RGB 分辨率一致的对齐深度图。
|
||
|
||
---
|
||
|
||
## 原理
|
||
|
||
软件 D2C（Depth-to-Color）对齐流程：
|
||
|
||
```
|
||
深度像素 (u_d, v_d, Z)
|
||
↓ Brown-Conrady 畸变校正 + 反投影
|
||
3D 点（深度相机坐标系）[X, Y, Z]
|
||
↓ 外参旋转 R + 平移 t
|
||
3D 点（彩色相机坐标系）[X_c, Y_c, Z_c]
|
||
↓ 彩色内参投影
|
||
彩色像素 (u_c, v_c) → 写入对齐深度图
|
||
```
|
||
|
||
多个深度点映射到同一彩色像素时，保留最近点（小 Z 值覆盖大 Z 值）。
|
||
|
||
### 前向映射的间隙问题与 3×3 Splat 修复
|
||
|
||
前向映射（forward scatter）存在固有缺陷：每个深度像素只写入 color 平面的**一个像素**。由于深度相机与彩色相机的视角差异，经外参变换 + 透视投影后，相邻深度像素在 color 平面上的落点会出现跳跃，中间留下空洞，输出图像呈现**离散小方块**而非连续深度面。
|
||
|
||
**修复方案：3×3 邻域扩散（splat）**
|
||
|
||
对每个投影后的深度像素，同时写入以其为中心的 3×3 邻域，而不是单个像素。遍历顺序仍保持**远→近**，因此当多个 splat 重叠时，Z 值较小（较近）的深度最后写入并覆盖，遮挡关系依然正确：
|
||
|
||
```
|
||
for dv in -1, 0, +1:
|
||
for du in -1, 0, +1:
|
||
aligned[v + dv, u + du] = z # 远→近顺序，近处覆盖远处
|
||
```
|
||
|
||
如果局部仍有残留空洞（如深度图有效范围边缘），可将 3×3 扩大为 5×5（`range(-2, 3)`）。
|
||
|
||
---
|
||
|
||
## 环境依赖
|
||
|
||
| 包 | 版本 |
|
||
|----|------|
|
||
| Python | 3.8 ~ 3.13 |
|
||
| pyorbbecsdk | 2.x |
|
||
| numpy | — |
|
||
| opencv-python | — |
|
||
|
||
```bash
|
||
pip install numpy opencv-python
|
||
```
|
||
|
||
### 安装 pyorbbecsdk
|
||
|
||
> 官方文档：https://orbbec.github.io/pyorbbecsdk/source/2_installation/install_the_package.html
|
||
> GitHub：https://github.com/orbbec/pyorbbecsdk
|
||
|
||
**支持平台：** Windows 10 x64 / Ubuntu 18.04·20.04·22.04 x64 / ARM64
|
||
|
||
#### 方式一：在线安装（推荐）
|
||
|
||
```bash
|
||
# Windows / Linux
|
||
pip install pyorbbecsdk2
|
||
```
|
||
|
||
> 无论在线（`pyorbbecsdk2`）还是离线安装，最终包目录名均为 `pyorbbecsdk`，`import pyorbbecsdk` 均可正常使用。
|
||
|
||
#### 方式二：离线安装（.whl）
|
||
|
||
1. 前往 [Releases](https://github.com/orbbec/pyorbbecsdk/releases) 下载与 Python 版本和平台匹配的 `.whl` 文件
|
||
（例：Python 3.11 / Windows → `pyorbbecsdk-2.x.x-cp311-cp311-win_amd64.whl`）
|
||
2. 安装：
|
||
```bash
|
||
pip install pyorbbecsdk-2.x.x-cp311-cp311-win_amd64.whl
|
||
```
|
||
|
||
#### 安装后验证
|
||
|
||
```bash
|
||
pip show pyorbbecsdk
|
||
```
|
||
|
||
#### 设备驱动配置
|
||
|
||
**Windows**（管理员 PowerShell）：
|
||
```powershell
|
||
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||
.\obsensor_metadata_win10.ps1 -op install_all
|
||
```
|
||
|
||
**Linux**：
|
||
```bash
|
||
cd pyorbbecsdk/scripts/env_setup
|
||
sudo chmod +x ./install_udev_rules.sh
|
||
sudo ./install_udev_rules.sh
|
||
sudo udevadm control --reload && sudo udevadm trigger
|
||
```
|
||
|
||
---
|
||
|
||
## 文件说明
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `d2c_batch.py` | 主程序 |
|
||
| `camera_params.json` | 相机参数缓存（自动生成，可复用） |
|
||
| `utils.py` | 奥比中光 SDK 辅助函数（备用） |
|
||
|
||
---
|
||
|
||
## 使用方法
|
||
|
||
### 完整流程（首次使用）
|
||
|
||
```bash
|
||
python d2c_batch.py
|
||
```
|
||
|
||
1. 列出相机所有 **RGB 配置**（分辨率 / 帧率 / 格式），输入序号选择
|
||
2. 列出所有 **Depth 配置**，输入序号选择
|
||
3. 自动启动相机，采集一帧，提取内外参，保存到 `camera_params.json`
|
||
4. 输入**深度图目录**路径
|
||
5. 批量转换，结果保存到 `<输入目录>_d2c/`
|
||
|
||
### 仅获取相机参数（不转换）
|
||
|
||
```bash
|
||
python d2c_batch.py --params
|
||
```
|
||
|
||
适合先连相机标定参数，稍后离线转换。
|
||
|
||
### 仅批量转换（无需连相机）
|
||
|
||
```bash
|
||
python d2c_batch.py --convert
|
||
```
|
||
|
||
使用已有的 `camera_params.json`，直接输入深度图目录开始转换。适合相机参数已获取、需要反复处理不同数据集的场景。
|
||
|
||
### 关闭 3×3 Splat 填充
|
||
|
||
```bash
|
||
python d2c_batch.py --no-splat
|
||
```
|
||
|
||
默认开启 splat（前向映射后用 3×3 邻域扩散填补间隙）。加 `--no-splat` 可关闭，每个深度像素仅写入 color 平面的单个像素，适合对原始投影结果做对比分析。可与其他参数组合使用：
|
||
|
||
```bash
|
||
python d2c_batch.py --convert --no-splat
|
||
```
|
||
|
||
---
|
||
|
||
## 交互示例
|
||
|
||
```
|
||
Found saved camera params: camera_params.json
|
||
Use existing params? [y=use existing / n=re-fetch from camera]: n
|
||
|
||
=== Phase 1: Camera Parameter Acquisition ===
|
||
|
||
Available RGB (Color) profiles:
|
||
# Resolution FPS Format
|
||
----------------------------------------
|
||
[0 ] 1920x1080 30 MJPG
|
||
[1 ] 1280x720 30 MJPG
|
||
[2 ] 640x480 30 RGB
|
||
Select RGB (Color) profile index: 0
|
||
-> Selected: 1920x1080 @ 30fps MJPG
|
||
|
||
Available Depth profiles:
|
||
# Resolution FPS Format
|
||
----------------------------------------
|
||
[0 ] 1280x800 30 Y16
|
||
[1 ] 640x400 30 Y16
|
||
[2 ] 320x200 30 Y16
|
||
Select Depth profile index: 1
|
||
-> Selected: 640x400 @ 30fps Y16
|
||
|
||
Starting pipeline...
|
||
Pipeline stopped.
|
||
Camera params saved to: camera_params.json
|
||
|
||
--- Camera Parameters Summary ---
|
||
RGB : 1920x1080 @ 30fps MJPG
|
||
fx=1382.5 fy=1382.5 cx=959.8 cy=539.4
|
||
Depth : 640x400 @ 30fps Y16
|
||
fx=424.0 fy=424.0 cx=319.5 cy=199.5
|
||
scale=0.001000 mm/unit
|
||
Extrinsic t : [-14.82 0.12 0.03] (mm)
|
||
|
||
Enter depth images directory: D:\data\depth_raw
|
||
|
||
=== Phase 2: Batch D2C Conversion ===
|
||
Input dir : D:\data\depth_raw
|
||
Output dir : D:\data\depth_raw_d2c
|
||
Files : 120
|
||
Depth scale: 0.001000 mm/unit
|
||
Output size: 1920x1080 (color resolution)
|
||
|
||
[ 1/120] 000001.png
|
||
[ 2/120] 000002.png
|
||
...
|
||
[ 120/120] 000120.png
|
||
|
||
Done. 120/120 files converted in 8.3s
|
||
Results: D:\data\depth_raw_d2c
|
||
```
|
||
|
||
---
|
||
|
||
## 输入 / 输出格式
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 输入深度图 | PNG，uint16，单位为传感器原始单位（乘以 `depth_scale` 得 mm） |
|
||
| 输出对齐深度图 | PNG，uint16，单位与输入相同，分辨率与所选 RGB 配置一致，目录名 `<input>_d2c` |
|
||
| 输出伪彩图 | PNG，uint8 BGR，JET colormap，无效像素为纯黑，目录名 `<input>_d2c_vis` |
|
||
|
||
---
|
||
|
||
## camera_params.json 格式
|
||
|
||
```json
|
||
{
|
||
"color": {
|
||
"width": 1920, "height": 1080, "fps": 30, "format": "MJPG",
|
||
"intrinsic": { "fx": 1382.5, "fy": 1382.5, "cx": 959.8, "cy": 539.4, "width": 1920, "height": 1080 },
|
||
"distortion": { "k1": -0.055, "k2": 0.071, "k3": 0.0, "k4": 0.0, "k5": 0.0, "k6": 0.0, "p1": 0.0, "p2": 0.0 }
|
||
},
|
||
"depth": {
|
||
"width": 640, "height": 400, "fps": 30, "format": "Y16",
|
||
"scale": 0.001,
|
||
"intrinsic": { "fx": 424.0, "fy": 424.0, "cx": 319.5, "cy": 199.5, "width": 640, "height": 400 },
|
||
"distortion": { "k1": 0.0, ... }
|
||
},
|
||
"extrinsic": {
|
||
"rot": [1,0,0, 0,1,0, 0,0,1],
|
||
"transform": [-14.82, 0.12, 0.03]
|
||
}
|
||
}
|
||
```
|
||
|
||
`extrinsic.rot` 为行优先展平的 3×3 旋转矩阵，`extrinsic.transform` 为平移向量（单位 mm），方向为深度相机坐标系 → 彩色相机坐标系。
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
- 获取相机参数时需要相机**实际连接**；批量转换时不需要。
|
||
- 更换相机或修改分辨率后需重新获取参数（运行时选 `n` 或使用 `--params`）。
|
||
- 输入深度图分辨率须与获取参数时选择的 Depth 分辨率一致。
|
||
- 对齐深度图的有效区域受深度传感器视场角限制，彩色图边缘区域可能无深度值（值为 0）。
|