文档基线：2026-08-05，main@4538763；最近发布标签为 v2.0.4，位姿图优化 位于标签后的 main。相关页：使用手册 · 部署与发布手册 · LeRobot 与 UMI 数据集导出

本产品是面向机器人学习演示数据采集的 Jetson 工作站。操作员佩戴头部和双手 Insight 相机完成任务，系统负责：

1. 低延迟显示多路相机画面、统一世界系设备姿态和轨迹；
2. 在不额外竞争图像 DDS reader 的前提下录制 rosbag，并持续审计完整性；
3. 管理 Bags、回放、评分、离线 WiLoR Hand pose 和轨迹优化；
4. 将通过质量检查的数据导出为标准 LeRobot v3 或旧 UMI Zarr；
5. 用 Insight9 在线稀疏地图和 Insight3 双路重定位提供唯一在线空间基准。

旧 AprilTag 在线对齐、MediaPipe hand pose、Qt 原生监控窗口和 A/B 分屏 kiosk 不属于当前产品范围。

• 采集操作员：看实时画面与设备状态，开始/停止录制，复核质量并导出数据集。
• 数据/算法工程师：回放、评分、Hand pose、优化、建图诊断和导出结果复核。
• 运维人员：选择设备 profile、部署/回滚发布镜像、检查相机网络和 worker 日志。

开发环境使用根目录 docker-compose.yml，本地构建并 bind-mount 整个仓库。 客户机使用 deploy/docker-compose.yml 和发布镜像，只挂载配置与运行数据。 ROS_DOMAIN_ID 从当前 config/cameras.json 读取，不能按机器写死。

客户发布自 v2.0.0 起包含 Dashboard、SuperGlue TensorRT 推理、Insight9 稀疏 mapper 和 Insight3 global localizer。Insight9 dense mapper 与 RViz profile 只供 内部验证，不进入客户包。

Insight cameras / ROS 2 DDS
          │
          ▼
PoseBridgeNode（ROS 生命周期与服务组合）
  ├─ dashboard_runtime：图像管线、录制桥接、watchdog、worker 监管、WS payload
  ├─ dashboard_web：aiohttp app、REST routes、WebSocket 和静态页面
  ├─ dashboard_media：JPEG 与 WebRTC 媒体实现
  ├─ post_processing_core：录制、恢复、同步、回放、评分、优化、bag/topic catalog
  ├─ webrtc_worker：独立信令与硬件 H.264 编码进程
  └─ hand_overlay_worker：按需 JPEG 解码、关键点叠加和重编码进程

SuperGlue worker ⇄ Insight9 sparse mapper ⇄ Insight3 global localizer
          │                      │
          └── 稀疏地图/位姿图 ──┴── 双路全局 Pose、Path、status、TCP TF

Firefox kiosk / remote browser
  └─ 页面级 ES modules：pages + shared + camera + spatial

multi_camera_dashboard_web.py 与 post_processing.py 是稳定兼容 facade；新增 业务逻辑必须进入对应拆分模块。当前前端不存在全站共享的单体 app.js。

• / 和旧 /images 跳转到 /3d，实时画面与 3D 场景在同一页面。
• 图像默认可走 WebRTC 硬件 H.264；协商、worker 或浏览器能力异常时回退 JPEG。
• WebRTC 保留相机发布的原生分辨率，只做编码所需的偶数取整，不再固定降到 540 px。浏览器正常预览请求 25 fps，主进程在图像转换和 IPC copy 前按会话 deadline 选择 latest frame；录制时预览限为 10 fps，以采集为先。
• WebRTC worker 通过鉴权 Unix IPC 与主进程通信，主进程轮询 health；手部画面 叠加由另一个按需 worker 完成，均不得在 ROS image callback 中做阻塞编码。
• Dashboard WebSocket 以 30 Hz 运行。新客户端和每 2 秒保底发送完整 snapshot，正常更新只 发送带 sequence/generation 的 trace_update 增量；前端检测缺口后重连获取快照。
• Jetson kiosk 的 Babylon 3D 场景以独立 wall-clock timer 保持 30 Hz，轨迹 mesh 最多 10 Hz 更新；可切换 GLB avatar 或 stick-figure，Avatar 下拉选择当前可用， 不处于旧版 locked 状态。
• 实时与回放必须通过 /bagplay/... 影子话题区分，不能用相机时间戳猜来源。

• 按当前 ROS domain 发现并按相机分组展示 topic，支持自定义包名和选择录制项。
• 主进程收到的图像直接送入每路 InProcessBagWriter 写 SQLite；禁止恢复额外 ros2 bag record 图像订阅。IMU、VIO、TF 等小消息仍由 RecordingManager 管理的 rosbag 子进程录制。
• SQLite 使用 WAL + synchronous=OFF，这是吞吐与断电恢复的有意折中；启动时 自动认领 rosbags/_staging/ 中断录制。
• 录制期间持续审计图像 header 帧间隔和相机网络。停止后合并各子包，写入 live header/network audit，并按配置自动同步宿主机；合并/同步完成前禁止开始下一条。
• Jetson NX 默认录入原始 VIO 以及 Dashboard/重定位产生的全局 Pose。

