diff --git a/README.md b/README.md index 27aae18..9ff39b1 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,10 @@ kill $(pgrep -f "d405_captur[e]_server") ## 界面操作 -左侧实时画面(下方显示当前模式 / 实际帧率 / 深度有效像素比例),右侧四个面板: +左侧实时画面,下方状态栏依次显示:当前模式 / 实际帧率 / 深度有效像素比例 / +**中心距离**(画面中央 1/3 区域深度中位数,D405 最佳工作距离 7–50cm,超出变红提示 +太近或太远)/ **录制健康度**(丢帧数与时间戳回跳数,录制中实时刷新,停止后保留上一段的 +统计,非 0 变红)。右侧四个面板: 1. **录制** - `● 开始录制 / ■ 停止并保存` @@ -59,6 +62,8 @@ kill $(pgrep -f "d405_captur[e]_server") 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)与增益 @@ -77,13 +82,24 @@ intrinsics.json 元数据 - 深度 PNG **单位 0.1mm**(值 × depth_scale_m = 米),**已对齐到彩色帧**(rs.align), 与彩色同分辨率,可直接按 intrinsics 反投影成点云 - `intrinsics.json`:对齐后彩色内参(fx/fy/cx/cy)、`depth_scale_m`、录制参数 - (分辨率/名义与实际帧率/是否存深度)、`timestamps_ms`(逐帧硬件时间戳,可查丢帧) + (分辨率/名义与实际帧率/是否存深度),以及逐帧时间信息(各列等长、按帧对齐): + + | 字段 | 含义 | + |---|---| + | `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、深度有效率 | +| `/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`(触发流重启)或画质/深度范围/曝光等 | @@ -104,5 +120,10 @@ curl -X POST -d '{"duration":10,"out_dir":"~/datasets/grasp"}' http://localhost: `/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 立体匹配的正常表现 diff --git a/d405_capture_server.py b/d405_capture_server.py index cc52067..8195526 100644 --- a/d405_capture_server.py +++ b/d405_capture_server.py @@ -7,7 +7,7 @@ http://localhost:8405 录制输出 captures/<时间戳>/: color.mp4 彩色视频(按当前分辨率/帧率) depth/%06d.png 16bit 深度 PNG(0.1mm,已对齐彩色;可关) - intrinsics.json 内参 + depth_scale + 逐帧时间戳 + 录制参数 + intrinsics.json 内参 + depth_scale + 逐帧双流硬件时间戳/帧号 + 丢帧统计 + 录制参数 用法: .venv-d405/bin/python d405_capture_server.py [--port 8405] """ @@ -34,12 +34,16 @@ cfg = { # 可从 UI 修改 } st = { # 只读状态 "stream_ok": False, "device": "-", "error": "", - "fps_actual": 0.0, "depth_fill": 0.0, + "fps_actual": 0.0, "depth_fill": 0.0, "dist_cm": 0.0, "on": False, "frames": 0, "elapsed": 0.0, "duration": 0, + "drops": 0, "backjumps": 0, "last_saved": None, } -rec = {"dir": None, "writer": None, "timestamps": [], "t0": 0.0, - "save_depth": True} +rec = {"dir": None, "writer": None, "t0": 0.0, "save_depth": True, + # 逐帧时间记录:双流硬件时间戳 + 帧号 + 主机单调钟到达时刻 + "color_ts": [], "depth_ts": [], "color_fn": [], "depth_fn": [], + "arrival_ns": [], "prev_cts": None, "prev_cfn": None, + "ts_domain": ""} restart_flag = threading.Event() sensor_dirty = threading.Event() intrinsics = {} @@ -67,11 +71,14 @@ def start_recording(duration, save_depth, out_dir=""): (d / "depth").mkdir(parents=True, exist_ok=True) else: d.mkdir(parents=True, exist_ok=True) - rec.update(dir=d, timestamps=[], t0=time.time(), save_depth=save_depth, + rec.update(dir=d, t0=time.time(), save_depth=save_depth, + color_ts=[], depth_ts=[], color_fn=[], depth_fn=[], + arrival_ns=[], prev_cts=None, prev_cfn=None, writer=cv2.VideoWriter(str(d / "color.mp4"), cv2.VideoWriter_fourcc(*"mp4v"), cfg["fps"], (cfg["width"], cfg["height"]))) - st.update(on=True, frames=0, elapsed=0.0, duration=duration) + st.update(on=True, frames=0, elapsed=0.0, duration=duration, + drops=0, backjumps=0) print(f"[record] start -> {d} (duration={duration}s, depth={save_depth})", flush=True) return None @@ -89,7 +96,19 @@ def stop_recording(): fps_nominal=cfg["fps"], fps_actual=round(n / max(time.time() - rec["t0"], 1e-6), 2), save_depth=rec["save_depth"], - timestamps_ms=rec["timestamps"]) + # 时间来源说明:global_time 已禁用,时间戳来自相机硬件时钟 + # (单调,不受主机 NTP/对时算法影响,可用于速度/加速度计算) + time_source="device hardware clock, global_time disabled", + timestamp_domain=rec["ts_domain"], + timestamps_ms=rec["color_ts"], # 兼容旧字段名=彩色流 + depth_timestamps_ms=rec["depth_ts"], + color_frame_numbers=rec["color_fn"], + depth_frame_numbers=rec["depth_fn"], + host_arrival_monotonic_ns=rec["arrival_ns"], + dropped_frames=st["drops"], + timestamp_backjumps=st["backjumps"], + sync_note="每行数据来自同一 frameset;D405 彩色取自左成像器," + "与深度同一次曝光,硬件级同步") (d / "intrinsics.json").write_text(json.dumps(meta, indent=1)) st["last_saved"] = f"{d}({n} 帧)" print(f"[record] saved {d} ({n} frames)", flush=True) @@ -130,6 +149,11 @@ def capture_loop(): align = rs.align(rs.stream.color) scale = profile.get_device().first_depth_sensor().get_depth_scale() dev = profile.get_device() + # 禁用 global_time:librealsense 的软件对时算法会造成时间戳回跳 + # (典型 ~150ms),禁用后走相机硬件时钟,严格单调 + for s in dev.query_sensors(): + if s.supports(rs.option.global_time_enabled): + s.set_option(rs.option.global_time_enabled, 0) apply_sensor_options(profile) frames = align.process(pipe.wait_for_frames()) intr = frames.get_color_frame().profile.as_video_stream_profile().intrinsics @@ -167,7 +191,20 @@ def capture_loop(): if rec["save_depth"]: cv2.imwrite(str(rec["dir"] / "depth" / f"{st['frames']:06d}.png"), depth_raw) - rec["timestamps"].append(cf.get_timestamp()) + cts, dts = cf.get_timestamp(), df.get_timestamp() + cfn, dfn = cf.get_frame_number(), df.get_frame_number() + if not rec["ts_domain"]: + rec["ts_domain"] = str(cf.get_frame_timestamp_domain()) + if rec["prev_cts"] is not None and cts <= rec["prev_cts"]: + st["backjumps"] += 1 + if rec["prev_cfn"] is not None and cfn > rec["prev_cfn"] + 1: + st["drops"] += int(cfn - rec["prev_cfn"] - 1) + rec["prev_cts"], rec["prev_cfn"] = cts, cfn + rec["color_ts"].append(cts) + rec["depth_ts"].append(dts) + rec["color_fn"].append(int(cfn)) + rec["depth_fn"].append(int(dfn)) + rec["arrival_ns"].append(time.monotonic_ns()) st["frames"] += 1 st["elapsed"] = time.time() - rec["t0"] if st["duration"] > 0 and st["elapsed"] >= st["duration"]: @@ -180,10 +217,15 @@ def capture_loop(): n_win += 1 now = time.time() if now - t_win >= 1.0: + hh, ww = depth_raw.shape + roi = depth_raw[hh // 3:2 * hh // 3, ww // 3:2 * ww // 3] + nz = roi[roi > 0] with state_lock: st["fps_actual"] = n_win / (now - t_win) st["depth_fill"] = 100.0 * np.count_nonzero(depth_raw) \ / depth_raw.size + st["dist_cm"] = float(np.median(nz)) * scale * 100 \ + if nz.size else 0.0 n_win, t_win = 0, now # 预览合成 @@ -295,7 +337,6 @@ class Handler(BaseHTTPRequestHandler): out = dict(st) out.update(width=cfg["width"], height=cfg["height"], fps=cfg["fps"]) - out.pop("timestamps", None) self._json(out) elif self.path.startswith("/frame.jpg"): # 等到「新」一帧再返回(最多 1.5s),前端拉帧循环靠它对齐相机节奏 diff --git a/d405_ui.html b/d405_ui.html index a420b99..19826f3 100644 --- a/d405_ui.html +++ b/d405_ui.html @@ -21,7 +21,11 @@ main{display:flex;gap:14px;padding:14px;align-items:flex-start;flex-wrap:wrap} #viewwrap{flex:1 1 640px;min-width:320px} #view{width:100%;display:block;background:#000;border:1px solid var(--line); border-radius:8px;min-height:200px} -#overlay{display:flex;gap:16px;margin-top:6px;font-size:13px;color:var(--dim)} +#overlay{display:flex;gap:16px;margin-top:6px;font-size:13px;color:var(--dim);flex-wrap:wrap} +#overlay .ok{color:#4cc38a} +#overlay .warn{color:#e8a33d} +#overlay .bad{color:var(--rec);font-weight:600} +.hint.warn{color:#e8a33d} aside{width:300px;flex:0 0 300px;display:flex;flex-direction:column;gap:12px} .card{background:var(--panel);border:1px solid var(--line);border-radius:10px; padding:12px 14px} @@ -59,6 +63,7 @@ button{border:0;border-radius:8px;padding:10px 0;width:100%;font-size:16px; live
——— + —