深度相机：现在是怎么被调用的，以及深度推理该怎么接进来

这一页回答两件事：①今天这套深度录制在代码里到底怎么串起来的、它坏在哪；②要让深度真正参与抓取， 有哪三条路可走、各自代价多大。所有结论都标了出处（文件:行号 或 实测数字）， 推断和实测分开写。

先说结论

一、现在的调用链

三层，从下往上。

二、这套设计坏在哪（2026-09-03 实测）

缺陷 1 · Start 按两次会孤儿掉录制线程 （今天已修）

_cmd_start 原来直接 self._depth = DepthRecorder(...)，覆盖前不停旧的。 按第二次 Start 时，上一个 DepthRecorder 就没人持有引用了：它的线程是 daemon， 只认自己的 _stop 事件，而 _cmd_stop 只停 self._depth 当前指向的那一个。

缺陷 2 · 摄像头句柄泄漏 （今天已修）

DepthCamera.open() 先 os.open() 拿到 fd，再做一串可能抛异常的 ioctl（S_FMT / REQBUFS / STREAMON）。 设备被占时 ioctl 抛错，DepthRecorder.start() 捕获后只把 _cam 置 None —— 那个已经打开的 fd 永远不关。

# v4l2_depth.py:119
def open(self):
    self.fd = os.open(self.device, os.O_RDWR | os.O_NONBLOCK)   # ← 先占住
    ...
    fcntl.ioctl(self.fd, VIDIOC_S_FMT, fmt)                     # ← 这里抛异常,fd 就漏了

实测：leader_follower_server.py 进程上挂着 34 个 /dev/video0 句柄（ls /proc/<pid>/fd）。 depth_recorder.py:108 那条「2026-08-31 观测到：开-关-立刻重开会让流起不来，每次 read 都超时」的注释， 正是这个泄漏的表象 —— 当时把症状当成了 Orbbec 的怪癖，绕过去了，没找到根因。

缺陷 3 · 相机开着但一帧不给：USB 层面的假死 （无软件修法）

9-02 下午右臂四个数据集（1654 / 1717 / 1734 / 1746）的深度目录全部 0 帧， meta.json 一律是 frames=0, dropped=0, error=None，起止正好 10.0 秒。 这个组合只有一种解释：open() 成功、ioctl 全过，然后 5 次 warm-up 读帧每次超时 2 秒 = 10 秒， 还没进主循环 stop() 就来了 —— 相机开着，但一帧都不给。1819 的 ep0–ep6 同样。

USB 拓扑（/dev/v4l/by-path/）—— 深度和 RGB 头是同一个物理设备的两个接口，腕相机在同一个 hub 的另一个口：

usb-0:2.3.1:1.0  → video0   Orbbec Gemini 335   ← 深度 (Z16)
usb-0:2.3.1:1.4  → video6   Orbbec Gemini 335   ← RGB 头,同一颗相机
usb-0:2.3.2:1.0  → video9   (腕) ← 18:32:16 就是这个口断开重连的
usb-0:2.3.3:1.0  → video10  USB2.0_CAM1 (腕)

三个缺陷叠加起来的实际损失（1819 这一个数据集）

缺陷 3 让 ep0–ep6 是 0 帧；缺陷 1 让 ep20 的录制器一直占着相机，缺陷 2 让后续每次开相机都失败且漏一个句柄。结果：

证据：ep21 起的每个深度目录都被创建了但一个文件都没有 —— 目录由 os.makedirs 在开相机之前建， 所以「空目录」精确地等于「尝试过、开相机失败」。ep21 的时间戳是 19:14:57，距 ep20 起跑仅 48 秒。
同一晚随后录的 ...-1928（17 集，19:28–19:43）整个数据集没有 depth 目录，同一个原因。

三、lerobot 原生的深度支持（本来就该用它）

当初做旁路的理由是「深度进数据集会被视频编码压毁」。这个理由从一开始就不成立。 本机 lerobot 0.6.2（~/lerobot/src/lerobot，checkout 于 2026-08-07）里 早已有完整的深度通路，全部来自 2026-06-27 的 PR #3644：

迁到 lerobot 原生之后，这三个缺陷还在不在

这是个绕不开的问题：既然旁路本可以不写，那换成原生就自动没事了吗？逐个看，答案不一样。

四、三条接入路线

路线 A —— 为什么它该排第一

03-software/scripts/cup_locate_demo.py 已经在做这件事：找画面里最近的一团， 用深度值 + 相机内参反投影出 3D 坐标。它不依赖任何 ML 模型，也不需要重训。

# cup_locate_demo.py 的自述,原文照录
# 积木② 深度相机每个像素给你一个距离(毫米);
# 积木③ 把"物体在画面的位置"+"那个位置多远"一拼 → 物体的真实 3D 坐标(反投影)。

