Files
liyang a038da124a 时间戳治理 + 工作距离/健康度指示 + 低分辨率提醒
- 禁用 librealsense global_time_enabled,时间戳改走相机硬件时钟(hardware_clock),
  消除软件对时造成的 ~150ms 回跳(旧录制 424×240@60 第 575 帧实测 −149ms)
- intrinsics.json 逐帧记录彩色/深度双流硬件时间戳、帧号、主机到达时刻,
  以及本段丢帧数与时间戳回跳数;README 补字段表与坑
- /api/status 增加中心距离 dist_cm(中央 1/3 区域深度中位数)与 drops/backjumps
- UI 状态栏:中心距离按 D405 最佳 7–50cm 变色提示;录制健康度实时显示;
  分辨率低于 848×480 时提示指尖/指缝细节风险;首次连接同步服务端流参数
- 实测 424×240@60:600 帧与 3595 帧两段均零丢帧零回跳,间隔恒定 16.697ms,
  彩色-深度时间戳差 <0.33ms

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-15 17:10:15 +08:00

6.8 KiB
Raw Permalink Blame History

D405 采集台

Intel RealSense D405 深度相机的网页采集工具:浏览器里实时预览彩色+深度画面, 按钮控制录制,输出下游(Dyn-HaMR / 手部重建等)可直接使用的数据格式。

单文件后端(d405_capture_server.py,标准库 HTTP 服务)+ 单文件前端(d405_ui.html), 无框架依赖。

硬件要求

  • Intel RealSense D405(其他 RealSense 型号未测;D405 特性:近距 7cm~50cm 最佳, 彩色与深度来自同一对成像器,天然对齐好、曝光联动)
  • USB 3.x 接口(USB2 带宽不够,高分辨率/帧率会起不来流)

依赖与安装

系统 Python 3.12 + venv(不用 conda):

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

依赖只有三个(版本为实测可用版本,见 requirements.txt):

包 用途
pyrealsense2 2.58.4 RealSense SDK Python 绑定,取流/对齐/控曝光
numpy 帧数据处理
opencv-python-headless JPEG/PNG 编码、mp4 写入、深度伪彩(headless 版即可,无 GUI 依赖)

无需 root、无需安装 librealsense 系统包(pyrealsense2 的 wheel 自带)。

运行

.venv/bin/python d405_capture_server.py          # 默认端口 8405
.venv/bin/python d405_capture_server.py --port 9000

浏览器打开 http://localhost:8405。服务只监听 127.0.0.1,如需远程访问请自行改绑定或做端口转发。

停止/重启(注意 pkill -f 会连含同名字符串的当前 shell 一起杀,用带括号的正则排除自身):

kill $(pgrep -f "d405_captur[e]_server")

界面操作

左侧实时画面,下方状态栏依次显示:当前模式 / 实际帧率 / 深度有效像素比例 / 中心距离(画面中央 1/3 区域深度中位数,D405 最佳工作距离 7–50cm,超出变红提示 太近或太远)/ 录制健康度(丢帧数与时间戳回跳数,录制中实时刷新,停止后保留上一段的 统计,非 0 变红)。右侧四个面板:

  1. 录制
    • ● 开始录制 / ■ 停止并保存
    • 录制时长(秒):填 N 秒到时自动停止;0 或留空 = 手动停止
    • 保存位置:留空用默认 captures/;支持绝对路径和 ~;相对路径挂在 脚本所在目录下。目录不存在自动创建,每段录制在其下建时间戳子目录
    • 保存深度:关掉可省约 90% 磁盘(深度 PNG 是大头)
  2. 视频流(改动需点「应用」,会重启相机流,约 1 秒黑屏;录制中禁止改)
    • 分辨率 424×240 / 640×360 / 848×480 / 1280×720
    • 帧率 5 / 15 / 30 / 60 / 90 —— 1280×720 最高 30fps,60/90 需 848×480 及以下
    • 选 848×480 以下时面板会提示:低分辨率对手腕/手掌整体定位可用,但指尖、指缝和 遮挡边界容易出错;手部重建建议 ≥848×480,且手和物体处在 7–50cm 内
  3. 预览与深度显示(即时生效):预览 JPEG 画质、深度伪彩范围(0.5/1/2/4m)、 布局(并排 / 仅彩色 / 仅深度)。只影响预览,不影响录制数据
  4. 传感器(即时生效):自动曝光开关;手动模式可调曝光(100~30000µs)与增益 (D405 彩色/深度同一成像器,曝光对两者同时生效)

