Orbbec_D2C/README.md

# 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 值）。

---

## 环境依赖

| 包 | 版本 |
|----|------|
| 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`，直接输入深度图目录开始转换。适合相机参数已获取、需要反复处理不同数据集的场景。

---

## 交互示例

```
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）。