它自己也诚实标了两条边界，这两条就是路线 A 的待办：

• Z（距离）是深度相机直接测的，准。X / Y 用的是估计内参（FX=FY=320, CX=320, CY=240，按 90° 水平视角假设）， 是近似值 —— 要精确必须做一次相机标定。这是路线 A 唯一的硬门槛。
• 透明玻璃杯深度会失效（返回 0 / 空洞）。这和之前的结论一致：不透明杯和磨砂杯可行，透明才是坑，贴标记是兜底。

路线 B —— 为什么不建议先做

「多一路相机」听起来最省事，但两个策略的视觉主干都是 RGB 预训练的：

• SmolVLA：图像喂给 SigLIP，归一化到 [-1,1]（policies/smolvla/modeling_smolvla.py:334 的 prepare_images）。
• ACT：vision_backbone = "resnet18" + pretrained_backbone_weights = "ResNet18_Weights.IMAGENET1K_V1"（policies/act/configuration_act.py:98）。

伪彩深度图对这两个主干都是分布外输入 —— 预训练特征在这种图上不成立，等于白白多一路要从头学的输入。 在「至今没有一个 checkpoint 抓起过杯子」的前提下，先加一路不确定的输入， 只会让「是数据的问题还是输入的问题」更难分辨。

路线 C —— 中期目标

录进去这一半是现成的；难点全在消费端。要做的事：

1. 写一个实现 lerobot Camera 接口的 Orbbec 深度相机类（connect / read / async_read / disconnect， 见 cameras/camera.py），让它输出 (H,W,1) uint16 —— 这样 feature_utils 会自动打上 is_depth_map。 现有的 v4l2_depth.DepthCamera 已经把最难的裸 V4L2 部分做完了，这一步主要是接口适配。
2. 确认训练管线端到端能吃 (H,W,1) 特征 —— 这一步没人验证过，必须先用几十集小数据集试通再说。
3. 决定策略侧怎么用：单独的深度编码器，还是和 RGB 拼成 4 通道（后者要放弃预训练主干的第一层权重）。

五、建议的动作顺序

1. 已完成 修 fd 泄漏（v4l2_depth.py:119，try/except + self.close()）。实测验证见缺陷 2。
2. 已完成 leader-follower 的实时录制页现在报每集深度帧数，0 帧标红 （leader_follower_server.py _cmd_stop：message_kind="err" 时前端渲染红色）。 VR / 面板批量录制那条路径（robot_server.py，整段会话一个 depth 文件夹，不是逐集）还没做，是接下来的一步。
3. 做一次相机标定，把 cup_locate_demo.py 里的估计内参换成实测值。这是路线 A 唯一的门槛。
4. 走通路线 A：深度 → 杯子 3D 坐标 → 先只做「报坐标」，人工核对准不准，再谈接进控制。
5. 小规模验证路线 C：几十集，确认 lerobot 原生 depth feature 能端到端训起来，再决定要不要全面迁移。

六、诚实边界

• 已实测：调用链的每一处文件行号、ep20 的 220,412 帧 / 13.7 小时 / 27 GB、34 集里 14 集有深度、 34 个泄漏句柄、深度有效像素占比 0.88、lerobot 0.6.2 里 depth 相关的五处代码。
• 未实测（推断）：路线 B 的「伪彩深度对 SigLIP/ResNet 是分布外输入」是从「主干为 RGB 预训练」推的， 没有跑实验证伪；路线 C 的「训练管线能吃 (H,W,1)」明确未验证。
• 没查：Orbbec 这颗深度相机的实际精度和最小工作距离（cup_locate_demo.py 里 zmin=150mm 是经验值，不是标定结果）； 深度与 RGB 两个节点之间的外参（做 3D→机械臂坐标必须要）。

七、这一页怎么在国内看

这些报告平时发到 HF Space Suyang99/xlerobot-build-reports（public、RUNNING、290 个文件， 2026-09-03 实测从机器上取回 HTTP 200 / 195 KB）。但 国内访问不了 huggingface.co —— 于是自己写的报告自己看不到。文件本来就在仓库里，所以 2026-09-03 给 robot_server 加了直接供页的路由：

http://100.107.145.111:8770/reports                       # 所有报告的索引(71 页)
http://100.107.145.111:8770/reports/space-2026-08-21/...  # 具体某一页

走 Tailscale，不经 HuggingFace，不需要 token（报告页里没有密钥；真实地址和密码在私有的 xlerobot-ops Space）。路径穿越已挡：解析后必须仍在 04-reports/ 内， 否则 403（实测 --path-as-is 三种穿越写法全部 403）。