- 禁用 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>
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 变红)。右侧四个面板:
- 录制
● 开始录制 / ■ 停止并保存- 录制时长(秒):填 N 秒到时自动停止;0 或留空 = 手动停止
- 保存位置:留空用默认
captures/;支持绝对路径和~;相对路径挂在 脚本所在目录下。目录不存在自动创建,每段录制在其下建时间戳子目录 - 保存深度:关掉可省约 90% 磁盘(深度 PNG 是大头)
- 视频流(改动需点「应用」,会重启相机流,约 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 内
- 预览与深度显示(即时生效):预览 JPEG 画质、深度伪彩范围(0.5/1/2/4m)、 布局(并排 / 仅彩色 / 仅深度)。只影响预览,不影响录制数据
- 传感器(即时生效):自动曝光开关;手动模式可调曝光(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 立体匹配的正常表现