输出格式

每段录制一个目录 <保存位置>/<YYYYmmdd_HHMMSS>/:

color.mp4          彩色视频,按录制时的分辨率/帧率
depth/000000.png   16bit 单通道 PNG,每帧一张,与 color.mp4 帧号一一对应
intrinsics.json    元数据
  • 深度 PNG 单位 0.1mm(值 × depth_scale_m = 米),已对齐到彩色帧(rs.align), 与彩色同分辨率,可直接按 intrinsics 反投影成点云

  • intrinsics.json:对齐后彩色内参(fx/fy/cx/cy)、depth_scale_m、录制参数 (分辨率/名义与实际帧率/是否存深度),以及逐帧时间信息(各列等长、按帧对齐):

    字段 含义
    time_source / timestamp_domain 时间来源说明;域应为 hardware_clock(相机硬件时钟,单调)
    timestamps_ms 彩色帧硬件时间戳(ms)。可直接用于速度/加速度计算
    depth_timestamps_ms 深度帧硬件时间戳(ms),与彩色差 <0.5ms(同一次曝光)
    color_frame_numbers / depth_frame_numbers 相机侧帧号(两流计数器独立,各自连续即无丢帧)
    host_arrival_monotonic_ns 主机 monotonic_ns 到达时刻,仅用于和其他主机设备粗对时(抖动 5~40ms,不要拿它算运动)
    dropped_frames / timestamp_backjumps 本段录制丢帧数 / 时间戳非单调次数,下游用前先看这两项是否为 0

    彩色与深度每行来自同一 frameset;D405 的彩色取自左成像器,和深度同一次曝光,属硬件级同步。

HTTP API(脚本化采集)

端点 方法 说明
/api/status GET 流状态、录制状态、实际 fps、深度有效率、中心距离 dist_cm、本段丢帧 drops / 回跳 backjumps
/api/start POST {"duration":秒, "save_depth":bool, "out_dir":"路径"}
/api/stop POST 停止并保存
/api/config POST 改 width/height/fps(触发流重启)或画质/深度范围/曝光等
/frame.jpg GET 阻塞到新一帧再返回(≤1.5s),适合拉帧循环
/stream GET MJPEG 流(兼容保留,前端已不用)

示例——命令行录 10 秒到指定目录:

curl -X POST -d '{"duration":10,"out_dir":"~/datasets/grasp"}' http://localhost:8405/api/start

设计说明 / 已踩的坑

  • 不用 librealsense 原生录制:SDK ≥2.56 只支持 rosbag2 的 .db3 格式,下游不好用, 故自行落 mp4 + PNG + json
  • 预览不用 MJPEG 长连接:连接一断 <img> 永远冻在最后一帧要手动刷新。前端改为 /frame.jpg 拉帧自愈循环(失败自动重试),服务端「等到新帧才返回」使拉帧节奏 自动对齐相机帧率
  • 流级自愈:wait_for_frames 连续超时 2 次自动重启相机流;流启动失败每 2 秒自动重试
  • 时间戳必须关掉 librealsense 的 global_time_enabled:它默认开启,用软件线性回归把 相机时钟对到主机时钟,回归更新时时间戳会回跳(实测 424×240@60 录 600 帧出现一次 −149ms),这种数据不能算速度/加速度。关掉后时间戳域变为 hardware_clock,实测 600 帧 间隔恒定 16.697ms、零回跳。代价是时间戳零点是相机上电时刻,不是 epoch——跨设备对时 用 host_arrival_monotonic_ns 粗配即可
  • 深度伪彩里黑色 = 无效像素。白墙/无纹理表面、超近(<7cm)或超远处无效点多, 是 D405 立体匹配的正常表现