• 展示 bag 名称、体积、时长、消息/topic 数和完整性、评分状态。
• 支持选择、删除、回放和跳转到下游任务。删除是永久操作，必须先由用户确认。
• check_bag.py --fast 直接对 SQLite 做每 topic COUNT/MIN/MAX(timestamp) 聚合； 它不读取 CDR payload，也不能替代录制期间的 header live audit。
• /tf_static 只要求至少一条；未配置 nominal rate 的 topic 只报告存在性，不作 丢帧结论。

• 默认格式为 LeRobot v3（HiFi-UMI profile）；Legacy UMI Zarr 只供旧训练栈兼容。
• 统一 20 Hz；状态固定 20 维 [right_10d, left_10d]，每臂为 xyz + rot6d + width，缺失单臂写零并配有效性掩码。
• LeRobot action 为下一时刻绝对状态。π0.5 等模型需要的相对动作由训练 adapter 产生，不污染标准归档。
• 每个选中的 rosbag 生成一个独立数据集。支持按约 1 秒停顿自动切 episode，或 保持一 bag 一 episode。
• 当前网页默认 224×224 下方操作区；可显式选 Original 或 384×384。
• 只有导出器明确判定的质量不合格 bag 可以在导出工作流中自动删除；配置、标定、系统或 导出错误必须保留源 bag。

• 完整性分析与轨迹质量评分使用共享后端任务，结果持久化到 outputs/results/。
• 评分按 pose topic 报告协方差水平、坏段、可用比例和最终分数；完整性与轨迹 分数是两个结论，界面不得把二者混为一个指标。

• 从 rosbag 离线提取 WiLoR hand pose，支持任务状态、结果复核和对应产物管理。
• 当前只保留 WiLoR；已删除的 MediaPipe 实现不得重新出现在设置、文档或依赖中。

• 对选定 bag/相机启动离线视觉重建与 VIO 对齐，展示日志、进度和结果。
• COLMAP 随 Jetson NX 发布镜像提供；运行产物保存在 runs/ / outputs/，不入库。

• 管理 avatar、stick-figure、夹爪追踪、手部叠加及可热更新的定位配置。
• avatar 切换当前开放。需要重启的配置由界面明确提示并提供后端重启入口。
• Insight3 图像 mask 默认值为 0，运行中可热更新，不要求重启 localizer。

Insight9 按关键帧构建稀疏地标。历史地标 PnP 通过三帧共识后形成回环边；SE(3) 位姿图把闭环误差分配到历史关键帧，再按优化位姿重融合地标和分段修正 Path。 对外最新 Pose 继续通过 EKF 平滑，避免观测到达单帧跳变。详见 Insight9 建图与回环检测。

Dashboard 将两路 Insight3 图像各以 2 Hz 中继给 localizer，避免 localizer 再建 全帧 DDS reader 与采集竞争。可靠 PnP 共识相对当前显示校正小于 0.15 m / 10° 时由 EKF 平滑拉回，达到任一阈值时硬重定位；暂时看不到地图后保持最后校正， 以 vio_only 模式继续 30 Hz 全局 pose。Jetson NX 同时发布 camera center 到 左右 TCP 的静态 TF。详见 Insight3 自适应重定位。

• 所有设备共享 main。profile 只包含 cameras.json 和 post_processing.json；运行中的机器禁止随意切换 profile。
• jetson-nx 默认使用 CycloneDDS、可靠图像 QoS、raw/no-payload 排除列表和 自动宿主机同步。
• insight-camera-network.service 配置网卡；冷启动恢复由 insight-camera-reboot.service 完成。
• Dashboard health 为 /healthz。WebRTC 和 hand overlay 日志分别位于 outputs/webrtc_worker.log、outputs/hand_overlay_worker.log。
• SuperGlue TensorRT 首次冷编译约 15 分钟，engine volume 跨升级保留；这段 时间 Dashboard 可用，但全局轨迹尚未出现。

• 后端：目标 API/WS 和真实 ROS 数据路径可用，worker health 正常，无重启循环。
• 录制：选择的 topic 存在；图像 live audit、网络审计和停止合并结果一致； _staging 不遗留未说明的失败产物。
• 前端：/3d、/recording、/bags、/umi-dataset、/scoring、 /handpose、/optimization、/settings 均能加载且无控制台错误。
• 前端源码变更必须执行 node web_dashboard/build.js 并同时提交 src/dist。
• 建图厘米级精度、Insight3 大漂移找回和双臂数据可训练性必须用真实相机与独立 控制点验证；合成测试不能替代现场结论。

• insight3_b 尚缺可靠夹爪宽度标定，双臂 LeRobot 导出会安全失败；禁止用默认 常数绕过。
• Insight9 位姿图已有合成回归与在线接线验证，但正式厘米级结论仍需真实小闭环、 长闭环和独立固定点测量。
• 显示用 2D 手部关键点没有真实深度，3D 骨架的左右分类与合成深度不能当作精密 机器人状态使用。