LingBot-Depth输入数据详解:RGB图像、16位深度图与归一化相机内参,3个关键格式避坑清单
LingBot-Depth输入数据详解:RGB图像、16位深度图与归一化相机内参,3个关键格式避坑清单
LingBot-Depth 是一款基于 Masked Depth Modeling 的深度精修模型,能把残缺、带噪的传感器深度图修复为高质量的度量级 3D 测量结果。要跑通推理,你只需要准备 3 类输入数据:RGB 图像、16 位深度图和归一化相机内参。本文用仓库自带的示例数据(examples/),带你逐一搞懂每种格式的正确打开方式,并附上最常见的 3 个格式坑位清单。
📦 先认识输入目录:3 个文件的固定搭配
以 examples/0/ 为例,LingBot-Depth 推理需要三样东西,缺一不可:
| 文件 | 格式 | 作用 |
|---|---|---|
rgb.png / rgb.jpg |
8 位三通道彩色图 | 外观信息,引导深度补全 |
raw_depth.png |
16 位灰度 PNG | 传感器原始深度,单位毫米 |
intrinsics.txt |
3×3 浮点矩阵 | 相机内参,用于输出 3D 点云 |
🖼️ 输入一:RGB 图像——记得 BGR 转 RGB 再除以 255
RGB 图像是普通 8 位彩色图(640×480),处理分两步(见 example.py):
- 通道顺序:
cv2.imread读出来是 BGR,必须用cv2.cvtColor转成 RGB,否则颜色通道会"串台"; - 数值范围:除以 255 归一化到
[0, 1],转成float32tensor,形状为[B, 3, H, W](channel-first)。
image = cv2.cvtColor(cv2.imread('examples/0/rgb.png'), cv2.COLOR_BGR2RGB)
image = torch.tensor(image / 255, dtype=torch.float32).permute(2, 0, 1)[None]
💡 小提示:模型内部会自动做 ImageNet 均值/方差标准化(
0.485/0.456/0.406,见 mdm/model/modules_rgbd_encoder.py),你只需要归一化到[0, 1],不要重复标准化。
📐 输入二:16 位深度图——毫米是单位,0 表示无效
这是最容易翻车的一项。LingBot-Depth 要求的深度图是 16 位单通道 PNG(I;16 模式),像素值直接表示毫米:
depth = cv2.imread('examples/0/raw_depth.png', cv2.IMREAD_UNCHANGED)
depth = depth.astype(np.float32) / 1000.0 # 毫米 → 米
depth = np.nan_to_num(depth, nan=0.0) # 无效区域统一置 0
两个关键要求(对应 example.py 的 load_depth_map):
- 必须用
cv2.IMREAD_UNCHANGED读取,否则 16 位会被压缩成 8 位,深度精度直接丢 256 倍; - 单位必须是米(毫米值除以 1000)。无效区域(传感器没测到)保持
0或NaN,模型会自行屏蔽。
左图是 16 位原始深度图被按 8 位渲染的样子(看起来"全白"很正常,因为毫米数值远大于 255);右图是用 colormap 可视化后的真实深度分布——近处偏红、远处偏蓝,空洞区域为黑色:
模型对深度输入还会做 log 重映射来稳定训练(mdm/model/modules_rgbd_encoder.py),这一步是内部行为,输入端不用操心。
📷 输入三:相机内参——必须"归一化"后再喂给模型
intrinsics.txt 里存的是像素单位的 3×3 内参矩阵,例如 examples/0/intrinsics.txt:
460.139587 0.000000 319.656128
0.000000 460.199005 237.396271
0.000000 0.000000 1.000000
但 model.infer 要求传入的是归一化内参:fx、cx 除以图像宽 W,fy、cy 除以图像高 H(见 example.py 的 load_intrinsics):
intrinsics = np.loadtxt('examples/0/intrinsics.txt')
intrinsics[0] /= w # fx, cx 除以宽
intrinsics[1] /= h # fy, cy 除以高
归一化后的矩阵形如 <a href="https://link.gitcode.com/i/7ed342bf231fdb32c263b3b49567b826" target="_blank">[fx/W, 0, cx/W], [0, fy/H, cy/H], [0, 0, 1]],形状 [B, 3, 3]。它的作用是把精修深度反投影为 3D 点云([mdm/utils/geo.py 的 depth_to_pointcloud)——内参错了,点云就会整体"歪掉"。
⚠️ 3 个关键格式避坑清单
| # | 常见错误 | 后果 | 正确做法 |
|---|---|---|---|
| 1 | 用 cv2.imread 默认方式读 16 位深度图 |
深度被压成 8 位,毫米变"厘米级",结果全错 | 加 cv2.IMREAD_UNCHANGED,再 /1000.0 转米 |
| 2 | 跳过 BGR→RGB 转换直接喂图 | 通道顺序错乱,精修质量下降 | cv2.cvtColor(..., cv2.COLOR_BGR2RGB) |
| 3 | 直接传像素单位内参 | 3D 点云坐标尺度错误 | fx/cx ÷ 宽、fy/cy ÷ 高,别搞反纵横 |
另外两个小提醒:
- 无效区域:深度中传感器测不到的像素,置
0或NaN都可以,模型会用 mask 屏蔽(mdm/model/v2.py); - 尺寸一致性:RGB、深度、内参必须来自同一帧、同一分辨率,示例统一为
640×480。
🧠 模型到底吃进了什么
整理一下,model.infer(image, depth_in=..., intrinsics=...) 的三个参数(定义见 mdm/model/v2.py):
image:[B, 3, H, W],float32,范围[0, 1],RGB 通道序;depth_in:[B, H, W],float32,单位米,无效区为 0/NaN;intrinsics:[B, 3, 3],归一化相机内参。
模型输出一个字典:depth(精修深度图,米)和 points(相机坐标系下的 3D 点云 [B, H, W, 3])。
训练时使用的 RGB-D 数据同时覆盖真实与仿真场景,其中 "Depth Raw" 就是与本文示例同格式的原始深度图,"Depth GT" 是精修后的参考结果(见 README.md):
📷 延伸:这些输入数据从哪来
如果你有自家传感器(RealSense、Azure Kinect、Orbbec 等),采集方式可参考官方的 RGB-D 采集系统:多相机同轴固定拍摄,彩色流与深度流逐帧对齐,内参随标定文件一起保存即可——这正是本文 3 类输入数据的来源(README.md):
✅ 一句话总结
- RGB:
[B,3,H,W],[0,1]float32,注意 BGR→RGB; - 深度:16 位 PNG 毫米值 ÷ 1000 得米,无效区置 0;
- 内参:
fx/cx除宽、fy/cy除高后以[B,3,3]传入。
格式对,结果才准。跑一遍 python example.py,对着 examples/ 的 8 个场景核对输出,你的输入数据就"达标"了。




