Import calibration tests and package resources

This commit is contained in:
sunxianghui
2026-10-29 14:21:57 +08:00
parent 06faf18bb6
commit 5ad1b5107e
143 changed files with 13585 additions and 0 deletions
+8
View File
@@ -0,0 +1,8 @@
# 标定包协作约定
- 全程用中文;保留工作区已有修改。
- 测试选择遵循 [TESTING.md](TESTING.md)。日常运行受影响用例及必要契约,常规验证目标 60 秒内。
- 不默认运行全量 pytest、colcon test 或所有型号整手拟合。公共契约变更与发布节点再扩大范围。
- 同一代码版本已通过的测试不无理由重复执行;修复失败后只重跑失败或受修改影响的用例,并记录耗时。
- 优先复用不可变输入及已生成产物,在验收边界测试拒绝条件;不为每种错误重复生成整手标定。
- 软件回放通过与实机连续通过分开报告;不能为缩短测试或减少暂停放宽精度、可观测性和发布门限。
+948
View File
@@ -0,0 +1,948 @@
# LinkerHand 多型号统一标定
G20、L6、O6、O12、O30 使用同一个产品启动器、在线状态机、采集器、拟合器、标准 URDF
验收和发布器。型号专属程序、配置和源 URDF 集中在 `linkerhand_calibration/models/<型号>/`;旧 `config/` 和 `urdf/` 路径供现有配置与历史记录兼容。
本包按观测关节冻结实机 baseline 零位,输出实测曲线及明确声明的复制曲线组成的 JSON v3,
以及保留线性 mimic 联动的修正 URDF;报告区分独立实测、迁移和 CAD 零位假设。
保留 CAD 连杆尺寸、轴位置、mesh、惯量。完整运动由 JSON 的全部关节角度配合修正 URDF 计算。
软件仿真通过不等于实机精度通过;当前原始 G20/L6/O12 存在需要确认的 mimic/限位冲突。
本轮实现与验证见 [v3 实施记录](CALIBRATION_V3_IMPLEMENTATION.md)。
O30 右手的构建、相机外参重标和完整操作说明见 [O30 右手标定](linkerhand_calibration/models/o30/docs/O30_RIGHT_CALIBRATION.md)。
O30 当前使用反馈判断运动、稳定及零位恢复;允许指令与反馈存在固定偏差。最终 JSON 仍为指令→视觉角度,反馈映射只作诊断。
测试的分层、选择范围与耗时记录见 [测试说明](TESTING.md)。
图像姿态双候选的本轮诊断重构见 [图像求解重构记录](docs/IMAGE_SOLVE_REFACTOR.md)。
## O30 当前默认:轻量采集,离线修正
默认 `raw_joint_2_plus_1` / `raw_joint_images_v2`:移动标签仅保存二维角点,
每任务两轮训练加一轮验证;当前失败方向立即补采一次,仍失败记录缺项并继续。
采完归位、封存数据、关闭控制栈,终态 `CAPTURE_COMPLETE` 不等于 URDF 通过。
后续使用 `--offline-raw` 读取同一批数据修正,失败不再触发运动。
启动、离线命令和协议边界见 [O30 轻量标定说明](linkerhand_calibration/models/o30/docs/O30_RAW_PROTOCOL_IMPLEMENTATION.md)。
以下分阶段和自适应章节为历史显式试验入口,不是 O30 当前默认流程。
## O30 分阶段训练试验
新增显式选项 `--training-policy staged_2_to_3`,该历史策略以 `fixed` 为对照。Tag 数量、编号、尺寸、位置、
相机布局、完整网格、运动速度和验收门限不变。新策略按原任务顺序执行全手轮次 0、全手轮次 1,
进行训练检查;必要时仅集中补一次轮次 2,随后冻结整手模型,最后采集独立验证轮次 3。
局部零位补采包含同轮几何依赖,分段任务整体补采,共享掌部问题扩大到全手。补采后仍不合格即失败。
```bash
# 仅校验配置;不连接、启动硬件
ros2 run linkerhand_calibration calibrate_hand --config \
src/linkerhand_calibration/config/o30_right_product.yaml \
--training-policy staged_2_to_3 --validate-only
```
准备阶段会保留已有上游运动中可见的相关末节 Tag 原始角点及合法候选;缺失旁观 Tag 不阻塞
上游任务。末节保持指令、反馈、参考和独立图像检查全部合格后,测得的相对位姿才能约束后续准备。
上游图像及几何不确定度进入验收;原有图像无法区分的姿态仍拒绝。旧日志不会补造缺失角点。
回访复核原零位后复用原模型。训练进程、任务索引和局部拟合在会话内复用;冻结文件
`frozen_training.json` 绑定配置、源 URDF、计划、输入证据和求解版本。在线最终验收不重新训练;
离线审计仍复算决定。新策略断点仅复用完整任务访问,重试额度跨断点保留,冻结后不回退到训练。
同一会话的 `raw_samples.jsonl` 和 `frozen_training.json` 应一起保留,离线回放须指定相同策略。
两轮全部通过时,扫描单元从 144 减到 108、正式稳态停点从 1390 减到 1052;这不是总耗时降幅。
阶段重排增加回访和参考复核,实机对照须计入这些时间。`stage_timing.json` 区分阶段耗时、开始到
终态耗时及开始前断点加载耗时,终态后等待退出不计入开始到终态指标。独立验证失败不得回炉训练。
JSON→URDF 重建、文件与像素验收、成对发布、失败不更新通过指针,以及五个末节 CAD 零位声明均保留。
软件检查与实机验收分开记录。完整实机通过、人工干预不增加且同条件总耗时至少降低 10% 后,
才能评估切换默认策略;本次软件实现不自动启动硬件。实现与验收说明见
[分阶段标定实施记录](docs/STAGED_CALIBRATION_IMPLEMENTATION.md)。
## O30 自适应训练试验
该历史策略以 `fixed` 为对照:三轮训练加一轮独立验证。新会话可显式选择 `adaptive_2_to_3`:两轮训练后
检查覆盖、稳态网格、双向重复性和可计算的几何零位质量;证据不足补第三轮,第三轮仍不合格
就失败。每个方向的缺样恢复仍最多同速重扫一次,准备缺样仍最多局部恢复一次。
速度、双向运动顺序、节点、准备路径及最终精度门限均保留。
```bash
# 只检查配置,不连接硬件
ros2 run linkerhand_calibration calibrate_hand --config \
src/linkerhand_calibration/config/o30_right_product.yaml \
--training-policy adaptive_2_to_3 --validate-only
# 完成现场准备后,显式开始全新试验会话
ros2 run linkerhand_calibration calibrate_hand --config \
src/linkerhand_calibration/config/o30_right_product.yaml \
--training-policy adaptive_2_to_3 --no-resume
```
旧 `adaptive_2_to_3` 顺序中,O30 掌部共享几何依赖最后采集的四指侧摆。前面的任务无法可靠提前计算零位置信区间,
因此保守保留第三轮;最后一个任务满足全部门限时才减轮。本版完整计划的稳态停点最多从
1390 降到 1340(约 3.6%),不承诺总耗时同比下降。所有任务都省一轮时的 1052 个停点只是
理论下界,该旧顺序下不能实现。上面的分阶段策略在两轮全手证据齐全后统一判断,不受此逐任务调度限制。
采集计划 `capture_plan_v1` 绑定任务、运动分段、准备路径、网格与实际训练/验证身份。
轮次 ID 保持不变:减轮后依次采集 0、1、3,界面显示第 1、2、3 轮;ID 3 始终为独立验证。
`training_decision` 保存增补/冻结/失败决定、输入与计划哈希、冻结局部模型哈希及统计。
几何依赖未齐时明确记录 `deferred`,不能将局部曲线一致性冒充零位认证。
零位仍按真实独立轮次计算 Student t 置信区间,1° 半宽不变;曲线重复性使用既有角度误差门限。
重复图像不会增加独立轮数,验证数据不参与训练、增补决策或模型选择。
最终产物仍依次经过训练冻结、独立验证、落盘 JSON、从 JSON 重建 URDF、图像与运动学回读、
成对发布。Tag 安装拟合及运动范围证据也使用实际训练轮集合。五个末节 CAD 零位假设及已验证
运动范围的精度声明保留;失败候选不会更新通过指针。
旧断点沿用固定策略,新旧策略不能拼接。自适应断点只复用连续完整任务;需要重做某个任务时,
其后依赖旧训练输入的任务一并重新采集。离线复算自适应会话也须传入同一 `--training-policy`。
原始日志与已发布产物不被改写。训练预检在有总时限的独立进程执行,超时或取消会清理子进程。
新会话的 `stage_timing.json` 按控制周期边界汇总准备、几何计算、等待、采样、恢复、断点加载及最终验收耗时。
已有固定三轮训练日志可作只读对照,保留同一独立验证集:
```bash
PYTHONPATH=src/linkerhand_calibration python3 -m linkerhand_calibration.runtime.training_replay \
--raw-samples calibration_output/O30_RIGHT_001/20260919_214048/raw_samples.jsonl \
--source-urdf src/linkerhand_calibration/urdf/o30_right/linkerhand_O30i_right-V2_0819.urdf \
--output /tmp/o30-training-comparison.json
```
此工具复用采集索引,仅比较已完成任务的训练与角度验证,不生成发布产物,也不认证全手零位。
2026-09-19 21:40 会话的 12 个完整任务在两种训练轮数下均通过原独立角度门限;其共享几何尚未
齐全,不能据此批准两轮零位标定。约 2.88 GB 日志索引加载实测约 25 秒,作为后续性能工作的基线;
本次没有改动日志存储格式。
## 启动
```bash
cd /home/lxp/projects/linkerhand_retarget_ros2
source /opt/ros/jazzy/setup.bash
colcon build --packages-select linkerhand_calibration --symlink-install
source install/setup.bash
# 无运动、无 SDK 启动的配置检查
ros2 run linkerhand_calibration calibrate_hand --config \
src/linkerhand_calibration/config/o12_right_product.yaml --validate-only
# 正式启动:自动启动 SDK、相机、检测及标定,READY 后自动开始运动
ros2 run linkerhand_calibration calibrate_hand --config \
src/linkerhand_calibration/config/o12_right_product.yaml
```
其他型号替换为 `g20_right_product.yaml`、`l6_right_product.yaml`、`o6_right_product.yaml`、`o30_right_product.yaml`。
AprilTag 检测参数直接读取产品指定的受保护 Tag YAML,统一启动文件不再覆盖其中的采样分辨率。
`calibrate_g20_right` 是同一 runner 的旧命令别名。不要同时运行 GUI、单独 SDK 或其他控制器。
`--commands-disabled` 只预览,不发送运动;`--no-resume` 强制新采集。Ctrl+C 中止,不自动快速张手。
产品配置的 `resume_mode: passed` 表示操作者确认安装位置未变:只读取已通过的完整任务,
不回放历史图像、不重新判定旧采样质量,也不复核已完成关节的物理零位;未完成任务整组重新采集。
O30 当前使用此模式。配置/设备身份核对、实时保护和最终产物验收仍执行,恢复策略写入原始日志。
默认 `resume_mode: verify` 会逐帧回读校验历史图像;若大断点超过默认 120 秒,可用
`--startup-timeout-seconds 600` 显式延长节点初始化及设备就绪等待。此参数不改变运动、反馈新鲜度、
堵转保护或精度验收门槛,也不会跳过断点基准和关节零位复核。
断点预校验会共享不可变模型的解析结果,并在至少 256 帧时使用最多 4 个独立进程回放图像;
工作进程只做离线计算,在实时采集开始前退出。每帧角点、姿态、样本绑定及原始记录的内容哈希仍完整检查,
不跨会话缓存校验结论;小断点及收尾进程沿用串行校验。
标定节点在启动校验后将长期驻留的对象移出循环垃圾回收扫描,避免大断点触发数秒停顿;
实时新增对象仍正常回收,节点退出后恢复原对象的回收管理。反馈超时保护不变。
重新开始时先安全回基准,仍必须确保现场没有障碍物。
### JSON 到修正 URDF
统一收尾顺序为:拟合与独立角度验证 → 保存标定 JSON → 重新读取 JSON 修正原始 URDF → 文件回读与整链验证 → 发布。
JSON 的 `urdf_correction` 保存原始 URDF SHA256 和必要的关节字段修正,重建不依赖内存拟合对象。
原始 URDF 不被覆盖;关节拓扑、字段授权、完整 mimic 范围和 JSON 查表范围在文件安装前检查。
新 v3 使用 `urdf_correction.schema_version: 4`、`joint_angle_source: calibration_json`,
并记录 `mimic_policy: preserve_source_mimic`:所有型号保留本侧原始 `<mimic>` 元素,
不改来源、倍率、偏移或省略的默认属性;正式标定不再拟合 mimic 参数。JSON 保留各关节
非线性曲线及方向分支,精度验收使用 JSON 提供的全部关节角。父子链、轴和连杆不变,
被动关节与驱动关节仍绑定同一 SDK 通道,所有数值编辑仍按 Profile 授权。
`mimic_envelopes` 单独记录基础范围、原始联动可达范围和导出范围;在明确的实测范围策略下,
导出范围取二者的最小包络,实测范围证据与查找表不变。未声明该策略的 CAD 限位,以及
另行声明的硬件安全限位,仍是硬边界;冲突时报告具体关节和所需范围,不压低倍率或放宽容差。
关节 origin 按标定零位修正后,原始 mimic 作为输出坐标中的近似预览,不作为准确物理约束。
旧 correction v1、移除 mimic 的 v2、拟合线性近似的 v3 产物继续兼容读取与重建。
导出规则单独版本化,不改变采集配置指纹或旧原始记录,已发布产物不能原地覆盖。
已生成的 JSON 可单独重建对应 URDF,无需相机或 SDK:
```bash
ros2 run linkerhand_calibration rebuild_calibrated_urdf \
--config src/linkerhand_calibration/config/o6_right_product.yaml \
--calibration-json /path/to/calibration.json \
--output /path/to/new_corrected.urdf
```
输出路径必须尚不存在。没有 `urdf_correction` 的历史 JSON 不会被猜测或自动补全。
同一 JSON 和源 URDF 可逐字节重建相同修正文件;发布器会核对此项一致性,读取器要求相应验收记录。
历史无修正元数据的已发布文件继续沿用原有读取规则。
完整文件验收失败时保留候选 JSON/URDF 和诊断,便于复核;只有 `release_manifest.json`
和成功发布指针才代表通过,运行时读取器拒绝把未发布候选当作合格标定。
| Profile | SDK 位置通道 | 扫描任务 | Tag | 输出格式 |
| --- | ---: | ---: | ---: | --- |
| G20/right/g20_right_19/v1 | 20 | 16 | 19 | unified v3,256 项指令查表 |
| L6/right/l6_right_8/v1 | 6 | 3 | 8 | unified v3,256 项指令查表 |
| O6/right/o6_right_8/v1 | 6 | 3 | 8 | unified v3,256 项指令查表 |
| O12/right/o12_right_16/v1 | 12 | 11 | 16 | unified v3,rad 输入节点查表 |
任务数、主动关节数和实测关节数不必相等。一条运动可观测多个主动/被动关节。
观测策略由 `measurement.transferred_motion_sources` 声明,目标关节指向直接实测的来源关节:
| 型号 | 独立采集 | 复制的运动映射 |
| --- | --- | --- |
| O6/L6 | 拇指、小指 | 食指/中指/无名指的 MCP、DIP 分别复制小指对应关节 |
| O12 | 拇指、小指、中指、食指 | 无名指 MCP/PIP/DIP 分别复制小指对应关节 |
| G20 / 全关节模式 | 每个关节 | 不声明复制关系 |
复制保留接收关节自己的 SDK 通道、URDF 名称与 CAD 几何,不要求接收关节另贴 Tag 或采集零位帧。
复制参数不等于接收关节独立实测;接收关节仍须有明确的绝对零位来源及合法机械范围。
`zero.cad_zero_assumptions` 显式记录“实机 baseline 与原 CAD 末节零位一致”的使用前提,
相应 DIP(及拇指末节 IP)δ=0、自身 `origin` 不改。这是假设,不是视觉测得的绝对 CAD 朝向。
按用户确认,O12 的 `pinky_pip`、`ring_pip` 和主动 `thumb_mcp` 也采用原始 URDF 零位作为 baseline 假设。
运动曲线仍按实际观测/明确复制关系生成,报告标记 `assumed_source_cad_zero`,不称为独立实测零偏。
正式入口在驱动硬件前检查运动覆盖及零位来源,缺失依据时直接指出缺项,不采完才发现无法发布。
启动检查分别列出 `unmeasured_joints`(未独立观测)、`unresolved_motion_joints`(也未声明复制)
及 `missing_baseline_geometry`。旧迁移字段单独存在不会自动授权新的 v3 曲线复制。
本次沿用现有 Tag 和避让布局声明延后零位动作,没有把新增动作或缺失 Tag 布局标为实机验证通过。
每任务的运动模型采集四个往返,共八趟单程:前三轮训练,第四轮独立双向验证。
四个产品配置统一使用 `command_capture_mode: separate`:这八趟均为完整连续扫描,随后另做一组稳态映射训练往返和一组独立验证往返。
主扫描不逐点停顿;稳态点直接执行移动、稳定反馈、新图像采样,不重复等待两次到位。
稳态训练点由前三轮连续数据生成 `command_sampling_plan`:在原节点网格上寻找最少的
保留节点,各关节、各方向的预测曲线插值变化均不超过 0.25°;端点、基准、中间支撑点及
显式增加的非线性节点保留。缺少完整训练数据或曲线噪声过大时使用原网格。
这份计划只决定停在哪里,每个保留点的静态角度仍由新图像独立测量,不用连续运动角度
冒充静态角度。独立验证网格保持原样,不参与节点选择。计划及训练来源哈希随原始记录保存,
拟合、离线回放和断点恢复均重新核验;缺点、篡改或最终误差超限仍禁止发布。
上一段已经完成到位/稳定检查且下一准备目标完全相同时,可复用一秒内、反馈未变化的
完整保持姿态,省去重复准备等待;有实际位移、反馈变化或记录过期时执行原准备流程。
原训练网格每方向通常为 9 点,并保留行程内的 baseline;O6 小指额外包含 239,共 10 点。
新流程在这份网格上按上述规则精简训练停点。
验证使用交错点加端点(O6 小指包含 247),两类数据不混用。
日志中的运动轮编号为 0–3,独立指令映射训练和验证编号为 4、5;界面分别显示“稳态指令映射训练/独立验证”。
其他采用 `interleaved` 的配置仍在四轮各方向中穿插稳态点,并使用三轮稳态训练、第四轮稳态验证。
行进图像用于旋转/几何拟合,停稳后的新图像用于 SDK 指令映射;同一张图像不会复制成两类样本。
每点至少 3 个稳定同步图像,轨迹结束后最多等待 2 秒,不能用精确指令/反馈相等判断稳定。
关节零位冻结另需至少 10 张独立有效图像。`acquisition.joint_zero_timeout_seconds`
单独限定首张合格零位图像后的采集窗口,四个产品配置均为 5 秒;几何求解后的跟踪恢复仍最多等待 2 秒。
反馈不稳定会清空当前零位候选,但不会重置总采集期限;图像数量、1° 稳定性及分支证据要求不变。
稳定窗口使用每条新收到的 SDK 反馈,按消息时间戳去重,不再只取控制定时器看到的最新一条。
定时器延迟不能制造“独立反馈不足”;期间真实运动仍会使窗口失效。
候选清空时的 `steady_capture_reset` 保存反馈窗口和丢弃样本数量,便于区分抖动、断流和调度问题。
零位样本的 `capture_timing` 记录接收、历史快照和提交时间,用于检查处理延迟。
图像数量未齐时先返回缺样结果,不在控制定时器中反复校验全部姿态。
四轮及稳态采集完成、数据落盘后关闭图像采集;拟合只使用已保存的相机和参考证据。
之后的新图像和相机消息不再改变拟合输入,也不触发采集暂停;SDK 反馈、故障保护及操作者中止持续生效。
拟合或文件验收失败结束为 `FAILED`,保存 `failure_diagnostic.json` 中的失败阶段、原始数据路径和异常堆栈。
这类失败应先离线复算,不能仅因状态失败就重复四轮运动。运动采集期间的固定参考检查保持生效。
O6 的顶部 ID7 与正面 ID2 实际固定在同一末节,Profile 将 ID7 明确绑定到 `rh_thumb_distal`。
`thumb_yaw` 是它承担的侧摆观测角色,不是其安装连杆名称。整链回放包含该 Tag 上游的侧摆、弯曲和末节角度,
保持关节沿用记录的到达方向。新绑定改变了 Profile 哈希,旧会话不会被自动复用为新配置的通过结果。
固定 Tag 的 ID 解码成功不代表边框完整。独立的视觉边框检查进程按完全相同的图像时间戳配对整流图像与检测结果,
检查当前检测四边的黑白边界支持;部分遮挡产生的畸变四边形会被记为 `detection_quality_rejected`,
不能进入 PnP、关节样本或固定基准移动计数。配对缓存有界,不用邻近时间的图像替代。
检查使用当前检测四边形,清晰 Tag 发生真实位移仍进入原有 5 px/连续 10 帧保护。
控制进程只订阅 `detections_checked` 小体积观测;三路大图像的传输、配对和边框处理不占用 SDK 控制节点的回调队列。
ROS 宿主将准备几何求解和逐帧图像角度求解交给独立计算进程,避免与 SDK 反馈争用 Python 执行资源。
准备请求仍限时 120 秒;逐帧请求最多三个在途,超时或工作进程不可用的图像不生成有效样本。
工作进程只接收不可变图像/模型输入,没有 ROS 或 SDK 控制接口。返回后仍检查当前图像、跟踪版本和会话版本,
不能将迟到结果提交到下一运动段。`motion_solver_diagnostic.jsonl` 记录请求、计算耗时、线程 CPU 时间及提交结果。
当前任务需要的固定 Tag 无有效观测时,仍按原采样规则等待或暂停;其他机位的遮挡不误报为移动。
稳态点缺失与连续扫描不足统一在方向结束处理,最多同速重扫一次。
首次关节零位准备、避让及收尾属于独立的必要动作,不计入四个正式往返;不会每轮重新锁定零位。
分段加减速和停点仍有耗时,八趟行程不等于耗时恰好降为原来的三分之一。
新产品会话记录 `capture_schedule_version=unified_schedule_v3_separate_mapping`;旧 `interleaved` 配置仍记录 v2。
采集模式或保护配置不同的旧断点不与新流程拼接,
历史原始数据仍保留原语义供对应配置离线读取和分析。训练/验证身份与精度阈值保持不变。
字节拟合不再改写原始 command/feedback,也不将接近端点的读数伪装成 0/255。
## O6 右手拇指短程诊断
当前 O6 实物在 2026-09-16 复测的 Tag 黑色码区边长为 **16.5 mm**,棋盘格边长仍为
**27 mm**。O6 Profile、检测器配置和标定节点配置已同步采用 `0.0165 m`,产品配置记录
对应文件指纹。该数值属于这套实物标记,不是所有型号或所有打印批次的统一尺寸。
更换标记时应实测黑框,并同步维护上述配置;旧 16 mm 会话保留原尺寸记录,不作为
新尺寸的恢复断点。Tag 尺寸修正不改变 JSON 中非线性运动曲线与修正 URDF 的配合方式。
本套 O6 的 2026-09-16 实采数据已生成通过验收的产物,目录为
`calibration_output/O6_RIGHT_001/20260916_134154_source_mimic_165mm/`,
`latest_partial_passed` 已指向该目录。JSON 和修正 URDF 应配套使用;当前 8 Tag 布局
直接测量拇指、小指,其余三指沿用配置中的曲线迁移关系。采集完成后的在线收尾曾发生
系统 OOM,最终产物由完整原始数据的正式离线流程验收;日志读取内存优化另经独立进程
验证,不能将此记录描述为在线全过程无中断。详细证据见 `CALIBRATION_PIPELINE_REVIEW.md`。
此目录用同一份原始数据重新验收,5 组 mimic 的完整元素与原始 URDF 一致:
拇指倍率 **1.86**、其他四个末节 **0.89**,偏移均为 **0**。
11 个关节的指令/反馈查找表及几何零位保持不变;仅拇指 IP 的 URDF 下限从
−0.115187° 调整到 −0.183816°,覆盖原始联动所需范围,实测范围证据仍为原值。
拇指 SDK 指令 0 时,IP 的 URDF 预览为 **63.68°**,JSON 为 **66.35°**;
这是线性预览与实测非线性的区别。完整 JSON+URDF 和独立原始图像继续满足原精度门限。
`20260916_123347_json_driven_165mm/`(移除 mimic)及
`20260916_124718_mimic_json_165mm/`(拟合倍率和偏移)为历史版本,已被本次发布替代。
旧目录均保留;始终使用同一 manifest 指定的 JSON、报告和 URDF。
定位 Tag 姿态跳变时,可沿用相同产品配置添加诊断选项:
```bash
ros2 run linkerhand_calibration calibrate_hand \
--config src/linkerhand_calibration/config/o6_right_product.yaml \
--diagnostic-thumb
```
诊断选择原 Profile 中的 `thumb_yaw_top` 和 `thumb_pitch_ip_front`,各采一次往返,
观测拇指 CMC yaw、CMC pitch、IP 三个关节。保留原速度、完整扫描行程、准备/避让、
固定基准锁定、按关节尝试零位确认和安全收尾;其余手指不执行扫描任务,但开始时仍会安全回到 baseline。
本次诊断只启动正面和顶部机位:开始时一次锁定正面 ID0、顶部 ID6;运动观测使用顶部 ID6/ID7、正面 ID0/ID1/ID2。
侧面不参与本次诊断,ID3 缺失或双解、侧面相机未连接均不会阻塞;因此无需为拇指诊断调整 ID3 或改动相机外参。
范围由本次全部任务的主/辅观测依赖统一确定,启动、ROS 订阅、设备检查、基准锁定、指纹和进度使用同一范围。
它不会随当前任务切换而重新锁定;正面和顶部的配置变化、固定基准漂移及所需 Tag 数据不足仍按原策略处理。
正式全手标定继续使用 Profile 声明的全部机位和固定基准,外参文件及保护输入的完整校验保持不变。
“短程”缩短的是任务和轮次数,不截断需要复现异常的运动行程。
本模式跳过稳态映射采样与三轮训练/第四轮验收,收尾后显示 `DIAGNOSTIC_COMPLETE`
并正常退出。诊断按当前运动 Tag 的原始图像覆盖推进,持续姿态歧义不阻断原始候选采集;
缺少当前运动 Tag 角点或同步反馈导致方向覆盖不足时,仍最多同速重扫一次,严重故障和中止行为不变。
归零准备证据为 `unresolved` 时,仅诊断模式允许继续收集原始观测:必须先到达 Profile 声明的零位指令,
SDK 反馈稳定,当前运动 Tag 具有足量、带会话和运动版本的图像,才保存独立的 `diagnostic_joint_zero_attempt`。
它表示访问并观察了声明姿态,不表示已建立关节零位;不写入 `zero_references`,方向切换及重扫不重新归零。
该组关节后续仅保存原始角点和候选,即使普通跟踪恢复,也不能生成 `joint_sample` 或伪造有效角度。
缺少零位原始图像、SDK 不稳定、固定基准移动及已冻结参考冲突仍按现有策略暂停;正式标定仍须先确认分支和冻结零位。
会话目录保存 `raw_samples.jsonl`(含角点和 IPPE 候选)、实际成功冻结的关节零位与 `diagnostic_capture.json`。
`diagnostic_observation_frame` 在零位尝试和扫描阶段单独记录各帧候选,包括未接受的姿态,不能当作关节角度样本。
报告 `unit_quality` 分别记录原始观测覆盖与 `accepted_pose_quality` 可信姿态覆盖;
`joint_zero_status`、`missing_joint_zero_references` 列出各关节真实零位状态,`motion_initialization_summary` 保留各候选的关节残差。
进度显示原始观测覆盖,并单列可信姿态数量和未确认关节;暂停时保持“已暂停”,不会被零位动作名称覆盖。
可信姿态不足会在退出时明确提示。相邻帧姿态跳变和图像身份用于定位问题,诊断完成不代表标定精度通过。
每方向的 `observation_timing` 分别统计原始/可见/同步图像数、缺命令与缺反馈图像数、最大图像及同步观测间隔;
缺命令与缺反馈可以发生在同一帧,不能相加当作总丢帧数。少于两帧的间隔记为 `null`。
方向失败时这些信息同时进入暂停诊断。反馈跨度 100% 仅表示两端都有观测,不代表中间没有缺口。
原始帧的 `timing` 保存回调接收、历史快照及最新命令/反馈时间戳,用于区分消息延迟与状态匹配问题;
接收到快照的时间包含线程调度和锁等待,不能单独解释为写盘耗时。未匹配反馈时同步误差为 `null`,不会显示为 0 ms。
可额外加 `--record-bag` 保存现有录制话题;仅检查入口与配置可加 `--validate-only`,不会启动硬件。
诊断始终完整新采,不复用断点,不拟合或发布标定 JSON/URDF,也不更新发布指针。
原始会话带有诊断标记,正式离线拟合和断点发现会拒绝将其用作正式标定数据。
当前选项只开放给 O6 右手;其他型号仍走原来的正式流程。原始 URDF、Profile 和设备配置无需修改。
诊断任务预设在 `profiles/diagnostics.py` 声明,运行时只选择既有 Profile 任务,复用公共调度与采集组件。
诊断采集完成后,runner 先关闭相机和 SDK 进程,再自动运行公共图像几何分析,生成独立的
`diagnostic_analysis.json` 和可直接阅读的 `diagnostic_analysis.md`。耗时优化不进入实时状态锁或相机回调。
分析按任务、机位、方向和尝试分别保留原始图像身份,比较所有候选族的三维 PnP 残差、深度误差比例、
图像域关节链拟合以及隔帧和前后区间验证。验证时几何参数冻结,只从当前图像反解几何角度,不使用 SDK 角度映射。
图像误差小不等于毫米精度通过,优化收敛也不代表分支唯一;分析结果不能写回跟踪器、零位或正式标定产物。
未采到的方向和旧会话缺少的归零前证据会明确列出,不拼接不同会话,不使用第四轮重新拟合。
图像分析失败或被取消时,已完成的采集及原始文件仍保留,不会改标成 SDK 故障。
已保存的数据可直接离线复算,无需启动相机或重复运动:
```bash
ros2 run linkerhand_calibration analyze_calibration_capture \
--config src/linkerhand_calibration/config/o6_right_product.yaml \
--raw calibration_output/O6_RIGHT_001/20260914_192637/raw_samples.jsonl \
--output calibration_output/O6_RIGHT_001/20260914_192637/image_review
```
这些修改解决诊断采集被未确认零位阻塞及报告不完整的问题。现有真实 IP 数据仍有分段几何不一致,
正式分支门槛、拟合器、URDF 修正和独立精度验收保持原要求;软件回归不能替代实机精度结论。
### O6 右手 yaw 方向差保持诊断
需要区分“到达指令后仍在缓慢稳定”和“保持后仍存在方向差”时,使用独立选项:
```bash
ros2 run linkerhand_calibration calibrate_hand \
--config src/linkerhand_calibration/config/o6_right_product.yaml \
--diagnostic-yaw-hold
```
此模式仅选择 `thumb_yaw_top`,只启动顶部机位,使用固定基准 ID6 和运动 Tag ID7。
每次 Start 都重新采集会话基准并尝试确认 yaw 零位,不复用旧会话;同一会话的两个方向共用首次冻结零位,
不会分别归零。未能确认零位时按诊断规则保留原始观测,并明确标记无法生成可信角度。
在原速度和行程下执行一次往返。每个方向扫描后先回到该方向的起点,再沿同一方向访问三个保持点:
递减方向为 `255 → 192 → 128 → 64`,递增方向为 `0 → 64 → 128 → 192`。
每个保持点在指令轨迹完成后至少保持 10 秒,两方向合计六次保持;反馈确认可能使实际等待稍长。
保持过程继续记录图像角点、候选、实际指令和同步反馈,用于比较到达后的角度随时间变化及双向最终差异。
保持阶段的原始观测单独标记,不计入连续扫描的覆盖统计;遮挡、设备故障、中止及安全收尾仍沿用公共策略。
`--diagnostic-yaw-hold` 与 `--diagnostic-thumb` 互斥,不能同时使用离线拟合、发布或禁用运动选项。
可加 `--validate-only` 只检查入口与配置,或加 `--record-bag` 留存现有录制话题。
结果保存在 `raw_samples.jsonl` 和 `diagnostic_capture.json`,记录保持指令及时间;
不拟合或发布标定 JSON/URDF,不形成正式断点,也不算精度验收。
本诊断用于查清实机稳定时间和方向差,不改变最终单值 `angle_rad` 的验收要求。
## 启动前相机检查
`--validate-only` 检查相机配置文件、序列号、内外参指纹和已有外参质量记录,不采集现场图像。
正式启动还检查实时 `CameraInfo` 的宽高及 K/D/R/P 是否与受保护外参中的记录一致;
参数不匹配、无效或消息过期时不能开始,并显示具体机位和原因。
**配置匹配不等于现场内外参有效。** 当前只有手上的 Tag,各机位使用不同 Tag,
没有声明跨机位共视或已知的 Tag 间几何关系;手掌和贴纸又允许在开始前移动、重贴。
因此光学内参与相对外参的现场有效性记录为 `unverified`,不能用重新锁定掌心 Tag、
较小的 PnP 残差或未变化的配置哈希代替实测,也不能由 Tag 位置变化断定相机被碰。
`READY` 只表示设备与消息满足现有开始条件。显示上述能力提示后沿用现有启动行为,
不要求各手指 Tag 可见,不增加人工确认或新的暂停条件;`READY` 不表示物理相机参数已验证通过。
会话目录中的 `camera_preflight.json` 和 `raw_samples.jsonl` 保存检查结果与依据,
开始前仅在结果变化时记录,接受 Start 前再检查并冻结一次;后续状态中的检查结果指这次启动检查。
单凭这些记录不能判定是否需要重新标定。`expected_cameras` 是配置期望身份,不是现场实测结果。
镜头、焦距或成像设置变化后应重新核验内参;相机之间相对位置变化后应重新核验外参。
未来同一个物理 Tag 被多个机位共同看到时,可以检查相对外参一致性,但当前尚未实现该能力。
本次检查不修改 Profile、SDK 或原始 URDF。
## 基准、避让与恢复
- 开始前可以调整手掌、相机和 Tag;预览数据不会成为正式参考。
- 开始后清空预览缓存,先安全回基准,再为每机位固定 Tag 收集至少 10 个有效帧。
缺少基准时保持并显示缺少的 ID,不因为等待时间长暂停。
- 锁定后禁止人工移动手掌、相机、支架、Tag 粘贴位置;程序驱动关节和避让仍是允许的。
- 全手 baseline 时只要求固定参考可见,不要求四指运动 Tag 同时可见。
每关节在 `motion.joint_zero_references` 指定任务前,按声明的到达姿态和避让分组回到自身 baseline,
反馈稳定后收集至少 10 个稳定视觉帧,冻结 `JointZeroReference`。此后方向、轮次、重扫均不重新归零。
例如 G20 食指开始前,已完成四轮的其他手指可以保持非零避让;这些完整指令和反馈写入参考。
task.start 不代表零位,例如侧摆 baseline=127、扫描起点=255,会分别执行两种姿态。
- 相机相对位置改变时须重新确认/标定外参;仅重新锁定掌心 Tag 不能替代外参标定。
- 固定 Tag 被避让遮住时可用已锁定参考继续采集;软件不能保证检测完全不可见对象的移动。
运动 Tag 的刚性和几何一致性仍须通过最终独立验证。
- 采集断点版本为 `unified_engine_v8_all_view_images`;另以 `pose_tracking_policy_version=confirmed_branch_v8_training_model_selection`
记录姿态分支策略。缺少此字段或版本不同的旧断点不能自动或手工恢复到新会话,历史文件保持原样供离线诊断。
首先检查配置哈希与整场固定参考;各关节轮到时,在同一完整保持姿态核对原零位与父子 Tag 位姿
(5 px、2°、5 mm),通过后才导入对应已完成扫描单元,并保留原零位记录。
整场参考不匹配则放弃旧数据;逐关节安装验证失败则暂停,禁止在旧样本上新建零位拼接。
排除原因后用 `--no-resume` 开始新会话。旧会话文件不修改。
旧日志的读取、凭据回放与单元质量检查在实时回调启动前完成,不占用运动/反馈回调。
现场验证通过后,每个控制周期最多导入 64 条历史记录;全部落盘后才跳过对应单元。
导入期间持续处理反馈、固定基准监测和中止,原 1 秒反馈超时保护不变。
连续图像、候选和样本按图像批量追加并刷新到系统缓存,避免持有控制状态锁逐条 `fsync` 阻塞反馈和运动定时器。
固定参考、关节零位、方向完成和暂停记录仍强制同步到磁盘;拟合、报告哈希、发布和关闭前另有同步屏障。
断点只复用通过且持久化的完整方向,意外断电时未完成方向不能拼入旧数据;同步失败不得发布。
此存储策略不改变 50 ms 图像/状态配对门限、方向覆盖门限、拟合公式或精度验收条件。
O6/L6/G20 标定读取 SDK 的 `*_hand_state_timed` 反馈接口;位置与每个通道的 CAN 接收时间
一同保存。G20 五指的分帧反馈分别插值到图像时间,重复发布的缓存不能刷新反馈超时或增加
稳态独立样本。标准 `JointState` 仍可供其他程序使用,其时间戳保留测量时间。
`sdk_feedback_sample` 原始记录支持复查时间配对;旧版本只保存发布时间,不能事后补成真实
CAN 测量时间,也不能与新版断点混用。O12 继续使用独立 HCAN 同步读取接口。
共同坐标约定:`q_CAD = q_output + delta`;每个关节在自身冻结 baseline 时 `q_output=0`。
局部零位通过采样时的完整保持姿态和运动链进入同一掌部参考。固定 Tag 不提供未知末端连杆的 CAD 朝向。
`zero.known_baseline_geometry` 可声明有独立依据的 CAD 角度、误差界与来源;不能填入猜测的 0、旧 mimic
或 Tag 安装偏角冒充几何证据。相应 `origin.rpy` 和限位修正仍须在 Profile 中明确授权。
O12 避让:小指和无名指到 Profile 的最大弯曲指令;标定食指前,中指 MCP/PIP 到最大弯曲指令,
中指侧摆为 0 rad。到位采用完成轨迹、正确方向、至少 80% 请求位移和短时稳定,
不要求反馈数值精确等于命令。SDK 指令最大值与实测 URDF 角度不是同一个量。
O12 使用 HCAN device 0/channel 0 的已锁定 vendor Python wheel,不检查 `can0`。
连接参数由本包的 `config/o12_sdk.yaml` 保存,并通过产品配置中的 SHA256 校验;
不依赖第三方 SDK 子仓库中未提交的示例 YAML 修改。
只读反馈桥可在第一次运动命令之前取得状态,不会发送零位命令来“激活回读”。
POSITION 和活动故障由 SDK 确认;无法单独回读温度时使用 SDK 错误位过热保护,不伪造温度。
字节 SDK 当前没有独立硬件故障遥测,状态会明确注明这一能力边界。
## 哪些情况暂停
实时仅因人工中止、竞争控制器、活动硬件故障/模式错误、真实失联、反馈超过 1 秒未更新、
物理越限、明显运动要求下超过 Profile 的无推进等待时间(O30 为 4 秒,其他型号为 2 秒)、
已锁固定基准连续 10 帧漂移超过 5 px 而暂停。
开始后相机投影参数变化也会拒绝继续使用混合坐标数据。
当前关节持续缺失零位观测会暂停并列出关节、机位和所需 Tag;尚未轮到的手指遮挡不阻塞当前任务。
零位和稳态点的反馈稳定窗口以最新独立反馈为终点,并保留跨越窗口起点的一条反馈。
控制定时器的调度抖动或重复读取同一反馈不会清空稳定观测;真实反馈波动或反馈过期仍会使当前窗口失效。
零位仍需至少 10 帧且姿态波动不超过 1°;拟合验收门限不变。
短时 Tag 丢失、PnP/同步失败、低检测率/低反馈 Hz、正常跟随滞后、固有耦合和非目标小幅运动
不会实时中断轨迹。无效视觉帧直接丢弃。
所有型号的独立 Tag 姿态筛选共用 `core/geometry/pnp.py` 中的近似同误差阈值,默认 `0.03 px`。
ROS 和离线采集使用相同默认值,型号 YAML 不重复声明该值。`1.5 px` 是图像质量拒绝阈值,
不能用它判断两种姿态是否同样可信;仅在误差差值不超过近似同误差阈值时使用时间连续性。
分支容差覆盖值必须有限、非负且小于图像质量拒绝阈值。
独立 Tag 首次接受姿态前,需要默认至少 5 帧、跨越至少 0.1 秒的图像证据确认。
近似同误差的候选只有旋转相差不超过 1°、平移相差不超过 1 mm 时才视为同一姿态;这些参数统一定义于
`core/geometry/tag_pose/parameters.py`,ROS 通过 `pnp_branch_confirmation_frames`、
`pnp_branch_confirmation_minimum_seconds`、`pnp_branch_equivalence_deg` 加载,离线采集使用相同默认值。
这只是图像分支的一致性确认,不能把多帧低重投影误差视为物理姿态真值。
以下独立图像跟踪规则保留用于预览和历史兼容;新会话的运动 Tag 首次零位还必须通过后述公共运动几何确认。
参考冻结前,明显更优但与历史姿态发生大跳变的新分支也必须经过确认,过渡帧不进入零位或拟合样本。
运动 Tag 参考冻结后,若原分支仍有连续、图像质量合格的候选,但另一候选的重投影误差明显更低,
该帧标为 `pose_branch_ambiguous` 并丢弃,内部保留原分支轨迹等待图像证据恢复;
不能仅凭另一候选连续数帧得分更高,就判定冻结参考损坏。不会切换分支、重建零位或把歧义帧送入拟合。
如果持续不存在符合原分支连续性约束的候选,仍在确认后暂停;长期失联后无法确认分支一致时也会明确拒绝。
正式标定方向结束仍检查可信样本、覆盖与稳态点,最多同速重扫一次;诊断模式另报原始观测与可信姿态覆盖。
需要更换分支或重新安装 Tag 时,必须重新开始新会话,
不能把旧冻结参考与新分支数据拼接。原有 0.03 px 容差、35° 跳变、75° 倾角及 1.5 px 重投影质量阈值保持不变。
真实角点噪声、采集时序和最终运动精度仍须通过独立实测验证。
### 首次零位前的公共运动几何确认
新生产会话复用 Profile 已声明的**最后一段归零准备运动**,在 `zero_approach` 中保存父子 Tag 的原始候选,
到 `joint_zero` 后先确认分支,再采集原有的稳定零位帧。没有增加扫描轮次、额外试探动作或型号专用求解器。
几何确认与 SDK 反馈稳定分别检查;几何通过不会提前开启零位采集窗口。
计算在状态锁外进行,期间持续接收 SDK 反馈并保持声明姿态;计算本身有 120 秒上限。
几何确认后,先在原有 2 秒观察窗口内等待恢复后的首个有效零位样本,再用
`joint_zero_timeout_seconds` 限定的独立窗口采齐稳定帧(字段默认 2 秒,四型号产品配置均为 5 秒)。
窗口不会无限延长。正式采集中,每组尚未冻结零位的关节最多自动恢复一次:可恢复的图像
准备失败重新执行该组原有的归零准备路径并采集全新图像;几何已经冻结但零位图像不足时,
保持原姿态和模型,只重新开启一次零位图像窗口。原始失败和恢复动作写入 `joint_zero_recovery`。
已冻结的零位、部分已经提交的多视角几何、保持姿态变化、设备故障不重新拟合;恢复后仍
不足时明确暂停,保留原有反馈、固定基准保护及用户中止能力。
中止、暂停或运动版本改变后,迟到的计算结果不能提交。
前面的避让段、预览、训练扫描和第四轮不参与首次确认。准备段同时核对其他通道的完整保持指令及反馈;
开始后不能改变相机、固定基准或 Tag 安装关系。
生产入口 `core/geometry/tag_pose/production_image_motion.py` 枚举 IPPE 候选家族,
使用父子转动副 `R = exp(theta × axis) R_ref`、`t = pivot + R × mount` 拟合原始角点的重投影残差。
稀疏线性子问题使用 `atol=btol=1e-10`,避免近似计算误差导致外层耗尽迭代预算;
外层收敛条件、默认 150 次迭代预算和各项精度门限保持不变,记录每个候选的求解状态及迭代次数。
父 Tag 本身运动时联合求解整条已声明的观测链;已冻结的上游几何不会重新拟合。
角度来自当前图像,不使用 SDK 到角度的先验、旧 mimic 或 CAD 零位假设选择分支。
单帧 PnP 深度噪声较大时,不再将其三维平移估计直接作为关节运动的真值。
当源 URDF 中两个转轴相邻且平行,并且观测 Tag 实际固定在对应连杆上时,
`profiles/observations.py` 提取零位修正后仍不变的平行关系和垂直轴距。
`CadImageHingeBundle` 消去三个多余几何变量,使准备模型遵守最终 URDF 保留的几何;
不修改原骨长/轴向、不增加权重或 CAD 零位假设。不满足条件的观测链使用原模型。
新冻结模型保存源 URDF 哈希和约束,最终处理从源文件重新推导核验;旧模型保持可读。
修改前的原始图像对照实验及适用边界见 [流程评估](CALIBRATION_PIPELINE_REVIEW.md)。
准备段至少需要 24 帧,训练与留出图像身份分离,默认各最多 72 帧。
训练帧取交错序列,未进入训练的图像才可留出;不因训练帧增加而复用验证图像。
局部几何可观测性检查计入逐帧角度的不确定性,轴线与转心的不确定度界分别不超过 3° 和 3 mm。
候选只按训练图像的平方误差选择;留出数据不用于选优,所选候选验证失败不能改选另一候选。
候选家族还须在准备段留出图像上区分:按运动角度分组,比较与拟合一致的平方误差损失,
差值为 `alternative_rms² - (candidate_rms + 0.03 px)²`,保留原像素容差。
同时通过单侧均值和符号秩检验,再对完整比较集采用 Holm 逐步校正,名义族错误水平保持 0.01。
`image_model_selection.py` 统一负责候选选择、同帧角色对齐、损失比较和多重校正;
诊断记录原始/校正后概率、选择策略和实际源 URDF 约束,失败时也保留这些证据。
缺失、未收敛或无法评估的替代家族不能被当作已排除;几何等价的家族才可合并。
这些检查是图像几何的条件性证据,不是独立毫米精度证明,不能替代第四轮 JSON/URDF 验收。
确认成功后冻结轴线、参考旋转、转心、安装关系及其来源图像。
`image_motion_projection.py` 后续每帧只反解当前图像角度,不重新拟合这些几何参数。
保留 1.5 px 重投影、75° 倾角及单帧角度不确定度检查;信息不足或角度仍有歧义时丢弃该帧,
按现有方向覆盖和最多一次同速重扫处理。35° 连续性和失联后的确认仍由公共 tracker 检查。
Tag 中心接近转轴本身不再是必然失败条件,是否可解取决于全部角点提供的几何信息。
准备段暂时缺帧或候选不确定时,每组尚未冻结零位的关节最多沿原归零路径补采一次;
已确认几何但零位图像短缺时,保持几何和姿态,只重新打开一次图像窗口。
两个恢复方式共享一次额度,保存 `joint_zero_recovery`,不延长成无限重试。
多机位已有部分几何冻结、保持姿态改变、设备故障和诊断采集不会触发重新拟合。
恢复后仍无法确认时不冻结零位、不发布;已有零位和旧数据不能被重新解释后拼接。
`motion_branch_observation` 保存准备段图像、角点、候选及 SDK 状态;`motion_branch_initialization` 保存各假设残差、
冻结模型、来源图像和内容哈希。新姿态来源为 `image_constrained_current_image`,保留原始 IPPE 候选,
同时记录 `frozen_image_model` 与 `image_model_sha256`。每个运动 Tag 的 `motion_evidence_id` 绑定首次证据,
`JointZeroReference.branch_references` 将它与零位、机位和分支版本关联。
正式读取与收尾校验这些关联,缺少证据、篡改来源或删除表头均不能降级为旧图像确认;
`motion_branch_provenance.json` 只证明证据链完整,不是精度证书。
恢复时共享来源只导入一次,关节零位及历史验证记录在该关节实际验证后导入,支持恢复期间再次中止。
正式回放用同一冻结模型复算同帧角点,核对父链、相机、Tag 尺寸及实际提交姿态,不重新拟合模型。
旧 `confirmed_branch_v1/v2/v3` 及 v4 三维候选约束记录仍按原语义读取,不能自动升级或恢复成新 v5 证据。
`motion_evidence.py` 的旧三维筛选入口保留供历史兼容和诊断。这里 v5 仅指姿态策略,最终标定 JSON 仍为 schema v3。
真实 O6 `20260914_175815` 的旧三维筛选只读回放中,yaw 与 pitch 分别存在唯一通过几何条件的家族;
但 pitch→IP 的四种父子组合全部超差,IP 转心 RMS 约 4.9–11.4 mm,完整拇指链仍为 `unresolved`。
这批图像来自旧零位冻结之后的单轮诊断扫描,只能用于反事实回归,不能代替新准备段证据、
覆盖旧零位或证明 JSON+URDF 精度。
可复算摘要见[本次分支修复回放](../../calibration_output/O6_RIGHT_001/20260914_175815/motion_branch_fix_review/README.md),
测试夹具同时保留“yaw/pitch 可分”和“IP 不得强行通过”两类断言。
后续 `20260914_200044` 的图像求解回放使用其真实归零准备段冻结模型,后续 838 帧可复算通过当前图像检查;
这仍是单轮诊断回放,不是完整四轮精度验收,也不会生成正式 JSON 或 URDF。
`20260915_104446` 正式实采中,拇指三个关节各冻结 10 帧零位并完成四轮,
pitch/IP 的旋转及指令单表子项均通过;yaw 旋转通过,但指令单表 MAE 为 1.0454°,超过 1°。
两场独立会话均观察到稳定方向差,该批观测即使允许每个指令任取一个输出角,MAE 下界仍超过 1°。
这不是通过重新拟合单表能够消除的误差;方向分支的诊断通过也不能冒充单表通过。
详见[拇指实测子项报告](../../calibration_output/O6_RIGHT_001/20260915_104446/motion_holdout_review/README.md)。
后续 `20260915_111401` yaw 保持实测在 64/128/192 各双向保持 10 秒;末 3 秒的方向差
分别为 2.2965°/2.7885°/2.1248°,每个窗口均有 90 帧可靠观测,同一目标的 SDK 反馈相同。
0.5–1 秒至末段的角度变化最多约 0.038°,延长等待没有消除方向差。
本轮仅启动顶部机位,不能据此确定具体机械原因或证明整手精度;继续保留单值 JSON 与原验收门槛。
复现脚本、时间曲线与来源哈希见[双向保持实测](../../calibration_output/O6_RIGHT_001/20260915_111401/yaw_hold_review/README.md)。
`20260915_104446` 会话在小指准备求解超时后停止,未完成整手空间/FK 验收、未发布 JSON/URDF。
小指同源准备段离线求解只需约 3.42 秒,但候选仍未达到统计区分要求;运行时超时来源尚待定位,
详见[小指准备段核查](../../calibration_output/O6_RIGHT_001/20260915_104446/side_preparation_review/README.md)。
后续会话另存 `motion_solver_diagnostic.jsonl`,记录请求来源哈希、版本、求解耗时和提交接受/拒绝,
以区分求解未返回与迟到结果被丢弃;该文件不参与测量授权,也不修改已冻结的原始记录。
此诊断接线在上述实采之后添加,不能补证该次超时原因。
固定基准另有明确的静止约束:锁定后始终使用首次冻结的相机局部姿态,将其投影到当前角点验证,
不因 IPPE 两支重投影误差排名反转而更换姿态或暂停。仍执行原有 1.5 px 重投影和 75° 倾角限制,
并保留当前 IPPE 候选与原有角点漂移监测。当前图像无法验证冻结姿态时丢弃依赖该基准的观测,
记录 `fixed_reference_pose_unverified`,不将几帧图像质量不合格判为不可恢复的姿态分支冲突。
恢复须默认至少 5 个合格帧且跨越至少 0.1 秒,始终核验同一冻结姿态,恢复完成前也禁止缓存兜底。
尚未使用该机位的动作可以继续;当前任务持续缺少有效数据时,仍按原有零位超时、稳态采样和最多一次同速重扫处理。
固定基准实际连续 10 帧漂移超过 5 px 仍使整场暂停,包括当前任务未使用的机位。
此约束仅用于 Profile 声明的 `fixed_reference`,
不用于随关节运动的 Tag,也不证明初始分支物理正确或当前外参已经实测验证。
方向结束才检查 ≥40 个有效同步样本、≥32 分箱、内部空白 ≤行程的 1/16、规定的有效行程覆盖,
以及 Profile 声明的端点/双视角观测。数据不足只同速重扫一次;第二次失败暂停。
拟合或最终文件验收失败不重新自动运动、不更新发布指针。
`independent_rotation_holdout_failed` 表示前三轮冻结旋转模型未通过第四轮检查,发生在空间求解前。
错误原因包含失败关节、机位和 MAE/P95/最大误差;`fit_diagnostics.json.rotation_holdout`
另存完整 SO(3)、轴向、偏轴统计及最坏图像身份。验收使用完整旋转误差,不能仅凭投影角度曲线重复判定通过。
新采样行的 `pnp_observation_evidence` 保存父子 Tag 的当前角点、尺寸、已选姿态和候选诊断,
相机矩阵引用同会话的 `rectified_camera_model`。缓存固定基准明确标注来源,不伪造当前帧的角点或候选。
可见且通过冻结姿态投影验证的基准标为 `verified_fixed_reference`,保存当前角点、IPPE 候选和实际投影误差;
完全未检测到时的缓存仍标为 `cached_fixed_reference`。候选回放保持同一冻结基准并复核前者的当前角点证据。
短程诊断报告以 `fixed_reference_summary` 单独统计基准的当前图像投影误差,
不会把固定输出姿态的零跳变误当作独立测量结果。
不合格姿态事件另外记录当时的动作阶段、指令与同步反馈,便于区分准备动作期间的异常与正式采样异常。
角点与候选记录用于诊断;其中分支状态、版本及实际选中姿态也用于核验冻结参考的一致性,
不使历史采集自动获得缺失的观测证据。O12 的轨迹几何评分仍只使用训练轮,
但正式收尾不得用评分更好的另一支替换已冻结的训练或第四轮姿态;超过同一公共等价界时明确拒绝发布。
历史记录仍可在离线诊断入口分析候选,不能借旧格式标记绕过正式产物的冻结分支检查。
所有型号显示相同进度:阶段、任务/轮次/方向、分机位 Tag ID、命令/反馈/单位/速度、
有效数据、基准、断点来源,以及中文原因、建议和原始诊断。
ROS 收尾拟合在独立进程执行:只读取采集结束时已同步的日志前缀,后续图像不进入拟合;
主进程继续接收反馈并检查固定基准,阶段事件按原顺序回传,最终发布仍由主进程持锁完成。
中止时终止计算子进程,不允许子进程更新发布指针。`finalization_timing.json` 保存实际耗时。
标题明确显示型号、左右手和序列号。开始前等待状态列出缺少或过期的相机内参、检测消息和 SDK 条件;
空 Tag 检测消息可以证明视觉链路工作,不要求开始前已经识别全部 Tag。
收到开始请求时重新检查设备状态;实时 CameraInfo 参数必须与受保护外参中的指纹一致。
开始前相机消息的新鲜度窗口为 2 秒,该窗口不用于扫描中的实时暂停。
## 唯一生产代码链
```text
linkerhand_calibration/
├── config/ 旧资源路径,兼容现有产品配置
├── urdf/ 旧 URDF/mesh 路径,兼容 package:// 引用
├── docs/ 共用记录
├── launch/ ROS 统一启动入口
└── linkerhand_calibration/
├── models/ G20/L6/O12/O30/O6 专属代码、配置、URDF 与说明
├── profiles/ 加载、静态验证、Tag/CAD 观测关系
├── core/domain/ Profile、样本、CalibrationResult、状态
├── core/geometry/ 相机、变换、PnP 兼容导出
│ └── tag_pose/ IPPE、连续跟踪、冻结前运动证据、刚性组和轨迹选择
├── core/fitting/ 运动曲线、线性耦合、固定安装
│ └── spatial_solver/ 空间观测、基座、零位、统计与独立验收
├── core/urdf/ 授权修正、FK、范围与最终文件验收
├── runtime/runner.py 唯一产品启动器
├── runtime/coordinator.py 会话协调、采集提交、运动和收尾接线
├── runtime/parameters.py 已解析的运行参数;无 ROS 类型
├── runtime/inputs.py 相机/检测输入、时钟与发布接口
├── runtime/cameras.py 受保护相机身份与消息新鲜度
├── runtime/camera_preflight.py 启动前配置检查结果与内外参实测能力边界
├── runtime/session.py 唯一在线状态机
├── runtime/execution.py Profile 任务与运动效果调度
├── runtime/motion_execution.py 平滑轨迹与位移到位判定
├── runtime/capture.py 多机位视觉/反馈采集
├── runtime/branch_initialization.py 最后归零准备段证据与一次性几何确认
├── runtime/branch_tracking.py 冻结约束选候选,原子提交同帧姿态与证据
├── runtime/motion_provenance.py 读取和收尾核验来源内容、零位与样本关联
├── runtime/scan_quality.py 唯一方向数据门
├── runtime/reference_lock.py 开始后固定基准
├── runtime/resume.py 整场断点证据检查
├── runtime/joint_resume.py 逐关节原零位验证后导入旧样本
├── runtime/safety.py 最小实时保护
├── runtime/status.py 统一状态与中文显示
├── runtime/snapshot.py 类型化状态快照与旧状态映射
├── runtime/adapters/ SDK 协议,不包含标定业务
├── runtime/ros/ ROS 参数加载、消息转换、订阅/服务/定时器
├── runtime/artifacts/ 收尾控制、后台 finalizer、serializer、原子发布
└── compat/ 历史格式、布局与离线诊断;不提供旧在线流程
```
`calibrate_hand → runner → runtime/ros/entrypoint → UnifiedCalibrationNode → CalibrationCoordinator → SessionExecution`
是所有型号的生产调用链。节点直接继承 ROS `Node`,组合 `RosCalibrationIO` 和协调器,
不通过父子类业务回调执行标定。SDK 绑定接收明确的反馈新鲜度、时钟、健康订阅和发布接口。
空间入口 `core/fitting/spatial.py` 保留显式兼容导出,计算顺序在
`spatial_solver/solve.py`:输入准备 → 仅训练求解 → 可观测性/轮间统计 → 冻结结果的独立验证 → 结果装配。
`TrainingProblem` 不包含第四轮观测,训练几何中的掌部姿态也按训练轮筛选。
基座策略由 Profile 的几何约束选择;曲线、零位坐标约定、权重、阈值和原始 URDF 授权修正规则不变。
PnP 的原导入路径继续可用。`tag_pose/parameters.py` 集中定义跟踪默认值,
ROS 加载器将角度参数由 deg 转为 rad,离线采集直接使用同一套默认值。
公共分支容差仍为 `0.03 px`,重投影质量和倾角限制保持一致;首次确认、参考冻结与失联恢复
使用同一公共分支策略,ROS 和离线链路均不能绕过它。
`CalibrationSession.phase` 是流程状态来源。协调器在状态锁内开始、中止、推进和提交观测;
耗时姿态计算在锁外进行,提交时核对会话版本、采集对象、运动对象及稳态采样边界。
Start 更换预览采集对象并重新锁定基准,暂停/中止使尚未完成的旧观测失效。
收尾由 `FinalizationController` 组合 worker 和发布器,worker 只上报阶段事件、准备候选文件;
协调器核实全部验收阶段后才能提交。锁顺序固定为状态锁 → worker 锁,
拟合失败维持当前姿态,中止后禁止提交,成功产物只提交一次。
老的单相机拇指/CMC 在线节点和 launch 已退出安装入口;需要局部测量时应增加经过验证的 Profile,
不能重新启用旧状态机。老版本离线诊断不是新的标准 URDF 发布证据。
## 新增型号
必需文件:
```text
linkerhand_calibration/models/new_hand/config/profiles/new_hand.yaml
linkerhand_calibration/models/new_hand/config/new_hand_product.yaml
linkerhand_calibration/models/new_hand/urdf/right/raw.urdf
linkerhand_calibration/models/new_hand/urdf/right/meshes/*
```
Profile 声明:
1. Adapter、SDK 通道顺序、单位、正负方向、命令/反馈范围、基准值、独立速度槽布局。
2. Tag ID/尺寸/机位/安装 link,以及每次运动的父子观测关系;不明确的 link 不能靠名称猜。
3. 扫描任务、速度、准备/避让/收尾 waypoint;每关节首次零位任务、完整保持指令及固定到达姿态。
4. 声明空间可观测约束、已知 baseline 几何或明确接受的 CAD 零位假设;每个运动关节须独立观测或显式指定对应实测来源。
5. 每关节允许修正的 `origin.rpy`、`limit.lower/upper`、`mimic.multiplier/offset`。
这仍需要正确的可观测性设计:单轴加一对未知安装角的 Tag 不能自动辨识绝对 CAD 零位。
不能为了减少配置,默认把 SDK 零点或最大指令当成 CAD 零位。可参考最简单的 L6/O6 Profile,
删除不适用关系后重新声明;不要盲目复制另一型号的空间约束。
复用 SDK 不增加 Python;新协议只增加 `runtime/adapters/` 实现及协议工厂注册。
没有型号节点、runner、状态机、质量/断点/发布器;新数学只能增加通用拟合原语。
新型号使用 `artifacts.output_schema_version: 3`;产物为
`format: unified_calibration_v3, schema_version: 3`。详细双映射保留在独立标定报告中。
旧 generic v1、v4/v6/v7 只保留历史兼容工具,不把反馈表改名为指令表来伪造兼容。
v1/v2 按原语义读取,不会自动升级为独立实测;保留的 v2 数学入口用于历史回归,不能证明 v3 精度。
配置错字、错误绑定、未知修正字段在启动前失败;修改受保护文件后应审查并更新对应 SHA256。
## 产物与离线验证
会话目录保存原始样本、冻结 Tag 安装、拟合诊断、标准 URDF 验收、JSON、URDF。
有效发布由 `release_manifest.json` 及产品发布指针共同证明;单独的 `PASS` 摘要或存在 URDF 文件不等于已发布。
manifest 记录 JSON、URDF、标定报告三文件 SHA256、受保护输入和独立 holdout 证据。任一验收失败都不会替换原发布指针。
`measurement_contract.json` 提前列出 Tag/link、零位观测关系、CAD 保留/迁移与原始 mimic 限位冲突。
主 JSON 以原始 URDF 关节名为键,单值关节包含 `sdk_channel` 和 `angle_rad`;
O12 等 rad 输入还包含一一对应的 `input_values`(在有效节点间线性插值,不外推)。
字节型号每条曲线固定 256 项:SDK 指令 `v` 对应所选曲线的第 `v` 项,只能在训练指令实际覆盖 0–255 时导出。
输出均是修正 URDF 的 q_output,不再加零偏。顶层记录身份、单位、完整 `baseline_command` 和共同零位约定。
独立观测的主动和被动关节直接导出各自视觉曲线,同一驱动通道可绑定多个关节。
显式复制的关节使用来源关节的同一组节点与角度,不重新拟合、归零或由 mimic 推导;接收通道保持不变。
默认单值曲线在指定的稳态训练数据中约束 baseline=0,正反向诊断分支共用冻结参考、保留回差。
独立稳态验证分别检验两个方向;超差时禁止发布,不隐藏切换分支。
O6 侧摆 `rh_thumb_cmc_yaw` 通过 `artifacts.directional_command_joints` 显式启用双向指令曲线。
v3 JSON 顶层保存同名声明,所列关节额外包含 `increasing_rad` / `decreasing_rad`;
方向指原始 SDK 数值增加/减少,与关节角度正负无关。其他关节继续使用单值表。
两条曲线分别只用所声明的稳态训练数据拟合,共用已冻结零位、各自满足 baseline=0;
独立稳态验证按实采方向读取最终序列化曲线,仍要求 MAE≤1°、P95≤2°、最大≤3°。
报告分别保存运动与指令映射的训练/验证分区及来源图像,限位推导仍不得使用任一验证分区。
`angle_rad` 保留为均值参考;双向关节在非 baseline 输入且方向未知时禁止用均值代替。
读取器须从 baseline 初始化,停住时保持到达方向,允许端点换向;行程中途反转尚无小回环标定证据,会明确拒绝。
字节指令的方向判断与查表共用 `floor(v+0.5)` 量化规则;连续小数步进不能绕过方向切换检查。
两条主回环曲线不构成任意反转、负载或多轴工况的精度证明。旧读取器会拒绝新增关节字段,须同步更新。
修正 URDF 保留原被动关节 `<mimic>`,单独拖动父关节滑条时,末节按
`q_child ≈ multiplier × q_parent + offset` 联动。标准 URDF 不能将查找表表达为 mimic。
前三轮成对视觉角度用于拟合线性近似,优化变量为父关节两端对应的子关节角度;
两端都限制在子关节原有输出范围内,因此整个联动行程合法,无需放大限位或裁剪小负角。
偏移是近似直线在 baseline 的误差,不能当作新的物理零位;报告明确保存
`baseline_error_rad`、`physical_zero_correction: false` 和独立留出误差。
JSON 指令/反馈曲线、几何零位不因近似拟合改变。需要实测非线性运动时使用完整 JSON,
消费程序显式设置全部关节角,并避免 URDF mimic 再次覆盖末节角度。
原始 CAD 限位默认仍是硬边界。Profile 可逐关节显式声明 `calibrated_motion_envelope`,
将该 CAD 限位视为本次要测定的运动范围;只有已授权的 `limit.lower/upper` 可据此修改。
O6 右手采用此策略,范围由前三轮运动反馈映射、独立稳态训练映射的实测包络及共同零位确定,
不增加安全余量,不用第四轮扩展范围,也不为容纳 mimic 越界而放大范围。
SDK 安全指令域不变,IP/DIP 的 CAD 零位不变。复制关节的范围证据仍属于来源关节。
报告和 manifest 的验收数据保存 `motion_range_evidence`,包含来源限位、零偏、训练轮次、
样本身份与新范围,并在收尾重新验证。O6 尚无独立机械安全角度界的实测证据,
该策略不代表对碰撞、过载或任意多轴姿态作出安全认证。
验收分别记录:最终 JSON 对独立稳态验证角度;完整 JSON+URDF FK 对独立验证 Tag 位姿;
仅使用 URDF mimic 的近似损失。前两项决定实测精度通过,第三项如实报告,不冒充非线性精度。
manifest 同时保存 `urdf_joint_angle_source: calibration_json`、`urdf_mimic_policy` 和两种回放结果。
门限保持角度 MAE≤1°、P95≤2°、最大≤3°,Tag 位置 P95≤3 mm。
平行转轴的零位计算先消除轴上参考点的任意坐标,再比较相机平面中的轴间方向;
改变同一轴线的表示点不能改变标定零位。这是所有型号共用的几何规则。
独立精度结论只覆盖实际观测的关节和 Tag;复制关节另检查来源、查表一致性、通道与机械范围,
不把来源关节的第四轮误差称为接收关节精度。混合产物 manifest 使用
`measured_and_transferred_json_urdf_v3`,列出实测和复制覆盖。
FK 使用训练冻结的安装与基座;第四轮不拟合零位、曲线、Tag 安装或基座。
正式图像采集还要求核验第四轮及独立稳态验证的原始 Tag 四角,沿用冻结的安装、基座
和受哈希保护的相机参数。主观测的独立三维位姿必须解释同帧原始角点,四角重投影 RMS
不得超过原 1.5 px;最终落盘 JSON+修正 URDF 与独立位姿的差异仍按上述角度和位置门限检查。
最终 FK 的总像素误差单独报告,不能将包含允许运动误差的总量等同于图像测量噪声。
额外机位没有独立三维测量时,仅检查是否存在满足原物理误差范围、且重投影误差不超过
1.5 px 的局部刚性位姿。这个数值见证不是真实位姿测量,不写回安装、零位、曲线或相机;
各运动任务分别检查,不能用其他任务中的静止图像稀释误差。它不能替代必要的独立三维验收。
缺少独立测量或原始图像、相机身份不一致、测量像素或物理误差超限均不能发布。
失败时保留 `final_image_diagnostics.json`;通过后在 manifest 记录 `final_file_image_holdout`
及规则版本 `independent_measurement_and_physical_consistency_v2`,分别列出独立精度与额外视角相容性。
训练阶段若 Tag 与整条运动链不满足刚性一致性,`tag_installation_diagnostics.json`
一次列出全部 Tag 的角度/位置 P95、门限和通过状态,不只显示遇到的第一个失败 Tag。
该失败不能直接归因于硬件松动,也不能作为自动重做整场采集的依据。
`calibration_report.json` 保存完整的 `command_to_rad` / `feedback_to_rad`、输入域、方向分支、
实测关节的零位原始参考帧、完整指令/反馈/到达方向、来源和训练/holdout 指标。
复制关节记录 `independently_measured: false`、`transferred_from_joint` 与来源参考链接,
不生成自己的伪零位样本或独立精度指标。绝对零位来源另由 `zero_method`、
`cad_zero_assumption` 或 `zero_transferred_from_joint` 表达。报告中的 `applicability` 记录保持姿态;
未采集多姿态证据不能宣称任意多轴工况已验证。主 JSON 用于指令查表,不能误作反馈转换。
旧 unified v1 会话继续只读兼容,不自动覆盖或转换历史产物;新输出单表必须重新通过最终文件验收。
统一消费桥可直接读取通过验证的 manifest(纯消息转换,不会发送实机命令):
```bash
ros2 run linkerhand_calibration calibrated_joint_state_bridge --ros-args \
-p calibration_file:=<session/release_manifest.json> -p input_kind:=command \
-p input_topic:=<SDK原始指令话题> -p output_topic:=/calibration/verification/joint_states
```
需要反馈角度显示时显式选择 `input_kind:=feedback`,桥读取配套报告中的反馈映射。
桥检查三文件哈希、拒绝越域输入,
v3 全部关节角由 JSON 显式计算,不加第二次零偏。完整 FK 使用
`independent_mimic_angles=True`,以 JSON 给出的末节角度覆盖线性近似。
标准 `robot_state_publisher` 和普通 URDF 网页查看器会执行 mimic,适合检查近似联动;
仅把完整 JointState 发给标准 RSP,不能让它停止覆盖被动角。
消费实测非线性曲线的仿真程序必须明确采用 JSON 角度,关闭重复的线性被动更新。
仿真输出不能与实机反馈话题同名。
MuJoCo 是用户后续使用的外部验收项目,本轮不改动它、不增加 MuJoCo 依赖,自动标定不要求打开 GUI。
外部对比须确认加载的模型来自这份 URDF,指令转换使用配套 JSON;不能用实机反馈直接驱动仿真来证明指令映射。
现有 MuJoCo 脚本尚不能视为支持 v3:后续须消费完整关节映射并停止冲突的线性被动更新。
```bash
# 同一算法离线回放新策略的完整采集;不启动硬件,默认不发布
ros2 run linkerhand_calibration calibrate_hand --config <product.yaml> \
--offline-raw <raw_samples.jsonl> --offline-output <新的输出目录>
# 只比较两份 URDF,不修改,不控制机械手
ros2 run linkerhand_calibration compare_calibration_urdfs \
--reference <参考.urdf> --candidate <本次.urdf> --output <新报告.json>
```
离线回放也检查原始会话策略、SDK 输入域、配置/相机证据、每方向完整数据及最终文件。
旧会话不能自动获得当前哈希或新版本认证。`--publish-offline` 必须显式给出,且不会绕过验证。
当前坐标规则、生产职责与验收范围见 [v3 实施记录](CALIBRATION_V3_IMPLEMENTATION.md)。
早期需求审查见 [2026-09-10 需求审查](CALIBRATION_CODE_REVIEW_20260910.md);
当前修改依据、实机结果与未完成的精度验收见 [流程评估](CALIBRATION_PIPELINE_REVIEW.md)。
相机和反馈目前均采用下述测量时间;时间配对正确仍须经过独立空间验收。
### 实时调度边界
公共 ROS 节点顺序处理控制和反馈消息;耗时图像估计由每视角有界工作队列执行。
图像最多在原同步容差内等候真实反馈时间覆盖,队列不反向持锁查询会话。
增加执行器线程数不能提高共享状态的处理能力;反馈超时仍按真实测量判断。
暂停或验收失败的会话仅提供诊断/候选文件,不能当作已发布的标定结果。
调度对照依据与验证范围见 `CALIBRATION_PIPELINE_REVIEW.md` 第七轮评估。
### 相机与反馈时间
连续扫描将 CAN 实测反馈与相机曝光中点配对。MVS 取帧/图像发布时间不参与替代曝光时间;
设备时钟由独立锁存换算到 ROS 时钟,换算依据保存在会话的 `camera_timing_<view>.jsonl`。
运行中的时钟校验失败会暂停出图并重新执行独立锁存校验,通过后恢复采集;校验失败期间不会继续使用旧映射,也不会永久退出采集线程。恢复前后的图像时间戳仍须严格递增;若主机时钟向后跳变,早于已发布图像的帧继续丢弃。
四型号共用 `unified_engine_v8_all_view_images`,保留设备曝光时间策略;旧采集只能按其原策略诊断,不能混用。
报告中的 `feedback_u8` 表示来自字节通道的测量值:插值到曝光时间后可以是小数,
拟合、内存映射和报告读取均按声明的分段线性曲线计算,不再次取整。
`command_u8` 仍按实际发送的整数字节查表;旧版整数表保留原读取规则。
相机时钟修正不会将被动关节的非线性曲线转成 URDF mimic;仿真仍须读取 JSON 查找表。
### 同一运动中的所有机位原始角点
四轮扫描、必要稳态点和关节基准采样期间,所有机位均保存 `image_observation_frame`。
记录包含曝光时间、完整指令/反馈及方向、轮次与尝试编号、相机矩阵和可见 Tag 的二维角点。
它经过原检测质量与采集窗口检查,但不依赖 PnP 分支或任务的主机位。
缺少同步反馈时保留明确的空值,不能将该帧当成有效角度测量。
例如 O6 顶部 ID7 与正面 ID2 属于同一末节:弯曲和侧摆时两机位的可见角点都应保存,
以便检查整条运动链。其他机位的记录不会增加停点或运动次数,也不会替代主机位的采样覆盖要求。
同机位重复帧不重复入库;暂停、切换运动和结束采集时仍按同一会话身份撤销迟到数据。
最终 JSON/URDF 的图像验收使用通过采集检查的第四轮和独立稳态验证窗口内全部机位角点。
主观测必须能与原始图像记录逐项对应,同一图像不能重复计数;其他动作下的有效角点也直接
投影验收,不先拟合成三维位姿。缺少主观测的原始记录或二者 SDK 条件不一致时拒绝发布。
这不表示联合求解或外参自校准已经通过验证。
## 低精度离线修正草稿(O30)
最新程序修复、两批实采数据验证及未通过的精度项目见
[O30_AUTOMATIC_URDF_FIX.md](linkerhand_calibration/models/o30/docs/O30_AUTOMATIC_URDF_FIX.md)。
当前目标是 **15 个非末端关节零位+20 个关节运动范围**;拇指 IP 与四指 DIP 的五个
末端零位保留 CAD,其运动范围仍由数据拟合。完整全手数据可提供局部拇指缺少的掌坐标
约束;只采部分任务时,不能将局部输出当作上述全手目标已完成。
O30 原始采集正常结束后,启动器完成归位封存、关闭 SDK/相机及控制上下文后退出。
`capture_result.json` 只报告采集结果,完整返回 0、缺项返回 3,不自动拟合。
每个新会话保存可供离线使用的 `capture_product.yaml`、Profile、源 URDF、内外参和
标签配置快照,并随原始证据封存。离线失败不改变采集状态,也不会再次运动。
也可手动从已完成任务生成完整结构的修正 URDF,再优化精度:
```bash
ros2 run linkerhand_calibration calibrate_hand \
--config /绝对路径/会话/capture_product.yaml \
--offline-raw /绝对路径/会话/raw_samples.jsonl \
--offline-draft --offline-output /绝对路径/新的草稿目录
```
草稿复用现有图像拟合器、零位约束和 URDF 写入器。训练数据估计可观测的零位及
双向指令曲线,验证数据仅报告误差;超过原精度门限仍可生成文件。
未独立观测的反向换向端点采用有来源的连续性约束,不保留可任意改变行程的自由参数;
约束写入 `motion_range_evidence.command_support`。缺少端点依据时拒绝生成行程。
`draft_urdf_linear_holdout.json` 单独报告纯 URDF 上下限线性驱动的误差;曲线精度
不能替代线性驱动验收,未通过精度验收的草稿不更新正式发布指针。
每个任务至少有一轮完整训练即可参与草稿求解,另一训练轮已通过采集质量检查的
完整方向也保留;不拼接失败尝试,不用第三轮补训练缺项。初始化使用该任务已完整的
训练轮,逐任务覆盖与选择理由写入 `draft_result.json` 的 `training_selection`。
父关节观测约束仍保留;草稿可覆盖全手与原始采集完整是两个独立结果。
缺测关节保留原 CAD,单根手指无法观测的根零位及已声明的 CAD 末端零位单独列出。
不从数值不可观测的自由度导出任意零位。JSON 读回、字段授权、运动范围、最终 FK、
标准 URDF 加载和来源哈希检查仍必须通过。
离线模型纠错可使用单独的 Profile/Product 文件,只允许修改标签连杆绑定和
`sdk_to_joint_direction`;原始会话仍按保存的 `capture_profile.yaml` 校验。
基准 SDK 指令、通道、采样路线和速度不允许借此更改。新旧方向及配置哈希写入
`draft_result.json`,不重写原始记录,也不影响在线控制。
求解前以训练轮的双向运动和两种平面姿态候选检查 CAD 平行根轴的方向一致性;
所有候选均反向时拒绝拟合,记录 `draft_sdk_to_urdf_direction_conflict`。
不能靠零位补偿错误的 SDK/URDF 方向。文件能加载及参数数量齐全,也不等于物理零位正确。
现场明确确认四指在采集基准指令下竖直时,离线命令可增加
`--draft-upright-splay-zero`。此选项先检查源 CAD 的四指零位为掌坐标竖直,
再从求解变量中移除四个侧摆零位,重新拟合其他零位与全部指令曲线;不是导出后改姿态。
JSON 将这四项标为 `operator_defined`,分别统计 11 个拟合零位、4 个用户定义零位及
5 个 CAD 末端零位,不能把四个定义值当作独立测量。原始基准指令、采集配置和记录不变;
该选项不能进入在线采集或正式发布。
同批数据已有局部草稿时,可增加 `--draft-initialization-from /绝对路径/已有草稿目录`。
入口核对原始数据及配置身份,只读取训练选出的起始姿态和曲线;所有待求参数仍在
全手训练图像中联合调整。不同批次、使用验证选择的结果不能作为该初值。
其文件哈希和用途写入新报告,不覆盖已有草稿。
全手草稿按相同标签、相同祖先关节指令/方向及相机参数合并重复预测,使用样本数权重
及组内散差保持原始最小二乘目标、梯度与信息矩阵;误差报告仍逐张原始图像计算。
草稿数值停止 `ftol=1e-5`,正式求解保持 `1e-9`;这不改变任何精度、可观测性或
发布门限,草稿无论数值收敛与否都不能自动更新 `latest_passed`。
草稿最多保留四个收敛初值的候选并按训练误差选择,报告已计算初值数量及是否穷尽;
不以这个有限搜索声称已排除全部几何解。正式候选搜索与发布验收保持原规则。
输出 `o30_right_draft.urdf`、`draft_calibration.json`、`draft_result.json` 及训练/验证报告。
草稿 JSON 使用独立格式,不作为正式控制映射或精度证书自动加载;URDF 可标准加载。
该入口允许读取中断会话的完整方向,不启动 SDK、不补采、不更新 `latest_passed`。
`--offline-draft` 不能与 `--publish-offline` 同用,正式精度验收入口保持不变。
若旧数据的标签连杆配置有误,提供 `--capture-profile /绝对路径/原Profile.yaml`;
新会话已保存 `capture_profile.yaml` 时会自动使用该快照。
先核对原 Profile 与会话哈希,再仅允许当前 Profile 修正标签安装连杆。
标签身份、尺寸、运动策略、相机与 CAD 来源不允许借此改变,原始记录保持只读。
采集中途重新安装移动标签时,不能直接沿用该标签原来的安装参数。O30 草稿流程可先
离线建立新断点,再按普通断点恢复:
```bash
ros2 run linkerhand_calibration calibrate_hand \
--config src/linkerhand_calibration/config/o30_right_product.yaml \
--prepare-remount-from /绝对路径/原会话 --remounted-tag-id 10
```
此步骤不启动相机或 SDK。只允许保留调整标签之前连续通过的任务前缀;原会话不修改,
新断点按 CAD 拓扑排除受影响手指的全部旧标签角点,从首个受影响任务重新采集,
其他方向的补采次数保持原值。未开始新扫描的准备断点可扩大排除范围;已开始的尝试
不能借此重新获得预算。
原会话保存一次性后继指针,后续重启使用普通恢复,不能再次从旧安装重置尝试次数。
原始角点续采时,活动标签在同一 SDK 基准指令下的像素/反馈差异及不可见情况
列为“待离线复核”,不将回位姿态差异直接判成标签重装,不据此暂停采集。
固定基准、配置身份及运动保护仍须通过。前后安装参考、差异和原补采预算均保留;
未核实差异只允许进入未认证修正草稿,正式发布仍拒绝未复核的安装关系。
标签必须仍在原配置连杆上;若移到了其他指节,先修正连杆绑定。
+817
View File
@@ -0,0 +1,817 @@
# 标定测试的执行范围
2026-09-24 O30 剩余误差诊断:只读两批封存数据及已冻结参数,旧/新独立验证图像
分别 2681/516 帧;按机位/标签/任务/指令拆分残差,受限试探仅用训练图像选参数、
验证轮报告结果。顶部相机在新拇指 roll 三轮只见固定标签;跨批食指端点偏差及
拇指 roll 高角度重复性残差已定位。JSON/URDF 逐字节差、来源哈希和所有试探结果
记录于 [O30_REMAINING_ISSUES.md](linkerhand_calibration/models/o30/docs/O30_REMAINING_ISSUES.md)。未修改生产拟合、采集、
门限或已生成候选;诊断结果不计作正式精度测试通过,也未驱动硬件。
2026-09-23 自动 URDF 修复:采集/局部/重装组 43 passed(17.06 秒),离线草稿及
换向端点组 43 passed(34.18 秒),更新审计 3 passed(0.33 秒)。完整真实
coordinator 的虚拟时钟 108 方向集成 1 passed(97.21 秒),用于核对完整调度和
训练/验证隔离,未启动硬件。最后补齐快照 mesh 与封存路径检查后,仅复查受影响
4 项,4 passed(2.38 秒);此组与前面重叠,不重复累计。
早期失败包括旧夹具仍使用已纠正的标签/方向配置、近端插值掩盖未观测换向端点;
分别修正历史场景声明、改用有来源的端点连续性约束后通过,没有降低验收门限。
旧外参全手与新外参拇指均按自身配置回放,训练重新收敛,JSON 重建 URDF 字节
一致,FK 最大差 6.66e-16,ROS/MuJoCo 加载通过;独立精度仍未通过,未发布。
证据、物理精度限制及候选路径见 [O30_AUTOMATIC_URDF_FIX.md](linkerhand_calibration/models/o30/docs/O30_AUTOMATIC_URDF_FIX.md)。
2026-09-23 离线逻辑复核:复用连续候选关联替代逐帧 PnP 排序,扫描起点按扫描身份纳入;
补全欠约束 SVD 零空间,范围证据记录实际可见训练样本和轮次,单轮仅允许未认证草稿。
新增 7 项集中回归通过;其余受影响项分组通过。首次 24 passed/4 failed/2 errors(22.21 秒)
中的失败分别为未 source ROS 和新增夹具字段名错误;修正后对应及 CLI 10 passed(2.13 秒)。
范围边界组 5 passed(1.20 秒),中节绑定/历史数据隔离组 2 passed(1.12 秒)。
用户确认 ID12–ID15 随中节运动后,新离线配置将四标签绑定至 `*_middle`;封存数据回放生成
`offline_confirmed_middle_tags_draft`,训练坐标 RMS 1.4867 px,最终 FK 差 5.55e-16。
四指角度子项通过,但拇指 roll/MCP 及全局图像/不确定度未通过;未发布,未控制实机。
详细问题、证据和复现命令见 [O30_OFFLINE_LOGIC_REVIEW.md](linkerhand_calibration/models/o30/docs/O30_OFFLINE_LOGIC_REVIEW.md)。
2026-09-23 四指侧摆竖直基准:新增显式离线选项 `--draft-upright-splay-zero`,
四项作为用户定义基准移出自由零位参数,全部行程与其余零位重新拟合。
新增/CLI 用例 6 passed(13.04 秒),相关范围、缺项、导出及生命周期用例
18 passed(16.88 秒)。`offline_upright_zero_draft` 最终 URDF 的四指正面侧偏均为
0°;JSON/FK 最大差 8.89e-16,标准加载与来源哈希检查通过。
报告区分 11 个拟合零位、4 个用户定义零位、5 个 CAD 末端零位和 20 个拟合范围。
本次独立验证已算出角度误差,但整手精度仍未通过,未更新 latest_passed。
原始数据保持不变,未进行硬件运动;上一版侧摆偏移 −6.6° 至 −9.4° 的草稿已附拒绝说明。
2026-09-23 物理零位复核:旧 `offline_full_hand_draft` 因四指 SDK/URDF 方向反转而
错误估计约 −20° MCP 零位,已附拒绝说明,不能将其文件检查通过理解为零位正确。
独立离线配置纠正方向后,`offline_corrected_zero_draft_v2` 的四指 MCP 为
+0.385°、−0.306°、−0.690°、−1.475°,没有强制置零;JSON/URDF FK 最大差
7.78e-16、标准加载及原始数据哈希检查通过。独立验证求解器仍报 IndexError,
保留 traceback,精度/发布均为 False;没有硬件动作。
本次 `test_raw_draft.py` 27 passed(30.15 秒),新增实采角点方向回归、离线模型
修订边界及验证求解异常不冒充精度通过的检查。原始数据仍为 107/108 单元。
全手草稿候选搜索收敛为最多四个收敛结果,明确记录非穷尽;相关数值不可观测拒绝、
候选预算和训练初值契约 3 passed、21 deselected(0.90 秒)。
实机封存数据 `20260923_142201` 已生成全手草稿于
`calibration_output/splay_recapture_20260923_132346/offline_full_hand_draft/`:
15 个非末端零位、20 个范围,五个末端零位保留 CAD;原始采集仍为 107/108。
复用已计算且收敛的同目标训练候选,重算原始像素误差确认一致,再运行正常草稿验收;
缓存文件、脚本和来源哈希见 `numerical_fit_reuse.json`。JSON/最终 URDF FK 最大差
6.66e-16,标准加载通过。独立验证角度求解失败,四个零位接近 ±20° 模型边界;
精度和发布均未通过,`latest_passed` 未更新。没有硬件动作。
2026-09-23 同批数据全手离线求解支持:最终 `test_raw_draft.py` 23 passed(14.47 秒)。
新增重复观测合并的原始目标、梯度和信息矩阵等价检查,原始图像误差仍逐帧报告;
训练初值拒绝不同数据批次或使用验证选择的结果,相关 CLI 不能进入在线运动。
首次等价测试的近零梯度逐元素断言受浮点消减影响(最大绝对差 4.62e-7、全梯度相对差
3.32e-13),改为完整梯度范数误差小于 1e-11 后通过,未改模型或采集精度门限。
试验过的自适应参数缩放未在合成全手收敛检查中通过,已撤回;最终沿用原参数缩放。
仅未认证草稿的数值停止容差为 1e-5,正式求解默认值及发布检查不变。
2026-09-23 离线草稿支持单轮完整训练:`test_raw_draft.py` 20 passed(8.42 秒)。
覆盖任一训练轮缺四指联动上行时仍保留全手求解范围、初始化选择另一完整训练轮、
两轮互补缺项或完整验证轮不能冒充完整训练轮,以及原有不可观测零位拒绝、JSON
重建和只读离线生命周期契约。未改变正式采集完整性或发布门限;未恢复历史测试。
实机数据的实际离线求解另行记录,不把上述软件测试当作精度验收。
2026-09-23 原始续采的活动标签基准检查:12 passed、30 deselected(1.37 秒)。
覆盖活动标签像素/反馈差异记录后继续导入、缺少基准记录的离线复核标记、固定基准
移动仍拒绝、非有限反馈拒绝、正式发布拒绝未复核安装、草稿仍检查来源完整性,
以及现有标签重装/次数持久化契约。真实 coordinator 检查确认没有因活动标签
基准差异暂停,且将未复核状态写入日志。未启动 SDK 或相机。
两份实机停止记录 `132507` / `132938` 的固定参考与 96 个方向断点只读复核位于
`calibration_output/splay_recapture_20260923_132346/software_review_resume_reference.json`。
不重判旧采样质量、不修改角点;下一任务为四指侧摆第 1 轮正向联动。
这只证明恢复检查和任务位置正确,不代表后续实机运动或 URDF 精度验收通过。
2026-09-22 正式 2+1 局部失败调度收敛:新增 test_taskwise_recovery.py,覆盖
完整依赖任务组延后、训练/验证顺序不变、已完成前缀不变、一次回访预算、真实
coordinator 的带视角错误处理、多视角参考变化不被掩盖、失败后归位且不进入拟合、
无可复用零位时的恢复日志及预算持久化、未解决状态禁止发布。
首组 30 项通过、1 项失败(13.93 秒);失败为既有观察器迁移测试仍断言
rigid_pair_v1,当前配置实际为 rigid_pair_candidates_v2,修正过时断言。
随后调度/恢复/旧 staged 契约/执行组 44 项通过、1 项未选(6.20 秒);passed
断点/分阶段训练/真实图像共享姿态交接组 59 项通过(22.11 秒)。集中任务准入
判断后,受影响恢复组及完整合成 JSON→URDF 验收 18 项通过(14.10 秒)。各组
有重叠,不累计为全量回归。最后一组包含最终文件重建一致性、独立图像验收、
CAD 冻结零位与授权字段保护。
正式 CLI --validate-only 通过,确认 capture_plan_v5、17 任务、训练 0/1、验证 3,
受保护输入一致。git diff --check 通过。本轮无实机运动,未改求解器/精度门限,
不代表全手稳定性验收;旧 v4/v15 断点与新调度隔离。
2026-09-22 用户指定无名指侧摆基准由 85 改为 127:同步 Profile、准备向量、
ROS 配置、产品指纹及当前夹具。Profile/局部任务组首次 14 项通过、1 项旧基准
断言失败(21.25 秒);修正该断言后单项通过(0.55 秒)。正式 CLI 配置校验及
diff 检查通过。全手新会话 194750 在启动前被已有控制/反馈/状态发布者保护拒绝,
未启动本次 SDK、未发送运动,不算实机标定通过;旧基准断点不复用。
2026-09-22 固定 190634 的绝对零位可观测性检查:新增
`test_zero_evidence_coverage.py`,覆盖原零位输入拒绝不变、训练/验证缺失列表
分离、明确缺失掌定位轴线,以及真实 O30 URDF 下的 MCP 零位/未知掌坐标精确
等价变换;已知掌坐标时同一零位变化可检测。三项通过,0.45 秒;既有
`test_spatial_solve_order.py` 真实空间拟合回放一项通过,0.86 秒。
仅增强输入覆盖报错,不改变零位/精度/运动策略。本次无实机运动,未发布产物;
不能把完整小指屈伸数据误当作全手绝对掌坐标参考,详情见稳定性报告最新节。
2026-09-22 DIP 父姿态/安装/角度不确定度:复用 `JointPairImages`,新增独立图像
局部角度协方差,保留共享相关项。原组 8 项通过,0.89 秒;新增“不确定度不可用
不得删除竞争模型”后受影响 3 项通过,0.44 秒。临时密度参数边界 3 项通过,
0.43 秒;密度对照未显示稳定收益,参数及其专属测试随后撤除。补齐重复图像和
角色身份检查,最终该模块 9 项通过,0.95 秒。各组有重复,不累计为全量回归。
真实 190634 前两轮默认预算 16 初值全部收敛,不确定度结果仍为非发布诊断;
72 帧/阶段对照中 2 初值独立图像求解失败,保留负面证据,不放宽优化器/候选
门限、不触发额外运动。第三轮在本轮未用于训练或选择,正式零位和产物仍未验收。
2026-09-22 复用 190634 离线曲线检查:补充原图像模型的纯前向名义像素误差
`image_motion_prediction_errors`,禁止验证时重拟合角度,检查训练/映射来源重叠、
有限角度、模型不变与错误预测可见。受影响组首次 3 项通过,0.47 秒;核对正式
验收语义后撤除对名义总像素误差额外施加 1.5 px 的判决,仅返回误差,再测该项
1 项通过,0.44 秒。正式物理验收规则及测量精度门限不变。
真实 MCP/PIP 冻结指令曲线及 DIP 两个保留候选的第三轮条件角度检查均通过;
DIP 安装候选仍未区分,不等于物理零位或 JSON/URDF 发布通过。细节及一次
缺少旁观标签的读取失败记录在稳定性报告,本轮未运动机械手。
2026-09-22 取消辅助侧摆并回到原交接方法:撤除本轮显式辅助开关,整指实验
拒绝任何辅助计划。采集/实际指令三轮/入口组首次 36 项通过、2 项因未 source
工作区而找不到 ROS package 失败,17.96 秒;补齐环境后仅重跑失败两项,
2 项通过、0.60 秒,没有为测试修改生产路径。
双侧交接回归首组六项因历史夹具与现 Profile 的姿态/标签尺寸不符而初始化失败;
修复测试夹具后首次写错 dataclass 字段,未进入求解;改用 baseline_u8 后六项
通过、1.86 秒,其余受同夹具影响的 23 项通过、4.86 秒。历史 113/16.5 mm
仅用于旧证据回放,生产仍为 85/16 mm。包含交接后模型选择、旧零位不变、
坏图像双侧拒绝、来源哈希和读回防篡改;不代表当前实机发布已通过。
当前 182949 真实数据原 MCP/PIP 及交接回放见稳定性报告:第三轮几何检查通过,
但未完成冻结指令映射、物理零位和最终产物验收。本轮未再次驱动机械手。
2026-09-22 用户指定一次辅助侧摆对照:复用已有 ObserverPreparation,整指实验
只允许 DIP 前一个有界动作,不继承全手或扩幅预算。真实 coordinator 虚拟测试
`test_chain_capture_runtime.py -k 'complete_chain and True'` 1 项通过、15.94 秒,
确认只有一次 52→115→52 辅助段,MCP/PIP/DIP 实际全部指令仍各三次往返,
不生成零位或产物。单动作/全手拒绝/多动作拒绝三个预算边界通过、0.83 秒。
实机 182949 在 MCP/PIP 十二方向完成及一次辅助段完成后,因早期父参考图像差异
暂停,DIP 未开始。离线有无辅助的双标签安装估计均未通过候选验收;未放宽门限,
未发布。具体证据见稳定性报告,不能将软件调度通过写成实机全流程通过。
2026-09-22 小指实际三轮采集:`test_chain_capture.py`、
`test_chain_capture_runtime.py`、`test_diagnostic_presets_cli.py` 共 33 项通过,
17.23 秒。实际 coordinator 虚拟时钟统计全部发送指令,包含准备/收尾,断言三个
关节恰好三次完整往返;保存三份第一轮训练回程参考,禁止验证轮、错误方向/
轮次、缺帧、标签缺失或不稳定反馈替换来源。DIP 标签持续缺失仍按原超时暂停,
原始证据不生成授权零位或角度、不发布。新增旧正式准备不受影响与同一参考只写
一次的两个边界通过,0.57 秒。本轮未驱动硬件,也未声称正式离线产物链已接通。
2026-09-22 正式入口收敛:O30 默认改为 `taskwise_2_plus_1`,不默认声明辅助动作,
产品指纹同步;历史合成夹具显式生成 fixed 数据全集,再由正式夹具选择验收分区。
`test_taskwise_two_round.py`、`test_o30_profile.py`、诊断 CLI 与交错运动受影响组
41 项通过,18.57 秒;含一次正式合成 20 关节 JSON→URDF 及独立图像验收,
新增 CAD 零位不变和仅允许字段变化断言。启动参数/分区/恢复/旧 staged 兼容组
41 项通过、6 项未选,18.30 秒;未运行不相关全型号拟合。旧固定策略测试显式
选 fixed,不通过改变生产策略保留过时默认。以上是软件测试,不是实机正式通过。
新增 2+1 实际 launch 参数传递用例 1 项通过,0.84 秒;CLI `--validate-only`
确认默认 17 任务、训练 0/1、验证 3,受保护指纹一致,未启动硬件。检查脚本首次
把 CLI 的 JSON 和尾部说明当成单个 JSON 解析失败;改为解码首个 JSON 后检查通过,
未改生产输出。`git diff --check` 通过。
只读旧数据的插值对照仍不满足精度,未将 PCHIP 引入正式代码,未新增运动。
2026-09-22 用户指定无名指侧摆基准改为 85:同步 Profile、全部相关零位/准备向量、
ROS 参数、产品指纹及合成夹具;其他通道不变。来源/指纹、侧摆零位路径、采样节点/
速度和局部任务契约共 4 项通过、1.97 秒。额外只读校验参数与 Profile 基准一致,
所有零位的 ring_yaw=85;范围示教文件仅修改本机 baseline.target[4],历史反馈
不改写。未启动实机运动,不改旧会话证据;新基准须重新采集,不复用旧断点。
2026-09-22 整指延后求解采集:显式 `o30_pinky_chain` 实验入口使用原任务路径、
原 SDK/基准保护及交错停点,逐任务轮次 0、1、3;原始父参考回访不授予零位或
角度权限。`test_chain_capture.py` 与旧旁观隔离失败项复查 15 项通过、1.58 秒;
完整真实 coordinator 虚拟时钟 18 单元集成测试通过、19.43 秒;缺失 DIP 标签时
原参考超时仍暂停,1 项通过、2.21 秒。验证轮不得进入旧分段拟合器,1 项通过、
0.72 秒;旧参考权限/虚拟任务契约 2 项通过、0.86 秒。
预设、旁观、冻结验收回归首组 55 项通过、1 项失败、2.08 秒:旧用例把启动日志
固定为单条,未考虑已有 camera_preflight;改为断言调用前后记录完全不变,未删
生产日志。完整虚拟夹具初次因设备心跳未刷新、合成标签投影小于原 30 px 门限
失败,修夹具心跳与焦距后通过,没有放宽生产门限。以上各组不累计为全量回归,
更不代表实机几何或 JSON/URDF 发布通过。
新增显式 CLI 训练策略/禁恢复契约 1 项通过、0.67 秒。实机 `165627` 三任务
18 单元连续采集完成,无暂停、无重扫,安全返回;独立冻结预测仍拒绝,具体精度
与候选差异见稳定性报告。没有因采集完成重跑不相关的全型号产物测试。
2026-09-22 联合模型冻结指令验证:新增 `test_frozen_chain_validation.py`,
16 项通过、0.61 秒;测试夹具改为通过构造接口提供窄支持域后,仅复查受影响项,
1 项通过、0.53 秒。覆盖已知真值的双向映射、验证期禁止重拟合、错误指令与零位
不得被吸收、5 px 阶段平移不得被重新配准、训练/候选选择图像隔离、独立轮次、
稳态目标、保持通道、机位/内参/标签尺寸、非有限或非整数线端指令和范围外拒绝。
复用已有几何合成夹具,无新增实机运动。`FrozenChainCommands` 是非授权的验收
组件,未接入运行时;它不证明物理零位来源、完整采样节点覆盖或候选不确定度。
未将该组软件测试标记为正式 2+1 或 JSON/URDF 验收通过。
2026-09-22 实时诊断内存修复:不再为诊断强制保留全场完整记录或训练几何;
方向结束验收与状态显示共用当前扫描窗口,完整报告在安全返回、关闭采集后从
不可变日志按需读取。`test_diagnostic_coordinator.py`、
`test_diagnostic_reference_flow.py`、`test_capture_runtime_index.py` 首轮 28 项通过、
2 项旧测试因直接解析压缩索引失败,115.33 秒(超过日常目标;后续仅复查受影响项)。
改用正式 `load_jsonl` 后失败两项通过,18.25 秒;新增当前扫描身份/容器绑定断言后
只复查一项完整流程,25.96 秒(与实机并行时耗时)。没有改变生产哈希或准入规则。
只读旧证据保留模型回放及四倍记录量压力数据见
`software_review_20260922_stability/retention_validation_20260922.json`。
实机 `151025` 完成拇指 CMC roll、MCP 四方向,一次通过原始覆盖;最大 GC
0.183 秒、未发生反馈超时,因小指侧摆持续升到 72°C 主动中止。不是全手通过。
用户确认仍可运动后,先只读确认温度下降且无故障,再运行 `151821`:491.96 秒、
48069 条记录,前六任务的十二方向原始覆盖均一次完成,实测 RSS 最高约 341 MiB、
GC 最大 0.239 秒、控制回调最大 0.114 秒,无反馈超时。进入 DIP 时因上游 MCP/PIP
均无可信零位,`parent_reference_current_session_source_missing` 正确阻止父参考复用;
尚未修改此诊断依赖行为。全手其余任务及正式 2+1、JSON/URDF 均未通过验收。
2026-09-22 机械手移动后新会话 `20260922_145145`:全手单轮非发布诊断计划
17 任务、20 关节、36 扫描单元,不恢复旧零位、不增加辅助动作。完成前五任务
共十个方向的原始覆盖;拇指 MCP 正向重扫一次,拇指 IP 与小指 MCP 零位未确认。
小指 PIP 准备阶段发生 1.783 秒 generation-2 GC 停顿,同期反馈时效保护暂停。
未完成全手测试,未发布 JSON/URDF;不能称作正式 2+1 验收。
全手入口/报告/分析受影响组 47 项通过(6.32 秒)。随后修复诊断多通道分段身份
及各指独立 command/feedback 索引,`test_diagnostic_quality.py` 28 项通过
(1.99 秒);四个分段均检查独立通道覆盖、错误分段拒绝、静止中指不得借其他指
运动通过。该修正在本次实机停止后完成,尚未实机验证,且不修复 GC 阻塞。
候选输出角度及共享不确定度诊断:`test_finger_chain_diagnostic.py` 新增轴符号/
2π 等价消除、真实零位差保留、与独立角度重拟合数值导数对照、相关协方差、
训练留出身份隔离及验证相机/尺寸/角色不变边界。首组 2 项通过(8.39 秒);
增加输入一致性边界后仅重跑受影响验证组,6 项通过(6.79 秒),不累计为全量。
旁观机位诊断入口使用 `test_diagnostic_presets_cli.py`、
`test_diagnostic_observation_scope.py`、`test_diagnostic_yaw_hold_plan.py`,39 项
通过(1.56 秒),覆盖扫描单元不变、序列化兼容、设备/参考保护和非发布隔离。
真实 `142553` 小指一次往返原始采集完成,但 DIP 安装候选仍未区分;
`143540` 既有四指侧摆旁观测试因无名指硬件堵转暂停,用户要求重试后的只读
检查报过温,未再运动。细节见稳定性报告,软件通过不代表实机正式标定通过。
2026-09-22 用户最终确认 O30 标签黑框 16×16 mm 后,同步正式 Profile、检测器、
标定覆盖表及产品指纹。`test_o30_profile.py` 的来源指纹、跨配置尺寸一致性、
图像采集受影响组 3 项通过,0.80 秒;CLI `--validate-only` 通过,
`git diff --check` 通过。本次没有实机运动或发布,不代表 DIP 多解已经解决。
下文 16.5 mm 的确认及“正式配置未改”描述保留为此前实验阶段记录。
整指三阶段联合诊断使用 `test_finger_chain_diagnostic.py`:已知几何恢复、
Schur 与完整协方差对照、只拟合留出角度、64 组初值的每一位实际参与初始化、
参考漂移不得被隐藏、URDF 结构去冗余、分阶段参考以及共同标签尺度诊断。
初组 10 项通过,1.17 秒,耗时记录为
`software_review_20260922_stability/finger_chain_tests.json`。开发中仅重跑修改所
影响的诊断组或新边界,没有重跑未受影响的旧模型和整手产物链。随后新增消除
逐图像角度等价 2π 绕回,受影响验证与新边界 4 项通过,0.83 秒;只从六份已保存
结果重算分箱比较,没有重复拟合,主要歧义结论不变。
真实 `121712` 的六组 64 初值回放均保留独立结果;存在三维多解和尺度一致性
问题,详见稳定性报告。此模块不能授权实机角度或发布,不等同于正式 2+1 通过。
用户随后要求固定 16.0/16.5 mm 对照,新增第七份 64 初值结果;比较脚本已核对
两组来源哈希、图像分区、结构约束和参考策略相同。16.0 mm 像素误差较低但
候选仍不唯一,正式配置未改;未因这次仅诊断输入变更重复无关测试。
完整父候选与联合父姿态诊断:`test_joint_pair_diagnostic.py` 检查已知真值恢复、
父姿态/角度 Schur 协方差与完整逆矩阵一致、固定几何验证、重复图像拒绝、
16 个失败初值保留及不能按验证误差选训练候选;不生成发布模型。
首次与配置策略组 13 项通过、1.42 秒;向量化/共用有界求解器后受影响 5 项
通过、0.69 秒;新增拒绝边界 1 项通过、0.42 秒,验证接口变更受影响 2 项
通过、0.65 秒,候选选择边界 1 项通过、0.39 秒。
`test_rigid_pair_observer.py -k 'not independent_parent_branches'` 的历史真实回读、
篡改和新旧父候选调用边界 9 项通过、20.37 秒;迁移/准备契约/已知真值候选组
32 项通过、5.64 秒。没有重跑未受影响的独立补采重拟合或整手产物链。
新版无辅助动作配置只读验证通过;`121712` 经新运行时桥接入口正确拒绝歧义。
联合诊断的真实 16 初值回放有像素改善,但父几何和候选比较仍不通过,详见稳定性
报告;这些软件分组不累计为一次全量测试,也不等同于实机或 JSON/URDF 验收。
共享零位及双端交接反馈契约复用 `staged_revisit_v2`:新 O30/u8 跨次容差 10,
窗内稳定性 2,旧无版本记录仍为 4。`test_shared_tag_pose_bridge.py` 与
`test_shared_pose_handoff.py` 首轮 45 项通过、3 项失败,19.03 秒;失败为两个
JSON 列表/元组直接相等断言,以及一个未完成任务本不应导入的旧测试假设。
改为反序列化后的物理参考相等、区分完成/未完成任务归属,不修改生产恢复规则。
针对复查及新增反馈契约篡改组 5 项通过、4.27 秒;源窗口的 7/10/11 边界、
旧版门限及窗内抖动新增组 3 项通过、1.30 秒。没有无理由重复完整拟合。
真实 `114118` 只读 PIP 回放在新反馈契约下通过独立父姿态检查和准备解算;
不把此软件结果视为 DIP 或整手实机通过。
随后 `121712` 无辅助侧摆实机完成六方向原始采集、无需重扫;MCP/PIP 和
DIP 父参考通过,DIP 几何因约 1.964 px / 4.864° 继续拒绝,未发布。
同批只读约束消融保留拒绝结果,详见稳定性报告;没有将删除约束作为修复方案。
实际启动验证纠正了上轮导出判断:固定 2+1 分区不是执行决策,应从策略派生,
不能填入禁止 YAML 导出的 `task_training_cycles`。修正后新策略/观测策略组
15 项通过、16.87 秒,包含正式合成 JSON→URDF;补充有效 YAML 完整往返后,
只重跑该项,1 项通过、1.04 秒。单次 v3 预算记录由实机暴露,新增
`test_single_trajectory_action_declares_budget_and_cannot_escalate`,与原两次预算恢复
用例共 2 项通过、0.78 秒。实机 `113510` 的旧记录保留拒绝;`114118` 的新记录
284 帧通过辅助证据验收,但因 PIP 父模型缺失停止,不能写成 DIP 精度通过。
2+1 辅助观测接入修正:`test_observer_policy.py` 同时检查 staged 与严格 2+1,
`test_taskwise_two_round.py` 检查实际 v3 依赖/动作编译而非只检查参数接受,且扫描顺序不变。
初次 quick 组 13 项通过、1 项导出断言失败、1 项未选(3.22 秒):运行期分区按现有契约
不可导出为可复用 YAML,修正测试预期后该项通过(1.14 秒)。后续策略与真实双标签回放组
17 项通过、107.59 秒,其中独立父分支真实补采回放耗时 65.68 秒;未再重复整手产物测试。
修正后的实际 CLI `--validate-only` 通过。真实小指的零新增运动反事实对照仍因几何精度
不足拒绝,详见 `linkerhand_calibration/models/o30/docs/O30_STABILITY_REVIEW_20260922.md`,不能称为实机修复完成。
2026-09-22 严格逐任务 2+1 用 `test_taskwise_two_round.py`:quick 部分检查
逐任务顺序、轮间不重复准备、禁止补轮、断点分区及不可观测不跨任务推迟;
integration 部分复用正式 O30 夹具,验证 20 关节拟合、独立留出及 JSON 重建相同 URDF。
与 `test_diagnostic_quality.py` 共 28 项通过,16.08 秒。诊断压缩证据读取用
`test_diagnostic_analysis.py`,19 项通过、2.24 秒。旧准备契约测试直接读取
压缩索引导致一次失败,改用公共 `load_jsonl` 后只复查受影响组,30 项通过、
1 项未选,3.32 秒。各组不累计为全量通过;实机边界见
`linkerhand_calibration/models/o30/docs/O30_STABILITY_REVIEW_20260922.md`。
辅助侧摆端点离开条件使用 `test_witness_endpoint.py`。真实夹具
`o30_witness_terminal_gap.json.gz` 来自 `20260920_183257` 的 226 帧完整侧摆窗口,
末尾连续三帧缺命令,仅余两帧有效尾部。真实记录必须继续拒绝;追加的模拟后续帧
仅验证实时等待门,不能作为实机或发布证据。与 `test_preparation_witness.py`、
`test_preparation_sync.py` 共 53 项通过,14.89 秒,检查在线和离线共用端点窗口、
原超时上限、旧记录兼容、数据篡改和辅助拟合失败仍拒绝。
准备契约升级用 `test_preparation_contract.py`,覆盖新旧断点分离、父子/预算/动作
变化、历史记录保留、原会话边界、节点写入和发布入口禁止旧模型冒充新预算。
时钟自适应刷新用 `test_camera_timing.py`,正负平滑漂移在模拟 30 Hz 的 60 秒内
曝光时间误差保持小于原 1 ms 连续性预算,同时验证真跳变仍拒绝及启动锚点年龄。
辅助精度预算前置用 `test_observer_pose.py` 和 `test_observer_reference.py`。
此次增量验证分组记录在 `software_review_stability_repair`:初始针对组 79 项、8.84 秒;
证据/真实 PIP-DIP 回放/runner/合成完整产物组 91 项、58.99 秒;修正启动锚点刷新
时机后的相机组 15 项、0.47 秒。组间有重复用例,不将累计次数称为一次全量回归。
实际目录的断点选择只读验证约 17 ms,排除了旧准备契约;配置 validate-only 通过。
这些结果不替代新版本的连续实机验收。
相机时钟诊断变更使用 `test_camera_timing.py`:同时覆盖原始计时单位、跳变、陈旧帧、
重同步顺序及拒绝事务可重放。新增 `CLOCK_MONOTONIC_RAW` 仅记录诊断边界,不能
替换 ROS 时间或放宽同步门限。2026-09-20 针对组 12 项通过,0.33 秒,记录于
`calibration_output/O30_RIGHT_001/software_review_stability_architecture/camera_timing_tests.json`。
这不表示实机重复失同步已经修复;整体评估见 `linkerhand_calibration/models/o30/docs/O30_STABILITY_ASSESSMENT_20260920.md`。
日常修改运行受影响用例和必要契约用例,目标为 60 秒内完成。不要因为修改了一行代码就运行
整手拟合或全量 `colcon test`。公共产物契约变更需要覆盖相关型号,发布前再执行全量回归。
测试保留原文件位置,避免破坏现有共享夹具。`test/conftest.py` 集中维护分类;函数上的显式标记优先。
| 标记 | 内容 | 何时执行 |
| --- | --- | --- |
| `quick` | 局部求解、调度、恢复、隔离和拒绝边界 | 日常选择受影响文件 |
| `replay` | 已记录的真实图像、准备失败和姿态歧义 | 修改对应观测或恢复逻辑 |
| `integration` | 完整拟合、产物回读、进程或 ROS 链路 | 修改公共契约或发布前 |
| `legacy` | 历史格式、旧型号算法及兼容入口 | 修改兼容契约或发布前 |
从工作区根目录准备环境:
```bash
source /opt/ros/jazzy/setup.bash
source install/setup.bash
export PYTHONPATH="$PWD/src/linkerhand_calibration:${PYTHONPATH:-}"
export PYTHONDONTWRITEBYTECODE=1
```
采集计划、训练接口日常验证(按改动选择文件,不必每次全部执行):
```bash
python3 -m pytest -q -m quick \
src/linkerhand_calibration/test/test_capture_plan.py \
src/linkerhand_calibration/test/test_adaptive_training.py \
src/linkerhand_calibration/test/test_command_motion.py \
--durations=8 --timings-json=/tmp/calibration-quick.json
```
涉及零位恢复时加 `test_zero_recovery.py`;涉及断点时加 `test_prepared_resume.py`、
`test_passed_resume.py`;涉及发布时加 `test_artifact_publication.py`。真实中指 DIP 歧义回归位于
`test_measured_transfer.py::test_real_middle_dip_fits_but_remains_ambiguous`,其正确结果仍为拒绝不充分证据。
`test_prepared_resume.py::test_resume_tick_uses_prepared_data_and_still_checks_current_reference`
同时覆盖 O30 分阶段恢复:历史证据索引须在启动准备时完成,实时回调不能再次整理整份历史;
参考变化仍拒绝复用。五个型号、参考保持/变化共 10 项约 2 秒。真实 `20260920_141822`
在该索引阶段发生控制回调阻塞,修复后的 `20260920_142046` 已实际复用 4 个扫描单元;
后续因小指零位 ID4 检测断续停止,不代表整手通过。
O30 回访反馈重复性修改,先运行 `test_staged_training.py -k revisit`:真实反馈 48→41、
10 的边界、超限、同批不稳定、图像/安装变化以及 v1/v2 回读共 8 项约 1.2 秒。
涉及复核记录格式时,追加 `test_staged_artifacts.py` 的 JSON→URDF 一致性和阶段拒绝组,
共享一次整手产物,5 项约 31 秒;无需为每个拒绝条件重复完整拟合。
分阶段调度、旁观证据和恢复的快速检查:
```bash
python3 -m pytest -q -m quick \
src/linkerhand_calibration/test/test_staged_training.py \
src/linkerhand_calibration/test/test_staged_runtime.py \
src/linkerhand_calibration/test/test_observer_pose.py \
src/linkerhand_calibration/test/test_observer_reference.py \
--durations=8 --timings-json=/tmp/calibration-staged-quick.json
```
`test_observer_reference.py` 共享一次上下游图像求解,角点、来源、安装和取样篡改直接检验
证据回读边界。`test_staged_runtime.py` 的进程复用用例及整手训练用例标为 `integration`。
只有训练/冻结/发布契约变化时,才运行下面的分阶段整手组;本次初次完整组 19 项约 45 秒,
后增加的回访时序拒绝用例随产物组单独复查,未重复其余已通过的完整拟合:
```bash
python3 -m pytest -q \
src/linkerhand_calibration/test/test_staged_training.py \
src/linkerhand_calibration/test/test_staged_runtime.py \
src/linkerhand_calibration/test/test_staged_artifacts.py \
--durations=8 --timings-json=/tmp/calibration-staged-integration.json
```
该组共享整手输入和产物,包含实际混合轮数统计、冻结后不再训练、一次集中补采、失败终止、
断点及 JSON→URDF 链路。下面的旧策略整手组仅在旧策略相关逻辑也受影响时追加。
共享 Tag 的进入姿态联合准备修改,运行真实 MCP 的专门回放组:
```bash
python3 -m pytest -q \
src/linkerhand_calibration/test/test_preparation_transition.py \
--durations=8 --timings-json=/tmp/calibration-preparation-transition.json
```
该组共享一次真实图像求解,检查正式运行时继续、原始证据回读、缺失辅助数据、留出隔离、
保持通道/参考变化、篡改拒绝及取消清理,通常约 10 秒。只有候选选择公共逻辑受影响时追加
`test_image_model_selection.py` 的相关用例;已有通过的完整拟合不为文档或断言修正重复执行。
本次验证记录位于 `calibration_output/O30_RIGHT_001/software_review_preparation_transition/`,
保留失败与针对性复查关系,不把软件回放写成实机通过。
测量几何候选的精度资格与图像评估分离,回归位于 `test_measured_transfer.py` 的
`test_real_ip_compares_uncertain_alternative_before_authorizing`、
`test_uncertain_alternative_cannot_be_frozen` 和
`test_uncertain_alternative_still_vetoes_when_images_do_not_distinguish`。
三项共享 `20260920_140424` 的 129 帧真实 IP 准备及父几何证据;精度不足的候选仍参与
留出区分,不能冻结;无法区分仍拒绝。相关旧中指 DIP、候选选择及回读边界共 17 项
耗时 5.39 秒,后补否决边界 1 项耗时 2.16 秒。记录位于
`calibration_output/O30_RIGHT_001/software_review_ip_alternative/`,不代表整手实机通过。
完整 O30 产物链路按需单独执行:
```bash
python3 -m pytest -q \
src/linkerhand_calibration/test/test_o30_artifacts.py::test_o30_nonlinear_twenty_channel_finalization \
--durations=8 --timings-json=/tmp/calibration-o30-integration.json
```
该用例从正式采集证据入口进入,检查采样完成、训练决策回放、运动授权、受保护相机文件、
原始角点、JSON→URDF 重建和回读。输入来自独立 FK 合成场景,使用兼容的几何运动授权;
不模拟在线图像模型选择,不替代实机连续采集及精度验收。末节 CAD 零位假设仍须保留原语义。
整手输入由会话级夹具共享,只读使用;需要篡改的用例先复制。反馈缺失、反馈卡住已改为局部
映射契约测试,不再各生成一套整手 JSON/URDF。篡改、取消和失败指针检查优先复用验收边界。
`--timings-json` 记录各用例 setup/call/teardown 耗时、结果、层级和 Python/YAML 源码指纹。
同一版本通过的测试不无理由复跑;修复失败后只重跑失败及受新改动影响的用例。裸 `pytest`
仍会运行全量,标记不会悄悄关闭测试。分层收集可用 `--collect-only -m replay` 等命令检查。
上一版逐任务自适应方案的软件验证记录保存在工作区
`calibration_output/O30_RIGHT_001/software_review_adaptive_training/software_validation.json`,
同目录保留各组耗时记录和历史数据对照。O30 正式产物链路与混合轮数统计约 44 秒,
恢复、断点及真实 DIP 歧义回归约 19 秒,在线训练评估与取消约 6 秒。记录保留开发期间
的失败及修复后复查关系,不将不同代码版本的增量检查称为一次最终全量回归。
本次分阶段方案记录在
`calibration_output/O30_RIGHT_001/software_review_staged_training/software_validation.json`。
同目录保留各次运行的源码指纹、耗时及开发失败,报告标明修复关系。新旧策略、旁观图像、
原真实 DIP 拒绝和文件链路均分别记录;不重复旧的 2.88 GB 日志性能测量,不宣称实机已通过。
遮挡感知准备策略的日常检查使用 `test_preparation_witness.py`:真实无名指停点保留为
`fixtures/o30_ring_mcp_ambiguous.json.gz`,合成独立侧摆源明确标注,模块共享一次原始
拟合和一次新增证据。覆盖逐指避让后单通道往返、整数 SDK 目标、回访不重采、
训练/留出隔离、姿态改变、完整窗口、篡改、强制证据缺失及正式读回。只读策略为
`--preparation-policy occlusion_aware_witness_v1 --validate-only`,不启动硬件。
最终遮挡版:该文件加 Profile 加载、采集计划、原图像采集契约,共 58 项约 14.12 秒。
源码迭代与现场遮挡澄清导致的增量复查分别记录,不把开发过程累计次数称为一次回归。
记录目录为 `calibration_output/O30_RIGHT_001/software_review_preparation_witness/`。
新策略仍需完整实机对照;原 O30 JSON→URDF 及取消发布两项共享整手夹具约 32.12 秒,
没有逐个拒绝条件重新拟合整手,也没有运行全量 pytest/colcon。
准备优化器统一恢复检查位于 `test_image_bundle_optimizer.py`。快速用例检查计算次数、
内存上限、不收敛/异常/非有限值/误差增大时继续拒绝;真实回放标记为 `replay`,共享
一次 `20260920_154722` 拇指 IP 求解。夹具保留真实父参考、上游准备记录及其原始角点,
通过正式准备、来源几何和父参考验收;不能仅用孤立合成输出代替这些入口。
该次真实候选原先耗尽 150 次稀疏求值,使用同一训练证据暖启动直接解法后,再 6 次
收敛,随后被原 1.5 px 门限拒绝,合格候选得以通过。未收敛候选仍否决,不参与绕过
门限的比较;留出数据不决定计算恢复。主回归 24 项约 32.20 秒,覆盖旧 IP 精度不足
候选、真实中指/无名指歧义拒绝、转接/共享姿态回读、小指历史预算、训练/留出隔离和
工作进程取消。新增用例开发失败及针对性复查分别保存于
`calibration_output/O30_RIGHT_001/software_review_solver_recovery/`。
未重跑整手拟合和 JSON→URDF 产物组;本次改变的是准备求解及其证据绑定,产物生成、
最终角度/像素门限没有修改。软件回放通过不代表整手实机已经通过。
准备采样有效性与辅助适用性使用 `test_preparation_sync.py`:夹具来自真实
`20260920_160630` 小指完整准备窗口,保留两帧原始缺指令值。检查完整原始窗口回读、
排除记录绑定、缺值行上的保持关节变化、持续缺样/端点/身份变化拒绝,以及拟合前
辅助不适用时主模型独立验收,拟合后不改路线。与 `test_preparation_witness.py` 的
原歧义和篡改检查合计 41 项、10.58 秒;历史 v1 和拟合失败拒绝另 3 项、3.97 秒。
后补缺候选不可视为转角不足的边界单独执行;没有无理由重跑前述已通过组。
验证记录位于 `calibration_output/O30_RIGHT_001/software_review_preparation_admission/`。
双端共享姿态交接使用 `test_shared_pose_handoff.py`,夹具来自 `20260920_163002`,
包括原 MCP 模型/零位/像素来源、上游回基准原始窗口和 PIP 准备完整证据。
共享一次 PIP 拟合,检查原失败复现、新双端验证、原门限、正式回读、数据篡改、验证轮
隔离、源图像先于全部新准备数据、断点依赖导入/去重、恢复代次和四指模型归属。
DIP 用真实像素模拟后续访问,经 `ObservationCapture`、父参考确认和文件回读,
下游模型外壳明确为合成数据,不能宣称整指实机通过。
本轮父参考、有限恢复、旧断点及旧版共享姿态 62 项通过,20.95 秒;最终针对组
25 项通过,4.11 秒(含 1 项已受修改影响的旧父参考回读)。随后新增时序边界与导入
去重只执行相应用例。现有 O30 正式采集证据入口 JSON→URDF 集成单独运行一次,
31.24 秒。开发中的夹具缺来源、策略字段绑定和 ROS 环境收集失败保留原记录,
不计为通过;没有全量 pytest 或 colcon。完整记录见
`calibration_output/O30_RIGHT_001/software_review_shared_pose/`。
准备观测预算的实机像素回归使用 `test_preparation_density.py`,夹具为
`20260920_171710` 的完整小指 PIP/DIP 准备窗口、上游模型和双端交接图像。新 PIP
模型重新投影原 DIP 像素后,验证更完整的训练/留出分组、源模型精度传递、候选区分
及模型回读;冻结旧父模型仍拒绝,四指多关节求解不扩容。此回放带有明确的离线姿态
准入标记,不声称它是一次可发布的实机采集。正式产物另用已有 staged 产物组检验。
`test_checkpoint_startup.py` 检查断点加载心跳、独立 900 秒上限、恢复后设备/服务
时限、异常清理及无断点不发布加载状态。相关启动/共享姿态/真实密集回放 98 项
14.79 秒;产物回读、阶段隔离和取消发布 8 项 24.11 秒。前一批 85 项通过、1 项
失败是历史测试将最大像素误差写死为 0.75;新增留出图像为 0.752,实际契约为
1.5 px。现已断言正式契约,并复查完整共享姿态回读。环境收集失败、反事实回放
拒绝分类断言修正和后续通过记录均保留,不混算为一次完整实机回归。
扩展到准备采集/辅助证据入口后,发现在线密集预算未传入离线重拟合,已补齐
`image_sampling_policy` 的版本、报告与角色哈希绑定、重放参数及帧数上限校验。
后续来源/辅助/真实回放组 121 项通过、2 项为测试断言失败;原断言分别固定了错误
文本和旧采样子集模型。修正为准确拒绝码及相同预算的离线对照后,仅复查失败用例、
受影响的启动与产物边界,16 项通过,32.54 秒。发布线程清理再检查 7 项通过。
记录完整保存在 `software_review_stability_density`,没有将多版本增量测试宣称为
一次全量回归。实机尝试 `20260920_174317` 在发起标定运动前被现有 ROS 控制节点占用
阻止,未产生可交付 JSON/URDF。
完整已声明归零路径用作辅助观测时,运行 `test_declared_witness_path.py`:
只有完全相同避让姿态下的既有单关节归零路径可超过默认四分之一行程,
任意扩幅、其他关节变化及未经声明的侧摆全行程仍拒绝。
`test_conditioned_witness.py` 使用 `20260920_191613` 的真实中指 PIP/MCP 图像,
覆盖原来只作事后检查时的共享姿态失败、独立源验证后参与共享零位拟合、
正式证据回读以及端点变化/策略降级拒绝。旧 v1/v2 辅助证据继续按原含义读取;
新 v3 的共享姿态条件绑定进准备契约,不能复用旧契约模型。
`test_rigid_pair_observer.py` 使用 `20260920_192330` 的中指 MCP/PIP/DIP 原始
图像,验证双 Tag 联合拟合、原 1°/1 mm 来源门限、DIP 有界父几何传递和正式证据
回读;保持关节变化、源验证角点变化、当前端点变化及删除必需证据均拒绝。
`test_observer_pose.py` 另用已知真值和故意偏置的父姿态初始化验证相对安装恢复,
防止把历史父模型当成精确测量。真实夹具包含上游完整来源和会话头。
受影响的旧观测/共享姿态/几何传递/配置/准备契约组 86 项通过,28.21 秒;
新刚体对与 staged JSON/URDF 产物链组 14 项通过,38.29 秒。
初次缺 ROS 环境的收集失败不计入通过;上述结果属于软件回放,不能代替整手实机验收。
staged `passed` 续采检查 `test_passed_resume.py` 的真实 coordinator 导入边界:
已通过访问必须先完整落盘才能跳过,未完成和未来轮次不被授权;导入中止和反馈失效仍暂停。
相关 staged 调度和断点启动组首次 21 项通过、4 项夹具失败(O6 不支持 staged、
旧合成观测缺会话字段);修正夹具后只重跑受影响的 6 项,1.39 秒全部通过。
统一观测策略使用 `test_observer_policy.py`:覆盖整图依赖选择、断开的角色关系、
历史模式不变、通过关节策略保持、幂等、序列化和执行校验。
`test_checkpoint_observer_upgrade.py` 检查完整审计及拒绝改动既有模型、训练决策、
运动/精度契约和保护哈希。`test_rigid_pair_observer.py` 增加真实食指夹具
`o30_index_rigid_pair.json.gz`,明确验证有歧义的数据不会因开启新策略而误通过;
中指原通过、篡改拒绝和正式证据回读用例继续保留。
本轮策略/迁移/准备契约/真实回放组 30 项通过、19.43 秒,另 1 项因没有 source
ROS 环境导入失败;恢复环境后只重跑该项及受影响的配置/观测兼容组,18 项通过、
2.29 秒。启动参数和准备辅助兼容组 32 项通过、9.99 秒,共 80 项通过。
最初把食指真实数据预设为可通过的实验出现来源歧义,已记录为负例;未降低任何
精度、候选区分或发布门限。这些结果是软件验证,不是整手实机通过。
有界独立观测使用 `test_observer_preparation.py`:检查按共同祖先生成动作、四分之一
行程限制、已通过测量不变、画面内旋转不算视角覆盖、模拟真值恢复、命令/反馈/路径/
完成记录篡改拒绝、原始证据导入、运动预算跨重启保持、固定端点等待上限及真实食指
提前触发。`o30_observer_initial_hold.json.gz` 保存 `20260920_210259` 的初始静止
记录,用于检查稳定窗口与图像时效分离,以及未开始侧摆的计划可以审计后继续。
初次兼容组 40 项通过、1 项测试替身缺少新增控制器,20.78 秒;补齐测试替身后,
新流程及受影响用例 14 项通过、2.80 秒。准备契约、调度、全相机原始像素与既有
staged JSON/URDF 产物链 41 项通过、29.74 秒。采集计划兼容组 12 项通过、4.39 秒。
修正实机暴露的时效契约及未开始动作的恢复边界后,新流程和旧刚体对回放 22 项
通过、19.98 秒。各组有重复用例,不累计为一次全量通过。
观测补采有限序列与父标签跨次反馈契约:`test_observer_preparation.py`、
`test_parent_reference_reuse.py`、`test_parent_reference_provenance.py` 验证真实
`20260920_211220` 的完整小幅补采、247→255 的跨次反馈、原图像精度检查、
历史 v1 语义、两步预算及未开始动作的恢复。父参考组 58 项通过,7.69 秒;
序列/迁移/准备契约组 36 项通过,5.63 秒;序列/调度组 27 项通过,6.33 秒;
状态显示组 8 项通过,1.47 秒。新增预算用例初次因测试夹具命令和反馈共享列表
重复缩放失败,修正夹具后该项通过,0.81 秒;反馈规则篡改拒绝项初次即通过。
记录在 `software_review_active_observer_sequence`,这些分组有重复,不累计成全量回归。
训练中的双 Tag 父姿态分支优化:`test_rigid_pair_observer.py` 与
`test_observer_preparation.py` 共 25 项通过,47.56 秒,包含 213013 实机补采源、
旧中指正式证据回读、源不足拒绝、预算与保留断点。逐帧多初值最大 320 次评估,
全局交替最多三次;旧冻结父姿态路径保留原 80 次评估。独立 DIP 几何仍因精度不足拒绝,
该组通过只表示观测源/兼容机制通过,不能宣称整手或本批 DIP 通过。
## 原 MCP/PIP 训练回程参考适配与无侧摆实测(2026-09-22 19:06)
本轮新适配器使用已有隔离求解工作进程,采集源有界且不读取第三轮;只授权父参考
检查,不授权物理零位、角度样本或产物发布。完整 coordinator 合成运动集成首次
1 项通过,16.43 秒;增加图像身份及模型证据断言后,`test_chain_capture.py` 与
`test_chain_capture_runtime.py` 28 项通过,18.52 秒。新增来源分箱、训练冻结、
清理后旧结果拒绝、未解模型拒绝等边界随后 4 项通过,0.84 秒。
工作进程、旧初始化及 CLI 组 25 项通过,7.44 秒;包括真实 spawn 对新请求/结果
类型的传递。实测后仅更新描述文字,CLI/分析输出受影响组 30 项通过,1.83 秒。
以上存在重叠用例,不相加为一次全量回归,未重复运行所有已通过用例。
实机 `20260922_190634` 完成小指 MCP/PIP/DIP 每任务连续 2+1:18 个方向单元
无暂停、无重扫;原始命令核查各三次往返,无侧摆或准备额外圈。冻结在线模型
后的第三轮几何检查 MCP/PIP 各 60/60 通过,最大 RMS 0.295269/0.448776 px;
DIP 入口父模型复用通过。`frozen_reference_live_audit.json` 留存逐帧结果。
这些是采集与几何检查通过,不等于 DIP 曲线、物理零位或 JSON/URDF 发布验收。
## 整指运动学联合模型离线检查(2026-09-22)
新增 `test_kinematic_chain_diagnostic.py` 和 `test_chain_candidate_audit.py`,
针对性运行 8 项通过,4.03 秒。覆盖共享铰链下的阶段参考姿态、合成真值恢复、
Schur 协方差与完整逆矩阵一致、冻结模型拒绝无法解释的阶段平移、相机坐标系
相关协方差,以及只按训练状态合并数值等价解、保留失败解和不等价候选。
真实 `20260922_142553` 回放完整枚举 64 个双标签初值,全部收敛;训练状态分成
4 个物理解族,原 0.01 / Holm 门限检验后保留 2 族。保留族的条件输出角度包络
为 MCP 0.136425°、PIP 0.197536°、DIP 0.655645°。原始拟合结果不重写,
分族和相机几何审计只读取保存参数,不重新拟合。证据位于
`calibration_output/O30_RIGHT_001/software_review_20260922_stability/` 下的
`kinematic_chain_camera_geometry_audit_142553.json`。
这不是正式标定稳定性通过:轴距采用精确 URDF 约束,验证仍逐帧估角,且反向数据
用于候选检验。尚缺物理零位绑定、冻结双向指令映射、未使用第三轮、完整输出误差
及 JSON/URDF 往返验收。新模块为非授权离线模型,未绕过正式父参考或发布门限。
## O30 raw_joint 正式链路(2026-09-22)
用户指定停滞重试(2026-09-22):仅 O30 的 `mechanical_stall` 增加同一运动
首次尝试加两次重试,每次重发前等待 3 秒,第 3 次失败停止。等待不发送新位置
指令,不作为有效采样;失联、控制权冲突及其他保护仍检查。真实 coordinator
虚拟时钟验证三次失败、两次等待和等待期间保护:3 passed,1.00 秒。
既有安全及反馈组 44 passed;另一条旧启动测试补充显式复用相机参数后通过。
测试夹具曾缺少 SDK 心跳,已补齐模拟心跳,未因此改变生产通信保护。
新默认协议及完整边界见 `linkerhand_calibration/models/o30/docs/O30_RAW_PROTOCOL_IMPLEMENTATION.md`。
针对性验证(不同组有重叠,不相加宣称一次全量回归):
- 原始采集、断点恢复、存储回归:35 passed,44.24 秒。覆盖首单元尚未通过的中断发现、跨恢复补采预算、实际 coordinator 三轮指令、缺失光学观测禁止运动。
- 全手运动效果及显式旧协议路径:3 passed,4.12 秒。原有两个接受关节角夹具改为显式 `TASKWISE_TWO_ROUND`,不修改新协议质量门限。
- 光学核验及候选集合门限:8 passed,5.84 秒。错误内外参、覆盖、序列号、同步拒绝;物理超差拒绝,标签安装不唯一不额外否决。
- 共享 CAD 图像导数、历史失败角点和发布回读:10 passed,51.30 秒;批量独立角度验证修正稀疏索引读取后,发布组 3 passed,10.92 秒。
- 外参工具、原子发布、状态及 O30 launch 公共契约:30 passed,2.32 秒。
- 最终候选门禁、共享整指/运动链及真实失败回归:23 passed,12.25 秒。正式终结入口缺少来源证据时,拒绝求解并保存失败状态:1 passed,4.76 秒。
- 光学核验采集同步上限统一为 50 ms 后,外参工具受影响组:10 passed,0.57 秒。源码编译与 `git diff --check` 通过。
- ID5/9/12 与 ID10 历史回归来自 `o30_raw_failure_observations.json.gz`,仅用于旧角点观察能力回归,不能恢复为新协议数据。
- `o30_training_candidate_parameters.npz` 保存两个合成训练解的参数,供配对损失/保留候选边界测试复用,不含任何实机标定授权。
完整合成真值数值回归:64 个初始化全部收敛,约 192.82 秒;每个候选总求值不超过 200。
训练像素门限排除 32 个,训练分层配对检验排除 16 个,剩余 16 个全部通过候选协方差与第三轮验证。
训练检验使用原 0.03 px 分辨率余量和 0.01 Holm 家族门限;第三轮不参与选择。
保留候选的零位三倍标准差与候选差异联合包络约 0.100°,绝对指令角约 0.192°,轴位置约 0.125 mm,FK 位置约 0.260 mm。
产物通过实际 robot_state_publisher、结构授权、JSON 重建及最终 FK 回读;后半程验收和发布约 10.38 秒。
只写入 `calibration_output/software_review_20260922_raw_joint/known_truth/` 和独立软件测试指针;实机 `latest_passed` 未修改。
未进行本次新协议全手实测或实机姿态对照;不能把以上软件结果当作现场精度证明。
## O30 轻量原始角点采集与立即补采(2026-09-23)
新增集中回归 `test_raw_lightweight.py`,不恢复外部删除的历史测试。覆盖当前方向立即补一次、
中断预算、仅固定标签在线跟踪、死区/平台、堵转/反向/噪声、静止采样冻结计时、
不稳定终点有界退出、采完禁止发送、封存校验、旧协议读取与混合拒绝、旧合成 URDF 重建。
首组 6 passed、5 failed(4.25 秒):五个失败是扫描测试没有先进入任务避让姿态,
修正夹具起始向量后只复查该组,5 passed(0.98 秒)。后续边界组 10 passed、
1 failed(4.18 秒):竞争控制测试缺少 Start 后反馈,补齐后单项 1 passed(0.77 秒)。
完整真实 coordinator 虚拟时钟、单主机位移动标签、108 方向、无补采、归位封存与
训练/验证分区检查 1 passed(85.13 秒),属于必要整手调度集成,不是实机通过。
旧合成产物 v1/v2 JSON→URDF 重建与终态入口 3 passed(0.87 秒)。
删重复图像记录并保留未稳定原始帧后,受影响采集/补采恢复/封存/兼容组
7 passed(6.25 秒)。各组存在重叠,不累计为一次全量测试。
正式 CLI 配置校验通过。实机 `20260923_104837` 去程通过,拇指旋转回程指令 162、
反馈 253,累计实际运动无推进 4.005 秒触发保护;未重复启动,控制栈已退出,
停在当前位置,未执行自动归位。仅 1/108 方向完成,未封存为完整采集、未发布 URDF。
同段移动标签角点最大位移约 0.47 px、固定基准约 0.50 px,未见明显回程运动;
不能据此删除停滞保护,也不能宣称全手稳定采集通过。
补充只读离线入口检查初次失败(3.61 秒):虚拟相机夹具缺少实际入口要求的
`rectified_camera_model` 日志,补齐夹具后在后续组通过,确认缺项拒绝发生于
离线验收、原始文件哈希不变且无新运动。
用户随后明确授权硬件停滞重试一次:复用现有 StallRetry,O30 原始采集限制为
首次尝试加一次重试,等待 3 秒,同方向共享预算;其他硬件保护不进入重试。
首组 6 passed、1 failed(4.19 秒):测试将保护停止发送的最后保持指令也误认为
等待期间推进,修正断言后四种实际 coordinator 场景 4 passed(1.31 秒)。
运动保护代码和计划身份同步更新,旧策略会话不得混入新断点。
补充端点阶段切换与反馈抖动回归:180 ms 图像延迟单项通过(7.87 秒),
扩大到 300 ms 并增加 4 u8 往返抖动后复现 3 个失败、4 个通过(14.95 秒)。
隔离模块验证有限端点等待和推进历史最高值修正,8 passed(7.98 秒),未影响当时运行的实机。
用户随后明确端点只看实际发送 SDK 指令:最终采用有效稳态记录中的已发送指令核验端点,
不额外增加端点等待、不要求反馈到 0/255,也不把稳态图混入运动覆盖。
真实 coordinator 300 ms 延迟、反馈端点仅 10/240、离线误判复核与中断拒绝,
加上方向推进、补采、封存及旧协议边界,17 passed(10.04 秒)。
SDK 身份错误保留原字段、其他硬件保护和单次停滞重试、旧合成 URDF 重建,
9 passed(1.86 秒)。
实机 `20260923_110651` 完成 35 个方向,原记录 29 个通过、6 个端点误判;
在小指 PIP 验证回程因 `o30_sdk_identity_mismatch` 停止,反馈仍约 29.81 Hz。
未触发停滞重试,未归位封存,未更新 `latest_passed`。异常身份字段在旧日志中缺失,
不能将此状态直接等同于物理通信断开。修正后只读复核同一数据,35 个完整方向均通过,
缺 73 个方向,禁止发布,源数据哈希未变化;报告见实现文档。
最终端点与推进规则下,完整 coordinator 单主机位、108 方向、归位封存及
训练/验证分区回归:1 passed(87.51 秒)。该必要整手集成仍仅为软件验证。
源码编译和 `git diff --check` 通过;未恢复外部删除的历史测试。
2026-09-23 用户确认 ID17 在拇指近端指节后修正安装连杆及产品哈希。
正式配置加载、拓扑反馈依赖 0/1/6、仅顶机位、17 任务/108 方向校验通过;
临时校验脚本首次误用 TagSpec.id,改为 tag_id 后通过,生产加载未失败。
既有原始角点、立即补采和旧协议边界回归 3 passed(0.85 秒)。
现有真实数据的局部拟合揭示原绑定错误,但修正后最大训练标签误差仍为 8.047 px,
原精度门限未通过;软件回归通过不代表实机 URDF 可发布。未重新运动或改写源证据。
2026-09-23 低精度离线草稿:新增集中 `test_raw_draft.py`,加已有合成正式 URDF
重建检查,13 passed(1.55 秒)。覆盖真实零位写入与 FK、缺测关节不改、JSON 零位/
曲线/来源篡改拒绝、不可观测零位拒绝、精度超限仍允许草稿、旧 Profile 仅允许标签
连杆修正、同步缺失帧不供给范围证据,以及 CLI 不进入运动或正式发布。
实测旧数据的正式 CLI 草稿路径已运行,生成完整结构 URDF 并通过标准 ROS 加载;
JSON/URDF FK 最大差 4.44e-16,两个拇指零位和四个行程实际改变。
独立精度验收仍失败,输出 `accuracy_passed=false`,没有更新 `latest_passed`。
第一次实数据导出因原始帧含空指令失败,修复共享证据过滤后 v2 成功;未删除失败审计。
2026-09-23 全手 15 零位/20 行程目标及采集后自动导出:受影响范围与真实 runner 生命周期
5 passed(1.75 秒),验证完整目标、部分数据不能冒充全手,以及成功/缺项/求解失败三种
情况下 SDK 栈、监控节点和自建 ROS 上下文均先关闭,离线阶段从不重新启动运动。
补充 Profile 原字节快照后,仅复查三个生命周期场景,3 passed(1.66 秒)。
正式 CLI --validate-only 通过,明确列出 15 个零位和 20 个行程目标。
必要的一次全手数学检查:独立 XML FK 生成 2028 帧训练角点,463 参数图像模型单初值
12 次联合迭代收敛;包括生成数据和秩检查共 31.82 秒,最大零位差 0.001054°。
复用保存参数进行完整 JSON→URDF 导出与标准加载,不重复拟合;15 个零位修正、五个
末端零位保留、20 个行程、最终 FK 最大差 5.55e-16 均通过。非实机验收、不更新正式指针。
2026-09-23 ID10 调整后的草稿断点:新增 `test_raw_remount.py`,验证 78 个连续通过方向
保留、旧 ID10 角点排除、原始像素不改、已用补采次数保留、重复调整声明拒绝、未知/
固定标签拒绝,以及固定基准和已知标签漂移仍拒绝。基准不可见标签只能进入草稿,不能
正式发布。首轮 5 passed,测试夹具共享列表导致 1 failed;修正夹具后,对失败项、CLI、
中断预算及受影响草稿契约运行 19 passed(2.74 秒)。没有恢复已删除的历史测试。
随后按 CAD 拓扑隔离整条受影响手指,验证旧观测不混用、已开始扫描禁止扩大排除范围,
受影响 6 passed(1.14 秒)。
2026-09-23 中指侧摆 0–80 短段:按已声明段长度缩放反馈分箱密度,保留图像/指令覆盖、
实际运动分辨率、4 秒推进及其他硬件保护。相关短段、堵转/反向/噪声、硬件保护、离线
生命周期与范围证据检查 14 passed(3.02 秒)。只读复核 `20260923_125329` 的两个
第二次完整尝试均通过,原始失败记录未改写,结果保存为 `short_segment_reassessment.json`。
## 离线零位方向回归
`test_raw_draft.py` 中的 `parallel_root_motion` 用同一批不变角点核对平行根轴方向,
四指 SDK/URDF 符号反转时必须拒绝,不能通过关节零位吸收错误。
`old_capture_model_correction` 验证离线绑定/方向修订仍保留原始采集身份,并拒绝速度变更。
方向用例来自首轮实采角点节选 `fixtures/o30_recorded_root_directions.json.gz`,
保留来源 SHA256,不含验证轮。其余数值回归仍使用合成数据;不发送硬件指令。
2026-09-23 拇指独立原始采集:局部范围编译保留 `raw_joint_2_plus_1`,清除被保留关节的
零位测量声明;训练策略允许经过范围契约验证的 O30 局部配置。复用原执行器和补采预算,
未修改拟合模型或运动保护。新增范围往返序列化、24 单元原路线/分区一致、立即补一次与归位后
结束测试,连同全手原调度两项回归共 4 passed(1.03 秒)。
实机会话 `thumb_recapture_20260923_175829/O30_RIGHT_001/20260923_180129` 在启动归位阶段
MCP 指令 0/反馈 120,两次无推进后停止;正式扫描 0/24,不能记为实机采集通过。
标定控制链已关闭,原全手数据未修改,等待现场机械接触观察。
2026-09-23 新外参拇指与旧四指离线组合:修复独立验证总判定的 NumPy bool_ JSON
序列化失败;新增冻结旧参考参数的图像拟合更新与显式局部验证范围。参数按语义转移,
不共享新旧相机外参,不改变 CAD 轴,无观测增量冻结,零位存在自由规范时拒绝。
`test_raw_joint_update.py test_raw_draft.py` 共 37 passed(20.74 秒);随后加入零位
可观测性保护,更新工具相关 3 passed(0.19 秒)。全手默认验证仍拒绝缺失关节,
局部报告不得视为全手验收。未恢复删除的历史测试。
实采组合草稿通过 JSON 重建、最终 FK(7.36e-16)、标准加载与 MuJoCo 编译。
曲线模型角度检查通过不等于 URDF 线性驱动通过:纯 URDF yaw 最大误差约 3.52°,
精度未认证,不更新 latest_passed。详见
`calibration_output/thumb_recapture_20260923_175829/offline_combined_new_thumb_draft/README.md`。
2026-09-29 G20/L6/O6/O12 原图离线反馈改造:受影响 `test_feedback_image_fit.py`、
`test_feedback_image_zero.py`、`test_feedback_image_graph.py`、`test_raw_feedback_protocol.py`
定向组最终 14 passed、1 deselected(2.54 秒);省略的 O6 整手虚拟采集在相同采集代码版本的前一轮已通过,未重复执行。
本轮验证反馈拟合仅取 0~3 轮、指令拟合仅取 4~5 轮、空间零位仍取反馈轮、
跨视角零位缺失拒绝、缺采样计划先于相机几何拒绝、原始照片进入最终图像验收入口。
合成 O6 投影可重建零位保持姿态,自动双解求解仍拒绝正对相机的欠确定几何。
正式发布接线被自动审核拒绝,未落盘;目前离线只生成不可发布草稿并作结构与 ROS
加载检查。没有真实新协议完整会话,草稿生成及最终图像精度尚未实测通过。
2026-09-29 原图反馈最终文件验收接线:`test_feedback_raw_release.py`、
`test_feedback_image_fit.py`、`test_feedback_image_zero.py`、
`test_feedback_image_graph.py`、`test_raw_feedback_protocol.py` 定向组
20 passed、1 deselected(2.79 秒)。额外核对四种原图 Profile 对各自包内源 URDF 的
发布几何前置检查均通过;产品配置加载中 O6 通过,G20/L6 因配置指向的外参文件缺失
停止,O12 因 SDK 包哈希不符停止。新增最终反馈/指令原始角点输入和失败不提交测试,
并核对 `--offline-raw` 将显式发布意图传到新 finalizer;尚无完整实拍新协议数据,
不把合成或 mock 测试记为实机精度通过。四型号默认生产策略切换被自动审核拒绝,
未落盘;仍需显式 `--training-policy raw_feedback_3_plus_1`。
2026-09-29 用户明确批准四型号默认改为原图封存后:G20/L6/O6/O12 的 Profile
`training_policy` 改为 `raw_feedback_3_plus_1`,四份产品配置的受保护 Profile SHA256
同步。定向离线/门槛组 20 passed、1 deselected(2.79 秒);默认策略、旧 fixed
显式回放和 O6 完整虚拟协调器采集组 9 passed、4 deselected(12.31 秒)。
虚拟整手仅证明采集、归位、封存和分区,不证明真实 IPPE 可解率或最终 URDF 精度。
G20/L6 产品配置缺外参、O12 SDK 包哈希问题仍在,未改写外部身份输入。
2026-09-29 默认原图策略后补查历史读取:原有图像数据集、双解候选、覆盖率、
零位前运动诊断组初次 17 passed、2 failed(1.08 秒),失败为旧简化日志被新默认
误按完整原图协议读取及旧夹具缺静止来源照片。只读工具改为按日志的 `capture_plan`
选择 `fixed`/新协议,旧夹具显式选 `fixed` 后 19 passed(1.87 秒)。
`test_offline_first_capture.py` 初次 11 passed、1 failed(1.07 秒),旧断言要求
O6 默认封存协议为姿态样本;按获批的新默认改为原图协议后 12 passed(1.04 秒)。
正式 O6 `runner.main --validate-only` 只读检查通过,显示 3 任务及
`raw_feedback_3_plus_1`;未连接或驱动手部硬件。
@@ -0,0 +1,133 @@
g20_thumb_calibration:
ros__parameters:
command_topic: /g20/cb_left_hand_control_cmd
state_topic: /g20/cb_left_hand_state
info_topic: /g20/cb_left_hand_info
camera_info_topic: /camera/camera/color/camera_info
image_topic: /camera/camera/color/image_rect
detections_topic: /apriltag/detections
tf_topic: /tf
# Use PnP translations as 3-D Tag centres and fit the directly observable
# root/MCP circles. The passive IP output follows the G20 URDF mimic
# relation below; its small residual T5 circle is diagnostic only. PnP
# orientations remain auxiliary quality checks. Command 255 is zero.
angle_estimation_mode: trajectory_center_3d
passive_ip_multiplier: 1.02
publish_debug_image: false
debug_max_rate_hz: 10.0
debug_scale: 0.5
# Default: send one end-to-end command per direction and pair every valid
# AprilTag frame with the timestamp-interpolated actual G20 state.
scan_mode: continuous
continuous_motion_mode: endpoint
repetitions: 1
# Used only by point-mode fallback and validation approach offsets.
command_step: 8
auto_start_tip: true
maximum_state_image_skew_ms: 150.0
continuous_endpoint_tolerance_u8: 2.0
continuous_endpoint_hold_seconds: 1.0
continuous_timeout_seconds: 90.0
continuous_invalid_timeout_seconds: 3.0
continuous_minimum_valid_frames: 40
continuous_minimum_state_span_u8: 240.0
continuous_minimum_bins: 32
continuous_maximum_bin_gap: 16
# Keep the responsive firmware speed, but pace it through the same
# 8-unit grid without waiting for static image captures at each point.
continuous_segment_minimum_seconds: 0.1
continuous_segment_timeout_seconds: 5.0
continuous_prepare_timeout_seconds: 30.0
preflight_frames: 150
minimum_detection_rate: 0.95
minimum_detection_hz: 15.0
maximum_hamming: 0
minimum_decision_margin: 30.0
# Trial threshold for small/far tags (historically observed at 32-38 px).
# Final acceptance is still guarded by static RMS and random validation.
minimum_edge_pixels: 30.0
# Current 30 px tags measure about 0.50-0.53 deg RMS while stationary.
# Keep a small practical margin here; final random validation stays at
# MAE <= 2 deg and P95 <= 3 deg.
# Match the preflight noise gate to the 3 deg robust capture gate below.
# The final calibration is still accepted only by the independent
# validation MAE/P95 limits, not by this readiness check.
maximum_static_std_deg: 3.0
pose_outlier_threshold_deg: 5.0
minimum_pose_inlier_rate: 0.90
pnp_minimum_valid_rate: 0.95
# 30-38 px tags are usable, but only if IPPE gives a tight image fit and
# a pose continuous with the preceding frame.
pnp_maximum_reprojection_error_px: 1.5
# Independent IPPE selection inherits the shared near-tie tolerance from
# core/geometry/pnp.py; continuity cannot override a clear image-fit lead.
pnp_maximum_pose_jump_deg: 35.0
pnp_maximum_translation_jump_m: 0.04
pnp_maximum_tag_tilt_deg: 75.0
# Preserve the branch through short detector gaps. A continuous sweep
# already pauses after 3 s without valid synchronised observations.
pnp_tracker_reset_seconds: 5.0
# Select all four IPPE branches as one kinematic chain. This prevents T4
# and T5 from independently changing mirror branches at the turnaround or
# during validation while still allowing real joint motion frame-to-frame.
pnp_group_relative_rotation_scale_deg: 5.0
pnp_group_relative_translation_scale_m: 0.01
# Reprojection remains a tie-breaker; temporal joint-chain continuity is
# deliberately dominant for the current 30-38 px planar tags.
pnp_group_reprojection_weight: 0.05
# Whole-sweep branch review. During a root sweep T3/T4/T5 should retain
# rigid relative poses; during a tip sweep T0/T3 should remain fixed.
pnp_trajectory_reprojection_scale_px: 0.1
pnp_rigid_rotation_scale_deg: 5.0
pnp_rigid_translation_scale_m: 0.01
# Judge the complete rigid trajectory against a robust sweep reference.
# Reject persistent drift at P95; keep a looser hard maximum so one noisy
# 30 px endpoint frame does not discard an otherwise sound sweep.
pnp_rigid_p95_accepted_drift_deg: 8.0
pnp_rigid_maximum_accepted_drift_deg: 15.0
# Centre-trajectory mode judges branch consistency by the Euclidean
# distance between rigid Tag centres. This is deliberately independent
# of the noisy planar-Tag orientation returned by PnP.
pnp_rigid_p95_accepted_distance_drift_m: 0.003
pnp_rigid_maximum_accepted_distance_drift_m: 0.006
# Three-dimensional centre-trajectory geometry gates. T0 stays on the
# palm as the translation anchor; T3/T4/T5 are the moving thumb points.
trajectory_maximum_plane_rms_m: 0.004
trajectory_maximum_radial_rms_m: 0.004
trajectory_minimum_radius_m: 0.005
trajectory_minimum_arc_deg: 15.0
trajectory_maximum_root_role_disagreement_deg: 5.0
trajectory_maximum_anchor_drift_m: 0.005
trajectory_static_translation_outlier_m: 0.005
trajectory_maximum_static_translation_rms_m: 0.002
# Static captures are now used only for sweep preparation and validation.
stable_frames: 5
capture_frames: 8
minimum_settle_seconds: 0.4
# This only confirms that the hand has stopped before an 8-frame robust
# median capture. The passive T4->T5 pair currently has about 2.3 deg
# peak spread over five 30 px PnP frames, while its two IPPE branches are
# separated by about 5.5 deg. A 3 deg gate accepts measurement jitter but
# still rejects a branch change. Final MAE/P95 limits remain unchanged.
maximum_stable_spread_deg: 3.0
# In centre mode the stationary capture gate is expressed in metres.
maximum_stable_translation_spread_m: 0.003
settle_timeout_seconds: 10.0
capture_timeout_seconds: 10.0
validation_command_count: 5
# The backlash approach point only waits for feedback to reach the target;
# it no longer performs an unnecessary image capture.
validation_approach_minimum_seconds: 0.2
validation_approach_timeout_seconds: 10.0
validation_position_tolerance_u8: 2.0
validation_seed: 20260727
maximum_validation_mae_deg: 2.0
maximum_validation_p95_deg: 3.0
maximum_coupling_drift_deg: 2.0
minimum_ip_coupling_r_squared: 0.98
maximum_monotonic_correction_deg: 2.0
maximum_hysteresis_deg: 5.0
@@ -0,0 +1,59 @@
g20_thumb_cmc_pitch_zero:
ros__parameters:
t0_id: 0
t3_id: 1
joint_name: thumb_cmc_pitch
motor_index: 0
zero_command_u8: 255
measure_travel: false
baseline_command_u8:
[255, 255, 255, 255, 255, 255, 193, 148, 105, 42,
245, 255, 255, 255, 255, 255, 255, 255, 255, 255]
repetitions: 3
zero_capture_frames: 30
# Each round sends one 255->64 endpoint command and one 64->255 return
# command. All valid T3-minus-T0 centres observed during both motions are
# state-binned and fitted to one image-plane circle.
trajectory_command_u8: 64
trajectory_bin_size_u8: 8.0
trajectory_minimum_frames: 45
trajectory_minimum_bins: 18
trajectory_minimum_state_span_u8: 160.0
trajectory_minimum_radius_px: 20.0
trajectory_minimum_arc_deg: 20.0
trajectory_maximum_radial_rms_px: 2.0
trajectory_maximum_p95_radial_error_px: 3.5
trajectory_endpoint_settle_seconds: 0.3
trajectory_timeout_seconds: 30.0
settle_seconds: 0.5
move_timeout_seconds: 20.0
capture_timeout_seconds: 15.0
state_tolerance_u8: 2.0
preflight_frames: 60
minimum_detection_rate: 0.95
maximum_hamming: 0
minimum_decision_margin: 30.0
minimum_edge_pixels: 40.0
maximum_static_position_rms_px: 1.5
maximum_round_difference_deg: 1.0
maximum_return_error_deg: 1.0
# Zero direction is always T3 centre -> fitted circle centre. T3's printed
# orientation and corner +x direction are deliberately not used.
maximum_zero_radial_error_px: 4.0
# Detect a long physical table/reference edge in the lower image. The red
# target and blue detected line are display-only aids for manual alignment;
# they never block preflight or the start service.
camera_alignment_enabled: true
camera_alignment_reference_y_ratio: 0.90
camera_alignment_roi_y_min_ratio: 0.55
camera_alignment_roi_y_max_ratio: 0.98
camera_alignment_minimum_line_length_ratio: 0.30
camera_alignment_max_candidate_angle_deg: 15.0
camera_alignment_max_angle_deg: 0.5
camera_alignment_max_vertical_offset_px: 12.0
camera_alignment_required_frames: 10
camera_alignment_minimum_detection_rate: 0.8
camera_alignment_max_age_seconds: 1.0
publish_debug_image: true
debug_max_rate_hz: 10.0
debug_scale: 0.75
@@ -0,0 +1,60 @@
g20_thumb_cmc_roll_calibration:
ros__parameters:
t0_id: 0
t3_id: 1
joint_name: thumb_cmc_roll
motor_index: 5
zero_command_u8: 255
measure_travel: true
baseline_command_u8:
[255, 255, 255, 255, 255, 255, 193, 148, 105, 42,
245, 255, 255, 255, 255, 255, 255, 255, 255, 255]
repetitions: 3
zero_capture_frames: 30
# Measure the complete motor-5 range. Each round captures both static
# endpoints around one 255->0->255 circle trajectory.
trajectory_command_u8: 0
trajectory_bin_size_u8: 8.0
trajectory_minimum_frames: 65
trajectory_minimum_bins: 30
trajectory_minimum_state_span_u8: 240.0
trajectory_minimum_radius_px: 20.0
trajectory_minimum_arc_deg: 20.0
trajectory_maximum_radial_rms_px: 2.0
trajectory_maximum_p95_radial_error_px: 3.5
trajectory_endpoint_settle_seconds: 0.3
trajectory_timeout_seconds: 35.0
settle_seconds: 0.5
move_timeout_seconds: 25.0
capture_timeout_seconds: 15.0
state_tolerance_u8: 2.0
preflight_frames: 60
minimum_detection_rate: 0.95
maximum_hamming: 0
minimum_decision_margin: 30.0
minimum_edge_pixels: 40.0
maximum_static_position_rms_px: 1.5
maximum_round_difference_deg: 1.0
maximum_travel_difference_deg: 1.0
minimum_travel_deg: 20.0
maximum_return_error_deg: 1.0
# Zero direction is always T3 centre -> fitted circle centre. T3's printed
# orientation and corner +x direction are deliberately not used.
maximum_zero_radial_error_px: 4.0
# Detect a long physical table/reference edge in the lower image. The red
# target and blue detected line are display-only aids for manual alignment;
# they never block preflight or the start service.
camera_alignment_enabled: true
camera_alignment_reference_y_ratio: 0.90
camera_alignment_roi_y_min_ratio: 0.55
camera_alignment_roi_y_max_ratio: 0.98
camera_alignment_minimum_line_length_ratio: 0.30
camera_alignment_max_candidate_angle_deg: 15.0
camera_alignment_max_angle_deg: 0.5
camera_alignment_max_vertical_offset_px: 12.0
camera_alignment_required_frames: 10
camera_alignment_minimum_detection_rate: 0.8
camera_alignment_max_age_seconds: 1.0
publish_debug_image: true
debug_max_rate_hz: 10.0
debug_scale: 0.75
@@ -0,0 +1,32 @@
<?xml version="1.0" encoding="UTF-8" ?>
<dds>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
<transport_descriptors>
<transport_descriptor>
<transport_id>g20_udp_transport</transport_id>
<type>UDPv4</type>
<sendBufferSize>10485760</sendBufferSize>
<receiveBufferSize>10485760</receiveBufferSize>
</transport_descriptor>
<transport_descriptor>
<transport_id>g20_shm_transport</transport_id>
<type>SHM</type>
<segment_size>67108864</segment_size>
<port_queue_capacity>512</port_queue_capacity>
<healthy_check_timeout_ms>1000</healthy_check_timeout_ms>
</transport_descriptor>
</transport_descriptors>
<participant
profile_name="g20_large_image_participant"
is_default_profile="true">
<rtps>
<userTransports>
<transport_id>g20_udp_transport</transport_id>
<transport_id>g20_shm_transport</transport_id>
</userTransports>
<useBuiltinTransports>false</useBuiltinTransports>
</rtps>
</participant>
</profiles>
</dds>
@@ -0,0 +1,30 @@
/apriltag/apriltag:
ros__parameters:
image_transport: raw
# Live calibration needs the newest frame, not lossless delivery of stale
# frames. BEST_EFFORT prevents a slow full-resolution detection callback
# from back-pressuring image_proc's reliable image publisher.
qos_profile: sensor_data
family: 36h11
size: 0.016
profile: false
max_hamming: 0
detector:
threads: 4
decimate: 1.5
blur: 0.0
refine: true
sharpening: 0.25
debug: false
pose_estimation_method: pnp
tag:
ids: [0, 1, 2, 3]
frames: [tag_t0, tag_t3, tag_t4, tag_t5]
sizes: [0.016, 0.016, 0.016, 0.016]
g20_thumb_calibration:
ros__parameters:
tag_roles: [t0, t3, t4, t5]
tag_ids: [0, 1, 2, 3]
tag_frames: [tag_t0, tag_t3, tag_t4, tag_t5]
tag_sizes_m: [0.016, 0.016, 0.016, 0.016]
@@ -0,0 +1 @@
../linkerhand_calibration/models/g20/config/g20_right_product.yaml
@@ -0,0 +1 @@
../linkerhand_calibration/models/l6/config/l6_right_8_tags.yaml
@@ -0,0 +1 @@
../linkerhand_calibration/models/l6/config/l6_right_product.yaml
@@ -0,0 +1 @@
../linkerhand_calibration/models/l6/config/l6_three_camera_calibration.yaml
@@ -0,0 +1 @@
../linkerhand_calibration/models/o12/config/o12_right_16_tags.yaml
@@ -0,0 +1 @@
../linkerhand_calibration/models/o12/config/o12_right_product.yaml
+1
View File
@@ -0,0 +1 @@
../linkerhand_calibration/models/o12/config/o12_sdk.yaml
@@ -0,0 +1 @@
../linkerhand_calibration/models/o12/config/o12_three_camera_calibration.yaml
@@ -0,0 +1 @@
../linkerhand_calibration/models/o30/config/o30_right_18_tags.yaml
@@ -0,0 +1 @@
../linkerhand_calibration/models/o30/config/o30_right_product.yaml
@@ -0,0 +1 @@
../linkerhand_calibration/models/o30/config/o30_three_camera_calibration.yaml
@@ -0,0 +1 @@
../linkerhand_calibration/models/o6/config/o6_right_8_tags.yaml
@@ -0,0 +1 @@
../linkerhand_calibration/models/o6/config/o6_right_product.yaml
@@ -0,0 +1 @@
../linkerhand_calibration/models/o6/config/o6_three_camera_calibration.yaml
@@ -0,0 +1 @@
../../linkerhand_calibration/models/g20/config/profiles/g20_right_19.yaml
@@ -0,0 +1 @@
../../linkerhand_calibration/models/l6/config/profiles/l6_right_8.yaml
@@ -0,0 +1 @@
../../linkerhand_calibration/models/o12/config/profiles/o12_right_16.yaml
@@ -0,0 +1 @@
../../linkerhand_calibration/models/o30/config/profiles/o30_right_18.yaml
@@ -0,0 +1 @@
../../linkerhand_calibration/models/o6/config/profiles/o6_right_8.yaml
@@ -0,0 +1,44 @@
$schema: https://json-schema.org/draft/2020-12/schema
title: LinkerHand calibration profile
type: object
additionalProperties: false
required:
- schema_version
- profile_id
- namespace
- sdk_adapter
- command
- vision
- motion
- measurement
- zero
- quality
- scope
- artifacts
- urdf
properties:
schema_version: {const: 1}
profile_id: {type: string, pattern: "^[A-Za-z0-9_-]+/(left|right)/[a-z0-9_-]+/v[1-9][0-9]*$"}
namespace: {type: string, pattern: "^/[^/].*[^/]$"}
sdk_adapter: {type: string, minLength: 1}
command: {type: object}
vision: {type: object}
motion: {type: object}
measurement: {type: object}
zero: {type: object}
quality: {type: object}
scope: {type: object}
artifacts: {type: object}
acquisition: {type: object}
urdf:
type: object
required: [authorized_fields]
properties:
authorized_fields:
type: object
additionalProperties:
type: array
uniqueItems: true
items:
enum: [origin.rpy, limit.lower, limit.upper, mimic.multiplier, mimic.offset]
joint_coverage: {type: object}
@@ -0,0 +1,14 @@
$schema: https://json-schema.org/draft/2020-12/schema
title: LinkerHand calibration product
type: object
required: [schema_version, profile_id, serial_number, cameras, artifacts]
properties:
schema_version: {type: integer, minimum: 2}
profile_id: {type: string}
profile_config: {type: string}
serial_number: {type: string, pattern: "^[A-Za-z0-9_.-]+$"}
namespace: {type: string}
sdk: {type: object}
cameras: {type: object, minProperties: 1}
artifacts: {type: object}
release: {type: object}
@@ -0,0 +1,191 @@
g20_calibration:
ros__parameters:
command_topic: /g20/cb_left_hand_control_cmd
state_topic: /g20/cb_left_hand_state
info_topic: /g20/cb_left_hand_info
setting_topic: /g20/cb_hand_setting_cmd
front_camera_info_topic: /g20_calibration/front/camera/camera_info
front_detections_topic: /g20_calibration/front/apriltag/detections
side_camera_info_topic: /g20_calibration/side/camera/camera_info
side_detections_topic: /g20_calibration/side/apriltag/detections
top_camera_info_topic: /g20_calibration/top/camera/camera_info
top_detections_topic: /g20_calibration/top/apriltag/detections
# /start先下发并确认这个20通道基准姿态,稳定后才进入第一条扫描。
baseline_command_u8: [255, 255, 255, 255, 255, 255, 127, 127, 127, 127, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255]
normal_calibration_speed: 15
index_roll_calibration_speed: 5
index_flex_calibration_speed: 10
# 19-Tag产品预检仍使用上面保守速度;只有正反预检都留出至少双倍正式分箱余量,
# 才把非roll任务正式扫描最多提速1.5倍。四指roll受0.5°回差门限约束,
# 始终保持速度5;任一方向采样余量不足也保持原速度。
adaptive_formal_speed_enabled: true
adaptive_formal_speed_max_scale: 1.5
adaptive_formal_speed_minimum_bins: 64
adaptive_formal_speed_maximum_bin_gap: 8
speed_setting_settle_seconds: 0.25
# tag36h11尺寸是检测角点围成的黑色正方形边长,不包含外围白边。
# 19张Tag的黑色码区外边长均为16 mm。自定义PnP必须与
# apriltag_ros逐ID尺寸一致,禁止用纸张/白边尺寸代替码区尺寸。
tag_size_m: 0.016
# ROS 2无法从YAML空数组推断整数/浮点数组类型。这四个
# 末端Tag仍显式写16 mm,防止节点启动时得到未初始化参数。
tag_size_override_ids: [7, 14, 16, 18]
tag_size_overrides_m: [0.016, 0.016, 0.016, 0.016]
repetitions: 3
# 19-Tag产品正式零位使用前三轮训练、最后一轮完全留出;旧11-Tag仍读取repetitions=3。
g20_right_19_repetitions: 4
preflight_frames: 60
minimum_detection_rate: 0.95
minimum_detection_hz: 15.0
minimum_feedback_hz: 25.0
maximum_hamming: 0
minimum_decision_margin: 30.0
minimum_edge_pixels: 30.0
pnp_maximum_reprojection_error_px: 1.5
pnp_maximum_pose_jump_deg: 35.0
pnp_maximum_translation_jump_m: 0.04
pnp_maximum_tag_tilt_deg: 75.0
pnp_tracker_reset_seconds: 5.0
# 标定任务不再用第一帧决定平面Tag的IPPE分支;静止端点联合8帧选择整组最稳定解。
pnp_group_initialization_frames: 8
# 侧面当前任务所需Tag在初始化端点的贴面法向应一致;用此先验消除静态IPPE镜像双解。
pnp_group_normal_alignment_scale_deg: 5.0
pnp_group_maximum_normal_alignment_deg: 15.0
# 三个拇指顶部任务共用预检时冻结的Tag 8位姿。Tag 8仍须实时可见;
# 任一角点相对会话基准漂移超过2 px并连续5帧时,判定标定中基准被移动。
fixed_base_maximum_corner_drift_px: 5.0
fixed_base_movement_confirmation_frames: 10
# 仅在拇指MCP/IP同步运动且至少一个候选落入可信区间时,用源URDF mimic
# 关系辅助选择IPPE分支;若全部候选超限则退回纯视觉,绝不丢帧,也不生成、
# 缩放或替代被动IP的自身Tag实测曲线。
thumb_ip_pnp_coupling_multiplier: 1.03
thumb_ip_pnp_coupling_scale_deg: 3.0
thumb_ip_pnp_maximum_coupling_residual_deg: 7.5
top_pnp_invalid_reset_seconds: 1.0
# 三维位姿必须与实测20通道状态严格按时间戳配对。
maximum_state_image_skew_ms: 50.0
axis_maximum_plane_rms_m: 0.003
# 被动耦合轴只用轨迹确定轴线位置,允许更大的轴向深度噪声;径向和跨轮
# 轴线一致性仍沿用严格检查。
passive_axis_maximum_plane_rms_m: 0.004
axis_maximum_radial_rms_m: 0.003
# 整段相对SE(3)运动拟合轴线点;端视关节会投影掉单目PnP光轴深度。
axis_maximum_pose_line_rms_m: 0.001
# 仅用于运动平面在三维中可观测的斜视关节;近图像平面关节使用姿态轴
# 约束三维圆,不让单目平面Tag的深度噪声自由决定转轴方向。
axis_maximum_rotation_circle_difference_deg: 1.0
# 单轴模型残差与跨轮重复误差分开判定:主动刚性关节要求更严;被动耦合
# 关节允许可重复的非理想单轴分量,但仍须通过0.75°跨轮轴差及最终轮留出。
active_maximum_rotation_orthogonal_rms_deg: 2.5
passive_maximum_rotation_orthogonal_rms_deg: 7.5
zero_maximum_axis_cycle_difference_deg: 0.75
# 零位无法改变父子轴夹角;超过该值属于CAD/PnP几何错误,不能吸收到零位。
zero_maximum_axis_cone_mismatch_deg: 5.0
zero_maximum_observability_condition_number: 10000000000.0
zero_maximum_offset_deg: 20.0
# 四指MCP roll保留严格的装配保护范围。thumb CMC三轴由多轴视觉几何
# 求解且不假定电气端点等于CAD上限;thumb_mcp及四指MCP pitch/PIP
# 静态零位由实测全行程与CAD机械端点联合求解,不写死为0。
zero_finger_maximum_offset_deg: 3.0
# 只对实物已确认等同CAD端点的关节使用该限制;CMC电气端点不作此假设。
mechanical_endpoint_maximum_offset_deg: 5.0
endpoint_tolerance_u8: 2.0
# 请求命令与固件反馈是两个标定域。稳态检查点允许小幅死区,但反馈
# 必须已经稳定;大残差仍由机械卡滞保护处理。
steady_checkpoint_command_feedback_tolerance_u8: 8.0
steady_checkpoint_maximum_feedback_range_u8: 2.0
# 电机10在命令0时实测会稳定反馈为4;该0端使用±4。
thumb_yaw_zero_endpoint_tolerance_u8: 4.0
# 右手电机10在命令255时多次实测稳定反馈为250;仅右手该端点使用±5。
right_thumb_yaw_255_endpoint_tolerance_u8: 5.0
# 右手小指PIP电机19在命令0时固件反馈稳定饱和为5;仅其0端使用±5。
pinky_pip_zero_endpoint_tolerance_u8: 5.0
endpoint_hold_seconds: 0.5
# roll零位127必须从两个方向到位并静止采集,禁止用运动中经过127的帧判回差。
baseline_hold_seconds: 0.5
minimum_baseline_hold_frames: 10
# unified_engine_v2 不执行每任务全行程预检;保留参数仅兼容旧配置读取。
task_precheck_hold_seconds: 2.0
position_timeout_seconds: 30.0
sweep_timeout_seconds: 90.0
# 启动宽限1秒后,反馈连续2秒没有至少1个u8的进展,按机械卡滞立即暂停;
# 这类硬故障不自动重试。
motor_stall_timeout_seconds: 2.0
motor_stall_startup_grace_seconds: 1.0
motor_stall_minimum_progress_u8: 1.0
invalid_timeout_seconds: 3.0
minimum_sweep_frames: 40
minimum_state_span_u8: 240.0
minimum_sweep_bins: 32
maximum_bin_gap: 16
# 可恢复的采样失败自动重扫当前方向;超过次数才暂停等待人工处理。
automatic_sweep_retry_limit: 1
# 轨迹拟合失败优先只重扫失败轮次;零位/URDF模型失败不重复运动。
automatic_fit_retry_limit: 0
automatic_motion_retry_limit: 0
# 留空为正式标定;设为pinky/ring/middle/index时只采该指正面+侧面roll,
# 即使正面baseline回差失败也继续完成侧面对照,并永久锁定本会话URDF发布。
cross_view_roll_diagnostic_finger: ""
# 过程检查允许25%的黄色预警带,最终验收仍使用下面的严格门限。
provisional_warning_ratio: 1.25
retry_minimum_speed: 3
retry_speed_scales: [1.0]
retry_endpoint_hold_seconds: [0.5]
trajectory_maximum_plane_rms_m: 0.004
trajectory_maximum_radial_rms_m: 0.004
trajectory_minimum_radius_m: 0.003
trajectory_minimum_arc_deg: 15.0
# 以下二维参数只供旧轨迹工具兼容,三机位v4零位不使用二维投影。
image_trajectory_maximum_radial_rms_px: 2.0
image_trajectory_maximum_radial_p95_px: 3.5
image_trajectory_minimum_radius_px: 20.0
trajectory_maximum_cycle_travel_difference_deg: 3.0
passive_maximum_cycle_travel_difference_deg: 10.0
maximum_monotonic_correction_deg: 2.0
# 旧布局仍用连续扫描正反程差门限;19-Tag产品的连续运动包含速度相关滞后,
# 由方向曲线和最终留出验证建模,不再重复硬判。其绝对正反程门禁使用下面
# 的九点稳态command_maximum_direction_gap_deg。
maximum_hysteresis_deg: 2.0
# 19-Tag产品模式额外要求每轮正反方向在各自baseline处绕实测关节轴的角度差
# 不超过0.5°;四指roll例外:127以255→127为唯一物理零位,反向分支
# 保留实测偏差,并改为检查分支间隙上限及跨轮稳定性。
baseline_maximum_hysteresis_deg: 0.5
directional_zero_maximum_branch_gap_deg: 2.0
directional_zero_maximum_branch_gap_range_deg: 0.3
cross_view_roll_maximum_branch_gap_difference_deg: 0.3
# 正面roll是Tag中心的二维投影角,侧面roll是三维姿态角。允许一个有界的
# 固定比例吸收Tag安装倾角/偏置带来的投影缩放,再严格比较两条曲线形状;
# 比例过大、方向相反、形状RMS及两视角各自的四轮重复性仍会失败。
cross_view_roll_maximum_shape_rms_deg: 1.25
cross_view_roll_maximum_projection_scale_ratio: 1.5
passive_maximum_monotonic_correction_deg: 3.0
passive_maximum_hysteresis_deg: 2.0
# 九点姿态先按实测反馈重新对齐,再用此门限检查固有机械回差;请求命令域
# 的两条运行曲线仍原样保留固件方向死区,不能把command/feedback差算成回差。
command_maximum_direction_gap_deg: 2.0
# 默认无额外随机动作;19-Tag产品最终一轮始终作为不可关闭的留出验证。
validation_enabled: false
# 第四轮留出求解后必须再走8个固定安全组合姿态;三机位规定Tag全部可见
# 且实测20通道到位才允许发布。只保存Tag位姿,不保存原始图像。
# Developer diagnostic only. The formal fourth sweep cycle already gives
# every isolated PIP/DIP pair an independent holdout.
combination_validation_enabled: false
combination_validation_frames: 10
combination_maximum_position_p95_m: 0.003
combination_maximum_orientation_p95_deg: 2.0
validation_command_count: 3
validation_frames: 10
validation_seed: 20260804
validation_timeout_seconds: 20.0
maximum_validation_mae_deg: 1.0
maximum_validation_p95_deg: 2.0
# 19-Tag产品模式使用更严格的任一点及静态零偏95%置信区间门限。
maximum_validation_error_deg: 3.0
zero_maximum_confidence_half_width_deg: 1.5
@@ -0,0 +1,62 @@
/g20_calibration/front/apriltag/apriltag:
ros__parameters:
image_transport: raw
qos_profile: sensor_data
family: 36h11
size: 0.016
profile: false
max_hamming: 0
detector:
threads: 4
decimate: 1.5
blur: 0.0
refine: true
sharpening: 0.25
debug: false
pose_estimation_method: pnp
tag:
ids: [0, 1, 2, 3, 10]
frames: [front_base, thumb_cmc, thumb_mcp, thumb_ip, index_roll]
sizes: [0.016, 0.016, 0.016, 0.016, 0.016]
/g20_calibration/side/apriltag/apriltag:
ros__parameters:
image_transport: raw
qos_profile: sensor_data
family: 36h11
size: 0.016
profile: false
max_hamming: 0
detector:
threads: 4
decimate: 1.5
blur: 0.0
refine: true
sharpening: 0.25
debug: false
pose_estimation_method: pnp
tag:
ids: [4, 5, 6, 7]
frames: [side_base, index_mcp, index_pip, index_dip]
sizes: [0.016, 0.016, 0.016, 0.016]
/g20_calibration/top/apriltag/apriltag:
ros__parameters:
image_transport: raw
qos_profile: sensor_data
family: 36h11
size: 0.016
profile: false
max_hamming: 0
detector:
threads: 4
decimate: 1.5
blur: 0.0
refine: true
sharpening: 0.25
debug: false
pose_estimation_method: pnp
tag:
ids: [8, 9]
frames: [top_base, thumb_yaw]
sizes: [0.016, 0.016]
@@ -0,0 +1 @@
../linkerhand_calibration/models/g20/config/three_camera_tags_g20_right_15.yaml
@@ -0,0 +1 @@
../linkerhand_calibration/models/g20/config/three_camera_tags_g20_right_19.yaml
@@ -0,0 +1,53 @@
# 全型号“先采集,后离线拟合”改造记录
## 目标
G20、L6、O6、O12、O30 都先采集并归位,关掉相机与手的控制进程,再单独拟合、验收、生成 URDF。拟合失败应保留已采的数据,不能重新启动手或抹掉采集结果。
## 本次已改
1. 普通型号完成扫描、归位后进入 `CAPTURE_COMPLETE`。不再从现场状态机进入最终 `FIT`。O30 原始图像流程保持原有终态。
2. 启动器看到 `CAPTURE_COMPLETE` 后先停止控制栈,再写 `capture_result.json`,引导使用 `--offline-raw`。
3. 所有正式采集开始前保存当次的型号配置、产品配置、URDF、标签、相机外参和内参快照。结束时为原始日志及快照写 SHA-256 清单 `raw_capture_manifest.json`。
4. 普通型号的封存协议标为 `measured_pose_samples_v1`;O30 仍为 `raw_joint_images_v2`。离线入口先验证清单、型号计划和数据完整性,再调用该型号原有的拟合与 URDF 验收流程。旧会话没有清单时仍按原有离线回放兼容。
5. 采集完成只表示“数据已封存”,不表示“精度通过”,不会在采集阶段发布 JSON 或 URDF。
## 当前执行顺序
```text
正式启动各型号
-> 保存当次输入快照
-> 现场安全检查、参考确认、扫描、检查数据覆盖、归位
-> 封存 raw_samples.jsonl 和输入文件
-> CAPTURE_COMPLETE,关闭 SDK/相机
-> 另起命令:标定程序 --offline-raw <会话/raw_samples.jsonl>
-> 校验封存文件、离线拟合、独立验证、生成候选 URDF
-> 仅验收通过且明确要求发布时才发布
```
使用 `--config <会话/capture_product.yaml> --offline-raw <会话/raw_samples.jsonl>`,以会话中的配置作为产品配置;它引用当次封存的配置和相机参数。默认离线拟合不发布;发布仍需明确指定 `--publish-offline`。
普通型号的原始角点离线输入、训练/验证分区和双候选计算进展见 [FEEDBACK_RAW_OFFLINE_MIGRATION.md](FEEDBACK_RAW_OFFLINE_MIGRATION.md)。
## 尚未完成的关键部分
G20、L6、O6、O12 的现场流程仍要在线确认关节零位和姿态分支,才能产生后续角度样本。明确的图像歧义现在可以延后任务并回访一次;回访后仍不能确认时,会继续其他独立任务、归位并封存为不完整。**因此目前只完成“最终拟合离线化”,尚未达到“任何拟合失败都不影响采集”的完整目标。**
不能直接把这些型号切到 O30 的原始图像开关:它们用分开的指令扫描轮次,O30 离线求解器只认交织的 0/1 训练轮与 3 验证轮;直接切换会产生无法拟合的数据。
## 下一阶段的改法与验收条件
1. 为普通型号建立独立的“只收原始图像与同步指令/反馈”的采集协议。现场只检查时间同步、可见性、覆盖率、运动和归位安全;不要用某个姿态分支是否解出来决定继续扫描。
2. 把关节零位、双姿态候选判别、父子链几何和角度样本生成搬到离线转换器。普通型号的分开采集轮次必须明确映射到训练和独立验证,不能借用 O30 的轮次假设。
3. 用各型号真实会话与合成退化数据验证:两解都能解、只有一解可用、两解都不可用。前两类应正常完成采集;最后一类应留下完整数据并在离线报告中指出缺哪种观察,不能现场误发布。
4. 只有每个型号离线求解、独立验证、标准 URDF 读回全部通过后,才把该型号正式切到纯原始图像采集。保持原有精度和发布门限。
## 本次验证
- 新增跨型号状态、动态轮次封存与篡改测试:6 项通过。
- 原有 O30 采集完成入口、缺项封存和单视角整手封存的定向测试通过;其中缺项会话保留离线审计记录并拒绝拟合。
- 未进行实机采集或全型号整手拟合;纯原始图像协议尚不可用于普通型号。
## 当前配置与实机验证限制
这次额外做了产品配置读取检查:O6 的输入快照可以保存并重新加载;G20/L6 的现有产品配置引用了尚不存在的 `config/g20_three_camera_extrinsics.yaml`;O12 的现有产品配置在供应商 Python SDK 包哈希检查处失败。这些在采集启动前就会报错,不能算作本次改造已通过四型号实机验收。需要对应的真实外参文件和匹配的 SDK 包后再进行实机联调,不能凭空生成外参或改哈希绕过。
@@ -0,0 +1,71 @@
# O30 右手标定稳定性与产物正确性审查
本次只分析并修改软件,没有启动 SDK、相机或机械手运动。实机指令下发后反馈不变的问题按硬件问题排除。原始日志、断点、Profile、保护输入哈希及运动顺序均未改写。
## 结论
流程确有软件层面的稳定性缺陷,不能把历次暂停全部归因于标签或硬件。本次修复准备观测准入、短暂缺帧的恢复分类,并统一在线与离线的完整采集验收入口。已有的姿态可观测性、独立留出验证及 JSON/URDF 回读要求继续保留。
“少暂停”与“结果正确”需要分别处理:短暂坏帧应在采集层过滤或使用有次数上限的重试;真正无法区分的三维姿态、移动的固定参考、改变的标签安装或不完整数据,应明确拒绝生成通过产物。相同机位重复同一动作并不一定能提供区分姿态所需的新信息。
## 已定位并修改的问题
| 问题 | 原有行为及影响 | 本次修改 |
| --- | --- | --- |
| 无效观测覆盖有效准备帧 | 每个指令区间保存最后一帧;后来的空候选或不合法候选可以覆盖先前有效帧,随后整个运动求解被拒绝 | 在写入区间缓存前,复用求解器已有的候选质量检查;图像求解所需的根参考必须已冻结。只有完整有效帧才能替换缓存,原始坏帧仍保存在日志中 |
| 缺帧错误未进入重试策略 | 底层返回 `insufficient_image_frames` 或 `motion_candidates_missing_or_invalid`,已有恢复策略却只识别另一部分错误名称 | 将这些暂态错误纳入同一个恢复策略,每个尚未建立零位的任务/关节组最多重新执行一次准备动作;持续失败仍暂停 |
| 在线与离线的收尾检查边界不一致 | 离线入口检查完整扫描单元,在线直接进入最终拟合;若恢复数据只有旧通过标记或最新尝试不完整,缺少同一个入口检查 | 抽出 `runtime/artifacts/capture_validation.py`,最终生成入口统一检查配置身份、固定参考、相机内参、每个单元最新尝试及实际样本质量;两种产品入口均要求采集证据 |
| 大日志的重复扫描和额外内存 | 每个单元都遍历完整日志;离线计算日志哈希时额外一次性读取整个文件 | 按单元、任务各建一次索引,复用原有质量规则;日志哈希改为流式计算 |
候选准入只使用预先规定的检测质量条件,不根据拟合后的误差选择保留帧;保留的两种候选均进入原有比较,不填补不存在的另一种候选,也不改变最终精度阈值。准备记录增加 `preparation_observation_rejections`,可查到被拒绝观测的原因与数量。
若一个最新尝试同时存在通过与失败标记,拒绝通过;若只有较早尝试完成、较新尝试未完成,也拒绝通过。失败原因写入 `capture_validation.json`,并在拟合前返回,不能更新 `latest_passed`。
## 真实日志验证
### 无名指 MCP 准备阶段
来源:`calibration_output/O30_RIGHT_001/20260919_204235/raw_samples.jsonl`,侧面机位、运动版本 159。
- 原报告选择了 105 帧,其中 8 个区间的最终帧存在空候选,整体报 `motion_candidates_missing_or_invalid`。
- 从原日志抽取该段 430 条侧面观测,保存为 `test/fixtures/o30_ring_preparation_admission.json.gz`;不修改其角点、指令、反馈或候选。
- 新准入规则拒绝 14 条不合格候选观测,保留 97 个有效运动区间,求解不再因整段混入空候选而失败。
- 这段历史数据还存在候选族不完整和图像重投影失败,最终仍未授权模型。该验证证明准入缺陷已消除,不能用来宣称这段实机标定已经通过。
### 已保存的 96 个单元
来源:`calibration_output/O30_RIGHT_001/20260919_214048/raw_samples.jsonl`。
- 保存的会话具有唯一启动记录、唯一固定参考和三个相机模型;与当前产品的保护输入哈希及采集策略兼容。
- 离线提取日志中实际用于覆盖率和稳态质量检查的字段,执行相同单元验收:前 96 个单元通过,第 97 个 `middle_dip_side / cycle=0 / increasing` 因未采集而拒绝;没有将历史断点视为完整产物。
- 该检查不拟合历史图像,不修改断点;不是完整运动来源与最终图像验收的替代品。
- 正式断点启动仍使用 `passed` 恢复,直接复用通过单元。整套数据的完整检查放在最终生成阶段,不加入恢复启动路径。
## 目前合理且继续保留的边界
1. 几何求解与当前零位图像采集分别计时。已有实现会在参考复用后开启独立采集窗口,避免求解或加载耗时吃掉零位采样时间;此次未重复修改这一已修复逻辑。
2. 已冻结零位不能被局部重试替换;已成功安装部分机位模型、保持关节发生移动或固定参考冲突时,不自动重走准备动作。
3. 三维候选族无法区分时仍不授权。之前对正面、侧面共享标签、测得的父关节几何及其不确定度的修正继续保留;没有把父几何当作绝对真值。
4. 运动顺序仍是拇指、四指屈伸、四指侧摆。恢复不回到整手起点;本次没有增加未声明的辅助动作。
## JSON 与修正 URDF 的正确性检查
正式产物必须依次通过:
1. 保护输入、相机和固定参考身份检查;所有应采集单元的最新尝试完成,样本覆盖率、稳态节点和训练/验证输入范围合格。
2. 零位、运动模型、跨会话来源及共享标签证据一致;训练数据与独立验证图像不重叠。
3. 方向分别拟合的指令映射和零位通过独立留出检查,不能用训练拟合误差替代验收。
4. 先写标定 JSON,再从落盘 JSON 重建修正 URDF,回读核对两份文件对应关系。
5. 检查授权修改范围、运动学、角度和最终文件对应的独立像素重投影;标准 ROS URDF 加载检查通过后才允许发布。
6. 发布控制器复核候选文件哈希和取消状态,最后更新通过指针。采集完整性检查通过不等于整套产物已通过。
O30 当前契约有 20 个独立主动关节;末节 DIP/IP 的五个 CAD 零位假设必须在产物中明确保留其来源,不能写成五个已经独立实测的绝对零位。本次不改变这一契约。要声称这些绝对零位也经过实测,还需要相应独立观测。
## 软件验证范围
- 新增回归覆盖坏帧覆盖、全部坏帧、未冻结根参考、保留两种候选、真实无名指准备数据,以及在线/离线收尾对失败单元、未完成新尝试、配置和内参变化的拒绝。
- 恢复回归覆盖实际底层缺帧错误、一次重试后成功和持续失败后暂停;继续检查已通过单元复用、异步求解和零位窗口。
- 产物回归覆盖 O30 20 通道非线性映射、独立角点验证、JSON 重建 URDF、授权字段约束、进程收尾与发布取消。
- 共 198 项不同的相关回归测试通过,其中新增 18 项用例/参数组合。首批 28 项通过,综合批次 181 项通过(504.86 秒),去除重叠后为 198 项;最终收尾检查修改后又单独复跑 20 项,全部通过。Python 编译与 `git diff --check` 通过。
- 软件回归及合成数据验收不代表实机精度已达标;当前仍没有完成整手最终产物验收。
- 安装环境解析到当前源码目录,新增的共享验收模块可直接导入;没有启动实机程序验证。
@@ -0,0 +1,152 @@
# G20 / L6 / O6 / O12 原始图像离线求解改造记录
## 目标与当前状态
目标是现场只采集角点、指令、反馈和运动身份;回到安全位置并关掉控制栈之后,再离线判断 AprilTag 的两个姿态候选、求关节参考位、拟合反馈曲线和指令曲线、验收 URDF。
**当前 G20 / L6 / O6 / O12 的默认采集策略已切为 `raw_feedback_3_plus_1`,并接通对应离线求解链。**现场不确认运动标签姿态,也不冻结关节零位,先安全走完采集并封存数据。离线阶段使用原有反馈、指令、空间零位和最终文件验收;只有全部原门槛通过且明确使用 `--publish-offline` 时才更新发布指针。目前没有新协议完整实机会话,不能当作实机验收通过。
## 核对出的模型差异
| 项目 | O30 | G20 / L6 / O6 / O12 |
| --- | --- | --- |
| 正式运动输入 | 发送的指令值 | 实际反馈值 |
| 指令采集 | 与运动图像交织 | 单独稳态扫描 |
| 运动训练 / 验证轮 | 0、1 / 3 | 0、1、2 / 3 |
| 指令训练 / 验证轮 | 0、1 / 3 | 4 / 5 |
| 最终报告 | 指令映射,反馈作诊断 | 反馈映射和指令映射均需验收 |
因此仅把 O30 的 `raw_joint_2_plus_1` 开关给其他型号,会用指令值解释反馈运动,且把 4、5 轮漏出 O30 拟合器。这样的结果不能用于发布。试验开关已撤回,未改动普通型号的正式 Profile 或产品配置哈希。
## 本次实际代码改动
新增 `runtime/feedback_image_dataset.py`、`runtime/feedback_image_candidates.py` 和只读命令 `analyze_feedback_images`:
1. 从已有 `image_observation_frame` 读取原始标签角点、相机内参、指令和反馈;不读取在线的 `joint_sample`、`joint_zero_reference` 或某个已选姿态。
2. 根据当次 `capture_plan`,将参考位图像、反馈运动训练图像、反馈运动验证图像、指令训练图像、指令验证图像分成五组。
3. 拒绝重复图像身份、未知任务、错误轮次、标签尺寸或 ID 不匹配、无效相机矩阵;保留尚未同步到反馈的原始帧,供离线判断缺项,不能因此丢掉整场采集。
4. 输出内容哈希,后续离线求解与验收必须绑定同一份不可变图像证据。
5. 对每张图像离线计算 IPPE 的全部正深度姿态候选和误差;目前不选择分支,也不授权关节零位。
可用 `analyze_feedback_images o6_right_8 <会话/raw_samples.jsonl>` 查看五类图像各有多少帧、多少标签有 0/1/2 个候选;命令不会启动拟合或发布。此处只建立离线求解输入,不产生零位或可发布 URDF。四个型号的分区、验证轮隔离、重复帧拒绝、在线姿态样本独立性和缺反馈帧保留,共 16 项分区测试通过;另有 1 项投影图像测试证明离线阶段同时保留两个姿态候选,且验证轮独立。
## 初次评估时列出的后续工作
1. 在现有原始图像上实现**反馈值驱动**的离线姿态与运动几何求解。保留每帧两个 IPPE 候选,用跨帧运动、父子标签关系和 URDF 几何联合判断;不能只选重投影误差较小的那个。
2. 离线重建每个关节的拍照参考位和反馈运动曲线,再用独立的第 4 轮验证;第 5 轮只验证指令映射,不参与训练。
3. 生成现有 v3 报告要求的 `feedback_to_rad` 与 `command_to_rad`,并保留已知几何、CAD 假设、转移关节等各型号原有规则。
4. 用同一批真实原始图像与当前程序结果比较,再做“两解都可用、只有一解、两解都不可用”的退化回放。之后才可逐型号切换现场到纯原始图像协议。
现有 O6 测试夹具仅包含运动分支观测摘要,不含完整图像角点和同步的指令、反馈,无法作为上述精度验收的真实会话。当前 G20/L6 产品配置还缺外参路径,O12 产品配置的 SDK 包哈希检查不通过;这些必须在实机联调前解决,不能虚构外参或绕过哈希。
工作区外找到的 `/home/lxqs/下载/raw_samples.jsonl` 仅含 `sample` 行,没有本工程的 `session_start` 或标签角点,不能用作本协议的真实验收数据。
## 前一轮“一次走完”采集改动
普通型号遇到明确的零位图像几何歧义时,在任务尚未正式扫描的前提下,将该任务及依赖任务延后;同一任务最多回访一次。若仍无法确认,记录 `task_observation_state=unobservable`,继续其他独立任务。参考位发生变化、运动安全故障、诊断模式和验证轮失败不走此延期通道。
单方向扫描因有效图像不足,同速安全补采一次后若仍不足,记录在 `incomplete_units`,继续其他任务。结束时先执行原有安全归位,再写包含未完成任务的封存清单。清单的 `raw_capture_complete` 为 `false`,启动器返回非零;离线入口拒绝正式拟合与发布。这保证“现场流程尽量走完”不会被误写成“标定通过”。
定向验证包括四型号扫描缺项继续、O6 真实协调器内存端口中的零位歧义延期、未完成任务归位封存以及 O30 原协议回归。这一轮仅改原有在线采集模式;后面新增的可选 `raw_feedback_3_plus_1` 模式才关闭在线运动标签求解。
## 继续实施:离线参考运动双解入口
新增 `runtime/feedback_image_motion.py`,并给 `analyze_feedback_images` 增加 `--joint` 参数。示例:
```bash
analyze_feedback_images o6_right_8 <会话/raw_samples.jsonl> --joint rh_thumb_cmc_yaw
analyze_feedback_images o6_right_8 <会话/raw_samples.jsonl> --coverage
```
它从第一轮、该关节对应的零位前运动图像重建求解器输入。固定父标签只提供相机对齐的坐标原点,不挑选它的 IPPE 正反面;运动标签的有效姿态候选全部保留,再调用已有的整段图像转轴求解器。固定基准角点漂移、相机内参变化、跨会话轮次混用会被拒绝。第三轮运动验证图像和第 4、5 轮指令图像不会进入这段准备运动求解。
这个命令**只出诊断报告**,字段明确写着 `joint_zero_authorized=false`、`publication_allowed=false`。目前只支持父标签固定在夹具上的关节。父标签也会运动的关节,需要把上游关节已经离线验收的几何模型串起来;然后还要重建反馈角度曲线、指令曲线、两个独立验证轮,并接入正式报告和发布门限。这些步骤未完成前,新模式只能封存原始采集数据,不能交付可发布的标定结果。
测试用合成图像验证:30 张准备运动图像各保留两套运动标签候选,验证轮不混入;当两套均无法通过原有门限时,求解器拒绝授权。现阶段没有完整的普通型号真实 `raw_samples.jsonl`,无法报告实机精度或成功率。已有的 `/home/lxqs/下载/raw_samples.jsonl` 缺少本协议的标签角点,不可用于此验收。
还新增 `runtime/feedback_image_coverage.py`:离线只看原始角点是否同时看见父子标签,以及指令、反馈是否在原有 50 ms 同步窗口内,再用现有扫描质量门限计算覆盖率。它不会把角点覆盖误认成关节角,也不会允许覆盖率通过就发布。合成 O6 回放验证:同步图像计入,超过窗口的反馈图像不计入。
## 继续实施:普通型号纯原始图像采集与离线证据筛选
新增可选策略 `raw_feedback_3_plus_1`,适用于 G20、L6、O6、O12 的独立反馈 / 指令采集 Profile。启动时通过 `--training-policy raw_feedback_3_plus_1` 选择。每个型号仍使用自己的 Profile、运动路径、标签定义和质量门限;扫描身份与原先的 0、1、2 轮反馈训练、3 轮反馈验证、4 轮指令训练、5 轮指令验证完全一致。
现场先沿原先声明的零位前运动路径拍照,在零位命令处静止拍照,再执行六轮扫描。图像记录保存角点、内参、指令、反馈、同步误差、任务和轮次。运动标签不在线选 IPPE 姿态,也不在线生成 `joint_zero_reference`;采集覆盖率只数同步且可见父子标签的照片。每轮覆盖不足仍按原补采规则处理,所有任务结束后安全归位并封存。参考照片不足会列在 `raw_capture_manifest.json` 的 `incomplete_references` 中,`raw_capture_complete=false`,不允许发布。新模式暂不支持从中断点续采,因此启动器关闭该模式的 resume。
新增 `runtime/feedback_raw_evidence.py`。离线读取整份日志时,先核对当次采集计划,拒绝混入在线关节角/零位记录,检查每轮扫描及其补采顺序,并独立重算最后一次采集的图像覆盖率。只有合格的最终一次照片进入反馈训练、反馈验证、指令训练、指令验证四组;失败补采留下审计记录,但不进入拟合。零位前与零位静止照片进入第五组参考证据。`analyze_feedback_images` 会识别新协议并使用这个筛选结果,同时报告未完成单元和所选补采次数。普通旧协议的只读检查仍可使用。
整手 O6 虚拟协调器测试覆盖 36 个扫描单元、安全归位、五组图像、无在线零位、封存完整性、离线重算以及混入在线零位时拒绝。它证明控制流程和证据分组可运行,不证明 IPPE 解的正确率或拟合精度。现有离线参考弧命令仍只覆盖固定父标签关节;运动父标签、离线零位、反馈角度曲线、指令曲线、独立验证与正式 URDF 发布链路尚未接通。正式 `--offline-raw` 遇到此新协议会明确拒绝发布,防止旧拟合器误用。用户目前没有该协议的实机会话,精度和连续采集成功率需重构完成后实测。
## 继续实施:离线标签链与静止父标签
本轮发现先前的纯图像会话只封存固定标签角点的汇总值。离线图像模型还需要知道这个坐标从哪组照片建立,才能确认后续照片的基准没有移动。因此,`raw_feedback_3_plus_1` 在锁定阶段现在复用静止图像参考跟踪器,把每个视角的至少 10 张原始固定标签照片、相机内参和相机对齐坐标写进 `fixed_base_reference_locked.stationary_image_references`。这只固定坐标系,不在线选运动标签的 IPPE 分支,也不在线计算关节零位。
`feedback_image_motion.py` 会读取并校验这份参考来源。新协议缺少来源照片就报错;历史诊断日志仍可按原方式只读分析,不获得发布权。O6 整手虚拟会话已验证:三个视角都保存来源照片,离线参考弧绑定的照片早于运动照片。
新增 `runtime/feedback_image_graph.py`,按任务把同一视角的多个关节组成父子标签链,保留每个运动标签的所有合格 IPPE 候选,调用现有跨帧图像运动求解器。模型只从 0、1、2 轮反馈运动训练照片构建;第 3 轮反馈验证和第 4、5 轮指令照片不进模型。固定父标签使用锁定阶段的来源照片。父标签贴在上游手指时,使用该任务扫描前零位保持的前 10 张照片建立局部坐标,后续照片留给零位估计;如果扫描中父标签移动超过原有 1.5 px 图像门限,直接拒绝该任务模型。`analyze_feedback_images --task <任务名> --view <视角>` 提供只读诊断,不授权零位或发布。
O6 双关节整手虚拟日志以及 G20 双关节合成图像验证了标签链、静止父标签来源、训练/验证隔离和父标签漂移拒绝。**这里仅完成图像模型的输入和诊断入口**:零位保持照片的角度读取、反馈与指令两条曲线拟合、正式独立验证和 URDF 发布仍待接通。测试使用合成图像,不能代替实机会话精度验收。
## 继续实施:离线读取零位保持角度
新增 `runtime/feedback_image_zero.py`。任务图像模型固定后,才在先前拍下的零位保持照片上读取几何角度;这些照片不参与模型参数拟合。读取时保留每帧所有 IPPE 初始候选,要求至少达到原有最少照片数,并同时检查角度变化不超过 1°、反馈变化不超过原运动控制的稳定门限。结果保存图像模型哈希、来源图像哈希和全部照片时间戳,明确标记 `spatial_zero_authorized=false`。
G20 合成双关节图像验证了父标签贴在上游手指时的局部静止参考;父标签任一角点明显移动即拒绝任务。O6 实际投影的合成图像验证了冻结模型能从独立保持照片读出指定的 0.12 rad 角度,反馈抖动会被拒绝。相应的局部测试通过。当前仍未把这些几何角度转换成经过 CAD/URDF 空间约束验收的关节零位,也未完成反馈曲线和指令曲线、两轮正式验证及可发布 URDF;正式离线发布入口继续拒绝新协议。
## 继续实施:封存后接入反馈与指令拟合(2026-09-29)
这一步把离线图像求解的结果接到了工程已有的两条拟合程序,**仍未打开 URDF 发布**。新协议的正式 `--offline-raw` 入口先核对封存清单、原始采集来源、完整扫描单元以及每个任务的稳态采样计划;再按任务和视角求解图像模型。模型只使用反馈训练轮 0、1、2 的照片,并在这些照片内部留出独立帧比较 IPPE 候选。第 3 轮只验证反馈曲线,第 4 轮只训练指令曲线,第 5 轮只验证指令曲线。采集时不做这些拟合动作。
具体改动:
1. 稳态原始照片新增 `steady_training_nodes` 和 `sampling_plan_sha256`。离线入口重新计算采样计划并检查所有任务都有声明;缺失、哈希变化或照片不属于该计划时停止。这样离线指令拟合能知道实际采了哪些节点。
2. `feedback_image_graph.py` 除主视角外,按 Profile 声明加入跨视角观测;移动父标签使用任务开始前的静止来源照片。求解器保留每个 IPPE 候选族,继续使用原来的像素、几何不确定度和候选区分门限。
3. `feedback_image_zero.py` 从零位保持照片取相对旋转和反馈参考值;`feedback_image_observations.py` 从同一份冻结模型重建父子相对姿态、公共坐标姿态、指令、反馈、图像身份与来源哈希。单张无法可靠解释的照片记入拒绝列表,不拿在线姿态补洞。
4. `feedback_image_fit.py` 调用已有的反馈运动拟合器及第 3 轮验证,再调用已有的稳态指令拟合器及第 5 轮验证;两个调用分别只接收自己的轮次。`feedback_raw_fit.json` 记录各任务双解候选、被拒照片数、图像来源哈希和阶段结果。失败也会留下这个报告。
5. 反馈和指令曲线通过后,继续调用现有 URDF 空间零位求解器,使用同一批 0~3 轮原始图像重建观测,保留其原有 CAD 几何、训练与第 3 轮验证门限。`feedback_raw_fit.json` 会记录求出的直接零位及验收结果。空间零位通过后会在 `offline_draft/` 用现有 v3 写入器生成 JSON 和 URDF,核对来源 URDF、允许改动的字段,并用隔离的 ROS 解析器读回。独立最终图像验收和 `latest_passed` 发布链尚未接入新协议;即使草稿检查通过,正式入口仍明确拒绝发布,不能把诊断报告当作已完成标定。
软件核对:O6 虚拟整手采集验证了 36 个扫描单元、归位封存、五类原始图像和所有任务的采样计划;新增的隔离测试验证反馈拟合只接收 0/3 轮、指令拟合只接收 4/5 轮,跨视角零位缺一视角即拒绝,空间零位阶段仍只接收反馈运动 0~3 轮,缺采样计划在打开相机几何前拒绝。O6 理想投影合成照片的冻结模型可以读出约 0.12 rad 的零位保持角;但当前自动双解模型把这组正对相机的平面几何判为不确定。这里保留拒绝和各候选诊断,没有降低精度门限。虚拟和合成测试不能证明真实手的求解率、空间零位或 URDF 精度;需在首个完整实机会话中据 `feedback_raw_fit.json` 逐任务分析。
### 上一阶段发布接线暂缓的记录
当前没有一场 G20/L6/O6/O12 新协议的真实完整会话。自动审核拒绝了在这个前提下直接接通正式发布指针的改动;该改动没有落盘。在当时的阶段只生成 `offline_draft/` 候选文件,`publication_allowed` 为 `false`。用户随后明确要求继续更改;下节记录正式发布门槛的接线。
## 继续实施:正式最终文件验收接线(2026-09-29)
用户明确要求继续更改后,新增 `runtime/artifacts/feedback_raw_release.py`,把已封存原图离线拟合生成的 v3 JSON/URDF 草稿送入原有的 `FrozenTagArtifactValidator` 和 `ArtifactPublisher`。验证仍在离线进程中进行,不启动手部 SDK 或发送运动指令。
执行顺序:
```text
封存清单及受保护输入核对
→ 每任务采样计划、Profile 与源 URDF 几何核对
→ 训练照片双解模型、保持照片零位参考
→ 反馈曲线拟合(0/1/2 轮)、第 3 轮验证
→ 指令曲线拟合(第 4 轮)、第 5 轮验证
→ URDF 空间零位求解及第 3 轮验证
→ offline_draft/ 草稿 JSON/URDF、结构和 ROS 加载检查
→ 原有标签安装重放及第 3/5 轮原始角点最终文件验收
→ 全部通过后写 standard_urdf_acceptance.json
→ 仅显式 --publish-offline 才原子更新发布指针
```
最终验收使用从原始照片重建的训练/验证姿态和原始角点,独立重放最终 JSON/URDF。反馈第 3 轮和指令第 5 轮分别使用自己的 SDK 值;没有用第 5 轮调整反馈模型,也没有用第 3 轮调整指令模型。新协议的主视角原图现在也进入 `ImageEvidence`,不要求在线保存 PnP 姿态。发布器仍检查 JSON、URDF、报告文件哈希,失败时不写 `release_manifest.json`,也不更新指针。默认只验收不发布;显式 `--publish-offline` 才提交。
定向软件测试:最终门槛失败时不提交;两个独立图像分区均传入最终验收;一张实际构造的原始角点照片进入反馈验证;四种手型的原图 Profile 均能通过本包源 URDF 的发布几何前置检查。**这些是软件契约测试,不是整条求解链在实拍图像上通过。**首个完整会话仍需逐任务检查 `feedback_raw_fit.json`、`standard_urdf_acceptance.json` 与原始照片。先前正对相机的合成平面图像被双解模型判为几何不确定,仍会停止,不会因发布链接通而放宽门限。
现场配置限制尚在:G20/L6 当前产品配置指向缺失的 `g20_three_camera_extrinsics.yaml`;O12 产品配置的 SDK 包哈希不符。两者都会在离线入口加载产品配置时停止。O6 当前产品配置可加载。相关文件或哈希应按实际安装核对,不能用虚构外参或忽略 SDK 身份绕过。
### 四型号默认策略切换和离线命令
初次切换尝试被自动审核拒绝,原因是会改变普通启动的现场行为。用户随后明确批准 G20、L6、O6、O12 四型号默认切到 `raw_feedback_3_plus_1` 并同步产品配置哈希;现已完成。普通新会话不再需要 `--training-policy`。旧 `fixed` 会话应使用自己的封存配置回放;若明确需要重跑旧在线模式,可显式传 `--training-policy fixed`,新旧采集计划不得混用。
新会话离线验收用封存时的 `capture_product.yaml`:
```bash
calibrate_hand --config <会话目录>/capture_product.yaml \
--offline-raw <会话目录>/raw_samples.jsonl \
--offline-output <新的离线输出目录>
```
上述命令只验收,不更新发布指针。确实要发布已经通过全部验收的结果时,另加 `--publish-offline`。入口会比对封存清单和 `capture_plan`;计划不符或采集不完整即拒绝。
@@ -0,0 +1,58 @@
# 图像双候选求解:第一步重构记录
日期:2026-09-28。依据仓库根目录的 `URDF_IMAGE_SOLVE_HANDOFF.md` 对照实现。
## 这次改了什么
交接文档所说的“两套解法”是**同一平面标签的两个姿态候选**。当前程序已经用整段运动的角点做铰链拟合,并在留出的准备图像上比较候选;这部分不需要再造一套 PnP。真正不方便的是:终端只显示总失败原因,操作员要翻完整候选记录才能判断“都很好但分不清”“都对不上图像”,还是“有一套根本没算完”。
本轮把**求解结果的解释**从采集协调器中独立出来:
1. 新增 `core/geometry/tag_pose/image_solve_diagnosis.py`。它只读取已保存的 `motion_branch_initialization` 记录,不碰相机、机械手,也不重新选择姿态。每套候选保留分支编号、训练/留出图像误差、失败原因、求解状态和比较概率;同时带出进入拟合前被拒绝的观测计数。
2. 在线初始化写审计记录时,同步增加 `image_solve_diagnosis` 摘要。旧的总原因和完整 `hypotheses` 仍在原位置。
3. 新增只读命令 `analyze_image_solve`。给它一个会话的 `raw_samples.jsonl`,可从旧记录重新生成同样的摘要。已有诊断汇总也会显示这个摘要。
4. 终端提示把“所有候选都不合格”和“备选候选没算完”分成两个独立代号,不再都落到笼统的零位分支提示。
5. 对应增加针对性测试:两套都像、两套都不合格、另一套求解未完成,以及四种操作员提示。测试确认未完成的候选不能被报告成已排除。
## 输出怎么读
| `category` | 大白话 | 下一步先看什么 |
| --- | --- | --- |
| `multiple_plausible_poses` | 至少两套姿态仍说得通 | 看各候选比较结果和已拍姿态的差异;同一小段重复拍摄未必有帮助 |
| `no_acceptable_model` | 没有一套通过当前图像模型检查 | 看各候选的 `reason`,以及哪个标签的训练/留出像素误差高 |
| `alternative_not_evaluated` | 有备选姿态还没得到可比较的结果 | 看该候选的求解状态,不能把它当成错误姿态 |
| `solver_incomplete` | 计算预算或时限用完 | 先离线排查计算,不能说已经证明没有解 |
| `insufficient_or_missing_evidence` | 没有足够的有效候选记录 | 查原始图像、标签和基准是否齐全 |
`accepted_training_candidate_count` 只表示通过训练阶段的局部检查;`accuracy_validated` 始终为 `false`。它们**不表示 URDF 已验收**。
## 使用方法
安装标定包后运行:
```bash
ros2 run linkerhand_calibration analyze_image_solve \
/path/to/session/raw_samples.jsonl
```
或者在源码环境运行:
```bash
PYTHONPATH=src/linkerhand_calibration python3 -m \
linkerhand_calibration.tools.image_solve_report \
/path/to/session/raw_samples.jsonl
```
输出是 JSON 数组,每条对应一次零位准备求解。这个命令只读日志。O30 当前默认的 `raw_joint_2_plus_1` 是先采原始角点、再离线拟合,通常不会产生交接文档所述的在线零位初始化记录;因此默认原始采集会话输出空数组是预期行为。该命令主要用于历史在线几何会话及显式在线策略。
## 算法与安全边界
这次优化的是**把失败分型和候选证据变得可见、可复盘**,不是声称消除了平面标签双解。`SOLVEPNP_IPPE_SQUARE`、整段铰链拟合、训练选赢家、留出图像区分候选,以及 1.5 px / 0.03 px / Holm 0.01 等现有门限未改。在线零位未确定时依然暂停,避免用不可靠角度继续采指令曲线。O30 默认原始采集与离线拟合原有分离流程也未改变。
更进一步的算法优化需要基于封存会话逐关节比较:哪些姿态能把两套预测拉开、哪些误差只是个别坏帧、哪些随角度系统性增长。当前工作区没有可用的完整原始会话,因此本轮没有根据合成数据去调整正式选解算法或降低验收门限。
## 验证
- 新增的诊断用例中,双候选、无可用候选、备选未完成和终端分类均通过;记录写入、JSONL 只读回放和既有诊断汇总得到一致结果。
- Python 模块与安装入口已做静态检查;未驱动实机,也未发布 URDF。
- 前一轮补齐的三台相机内参可读取,O30 相关分批测试共 43 项通过;这验证了原有路径没有因目录整理失效,不代表本轮新诊断已经在真实失败会话上验证。
@@ -0,0 +1,3 @@
# 共用记录
此处保存跨型号的实施与稳定性记录。O30 专属操作说明和故障记录见 [O30 文档](../linkerhand_calibration/models/o30/docs/README.md)。
@@ -0,0 +1,92 @@
# 固定 Tag 的分阶段标定实施记录
默认 `fixed` 保留。新策略通过 `--training-policy staged_2_to_3` 显式启用;当前满足其
“实测指令发布、完整交错网格”能力约束的内置配置为 O30。通用实现不按手型号或相机名称分支。
本次没有启动硬件、修改 Tag/相机配置或更新已发布产物。
## 执行和证据
- `capture_plan_v2` 描述各阶段、原任务顺序及实际训练轮。引擎按轮次排列现有扫描单元,
继续使用原基准、避让、进入/退出路径。首轮数据直接用于正式训练。
- 两轮全手数据齐全后检查曲线重复性、空间几何、零位置信度和 Tag 安装。训练问题使用
参数、原因、范围和任务依赖描述;局部零位缺陷补齐同轮依赖,共享根部几何缺陷扩大到全手。
- 第三轮只允许一个集中补采批次,轮次固定为 2。仍不合格即失败。独立验证始终是轮次 3。
- 每次回访保存新零位复核记录,原零位、安装模型与证据 ID 不被替换。新/旧分支编号均有
独立授权,历史扫描不会被后来一次复核覆盖。训练不足、持续姿态歧义和参考变化不靠重复验证解决。
- 上游准备阶段按物理 Tag 关系保存旁观角点、候选及原指令/反馈身份,沿用有界运动分箱。
末节保持基准指令和反馈稳定才可采用。候选使用固定时间划分、原像素门限、角度分层的独立
误差比较及 Holm 控制;不能用最低误差强选不可区分的候选。
- 相对位姿估计传播同图父 Tag 的像素不确定度,并保守累加父模型几何不确定度;后续末节
准备仍通过原运动、图像、可观测性和候选区分门限。回读核对模型身份、原始角点、固定取样、
保持通道和测量结果。短暂内部恢复仅沿既有带日志的参考延续规则复用来源。
旁观证据与已有共享 Tag 桥接并存时,策略标识同时保留两者的来源和约束方式。
## 计算和冻结
训练工作进程在会话内复用。传输、计算和返回均受同一超时/取消约束。任务索引缓存已选
训练快照,增补只使受影响任务的局部模型失效,随后重算全局空间解。
`staged_training_decision` 记录输入与计划哈希、结构化问题、实际独立轮数、置信区间和
增补/冻结/失败决定。`frozen_training.json` 使用显式 JSON 数值类型,包含双向映射、空间解、
实际应用零偏、统计、掌部姿态和 Tag 安装;绑定完整配置、源 URDF、训练记录、零位和求解版本。
修改求解语义时必须升级求解版本,不能用缓存替代证据。
在线最终验收加载已冻结结果,不再次运行曲线和空间训练优化。产物顺序仍为:独立角度验证、
写 JSON、从落盘 JSON 重建 URDF、文件/限位/方向/通道/单位/像素检查、成对发布。
离线审计复算训练决定并比对冻结结果。模型或证据改变时拒绝发布。五个末节绝对零位仍为
明确的 CAD 假设,精度声明限于经过独立验证的运动范围和姿态。
## 断点和恢复
新旧计划不得混用。旧策略保持原恢复语义。新策略仅复用连续完整任务访问;部分方向不算
访问完成。固定参考通过后,先导入原模型和原零位,再逐次复核当前零位,最后才跳过原访问。
集中补采与冻结决定按日志顺序恢复;已冻结而缺失原训练前缀或冻结文件时拒绝回退训练。
恢复父模型时一并恢复其已绑定的有界旁观原始帧,缺失角点不补造;当前零位仍须重新复核。
扫描时间必须晚于所绑定访问的零位复核;导入历史扫描保留当时的复核证据,不能伪造新采集时间。
准备缺样额度与同速重扫额度跨断点保留;已经耗尽的恢复不能通过重新加载断点获得新额度。
## 验证与局限
### 共享 Tag 改变进入姿态时的联合准备(2026-09-20)
拇指 CMC roll 与 MCP 使用同一个 Tag,但两任务间 yaw 基准不同,不能直接把前一个零位
当作 MCP 零位。本次保留既有 yaw 进入动作,把其原始图像与 MCP 自身准备图像联合求解:
前端绑定已经实测的 roll 零位,后端用保持指令及稳定反馈确认与 MCP 的共同姿态。
SDK 指令只标识动作和保持状态,不充当相机测得的角度。没有新增运动或修改 Tag、速度、路径。
采样分箱及训练/留出划分事先固定,完整枚举两段动作的候选组合;训练决定模型,留出只可
否决。维持原像素、几何不确定度和候选区分门限。目标几何的不确定度计算恢复全部自由度,
避免把固定来源零位误当作额外精度。辅助进入数据缺失时,在拟合前记录原因并使用原准备入口;
进入数据违反参考/安装/保持通道约束,或联合拟合及留出失败时,不能退回另一种求解碰运气。
`preparation_transition_v1` 绑定来源零位、来源模型、实际运动依赖、完整原始帧哈希和固定
选样身份。日志回读重新核对源 URDF 依赖、来源零位图像,并复算联合模型、核对冻结模型哈希。
取消和跨会话会清除未完成的进入证据。该机制沿用现有准备工作进程及状态机,普通冻结图像模型
和最终 JSON→URDF 发布契约不变。
真实会话 `20260920_125306` 的 MCP 原始图像经运行时采集入口回放后通过:原方法仍因候选
不可区分而拒绝;联合模型的最大训练/留出帧 RMS 分别约 1.117/1.083 px(原门限 1.5 px)。
四个初始化组合中两个收敛到等价几何,另两个违反原像素门限。原中指 DIP 不充分证据回归仍拒绝。
这证明该次 MCP 停点的软件问题得到改善,不代表整手物理精度、总耗时或一次连续通过已经验收。
本次优化未启动硬件,也未生成或发布新的整手 JSON/URDF;默认策略继续为 `fixed`。
软件验证与原始回放报告保存在
`calibration_output/O30_RIGHT_001/software_review_preparation_transition/`。
测试按快速单元、回放、产物集成、历史兼容分层;命令见 `../TESTING.md`。整手输入和产物由
共享夹具提供,篡改、缺字段、取消等直接进入对应拒绝边界。修正了一个拿不完整采集数据
调用最终化、却期待后置运动证据错误的旧用例,改为直接检验其负责的运动验收边界。
已覆盖:两轮冻结、一次局部/全手补采、补采失败、真实依赖的混合轮数、冻结后不再训练、
留出隔离、回访复核、有界恢复、完整访问恢复、模型篡改拒绝、取消发布和 O30 JSON→URDF 一致性。
真实中指 DIP 旧数据缺少旁观证据时仍拒绝。新增合成独立证据能区分候选时才通过。
各次测试的源码指纹、耗时、失败及修复后复查关系保存于工作区
`calibration_output/O30_RIGHT_001/software_review_staged_training/software_validation.json`。
O30 产物集成使用原正式采集证据入口及独立 FK 合成图像,复用兼容的几何运动授权。
它覆盖文件链路与证据契约;在线图像准备算法另由原真实 DIP 回放和新增旁观图像用例检查。
该合成产物用例不是整手实机图像模型选择、连续运动或物理精度证明。
实机工作仍需在全新会话完成:所有尝试均计入,比较总耗时、完整通过、人工干预和失败原因。
记录开始到终态、准备、稳定等待、采样、恢复、训练、文件验收及开始前断点加载开销;比较时
不能漏掉加载开销或只比较扫描时间。达到正确性门限、人工干预未增加且总耗时改善至少 10%
才考虑切换默认。大日志存储/全量解码重构未与本次采集规则一起进行。
@@ -0,0 +1,21 @@
"""One-release compatibility surface for the former Python package name.
New code must import :mod:`linkerhand_calibration`. Only the documented
configuration loader is re-exported here; calibration algorithms continue to
have a single implementation in the renamed package.
"""
from __future__ import annotations
import warnings
warnings.warn(
"g20_thumb_apriltag_calibration is deprecated; "
"import linkerhand_calibration instead",
DeprecationWarning,
stacklevel=2,
)
from linkerhand_calibration.product import ProductConfig, load_product_config
__all__ = ["ProductConfig", "load_product_config"]
@@ -0,0 +1,9 @@
"""Deprecated forwarding entry point for the runtime joint-state bridge."""
from linkerhand_calibration.calibrated_joint_state_bridge import main
__all__ = ["main"]
if __name__ == "__main__":
main()
@@ -0,0 +1,9 @@
"""Deprecated forwarding entry point for offline replay."""
from linkerhand_calibration.offline_replay import main
__all__ = ["main"]
if __name__ == "__main__":
main()
@@ -0,0 +1,9 @@
"""Deprecated forwarding entry point for the former Python package."""
from linkerhand_calibration.one_command import main
__all__ = ["main"]
if __name__ == "__main__":
main()
@@ -0,0 +1,37 @@
"""Publish profile-calibrated URDF angles from raw command/feedback u8 values."""
from launch import LaunchDescription
from launch.actions import DeclareLaunchArgument
from launch.substitutions import LaunchConfiguration
from launch_ros.actions import Node
def generate_launch_description() -> LaunchDescription:
return LaunchDescription(
[
DeclareLaunchArgument("hand_type", default_value="right"),
DeclareLaunchArgument("calibration_file"),
DeclareLaunchArgument("input_topic", default_value=""),
DeclareLaunchArgument("output_topic", default_value=""),
Node(
package="linkerhand_calibration",
executable="calibrated_joint_state_bridge",
name=[
"calibrated_joint_state_bridge_",
LaunchConfiguration("hand_type"),
],
output="screen",
emulate_tty=True,
parameters=[
{
"hand_type": LaunchConfiguration("hand_type"),
"calibration_file": LaunchConfiguration(
"calibration_file"
),
"input_topic": LaunchConfiguration("input_topic"),
"output_topic": LaunchConfiguration("output_topic"),
}
],
),
]
)
@@ -0,0 +1,487 @@
"""Launch Profile-declared Hikrobot views and one calibration owner."""
from __future__ import annotations
from datetime import datetime
import hashlib
from pathlib import Path
import re
from ament_index_python.packages import get_package_share_directory
from launch import LaunchDescription
from launch.actions import (
DeclareLaunchArgument,
ExecuteProcess,
LogInfo,
OpaqueFunction,
SetEnvironmentVariable,
)
from launch.conditions import IfCondition
from launch.substitutions import LaunchConfiguration
from launch_ros.actions import ComposableNodeContainer, Node
from launch_ros.descriptions import ComposableNode
from launch_ros.parameter_descriptions import ParameterValue
def _launch_stack(context):
from linkerhand_calibration.product import (
ProductCalibrationContract,
)
from linkerhand_calibration.profiles import load_hand_profile
from linkerhand_calibration.runtime.adapters.ros_topics import sdk_topics
from linkerhand_calibration.runtime.diagnostic_capture import resolve_diagnostic_capture
from linkerhand_calibration.runtime.observation_scope import required_observation_views
model = LaunchConfiguration("model").perform(context).strip().upper()
hand_type = LaunchConfiguration("hand_type").perform(context).lower()
if hand_type not in {"left", "right"}:
raise RuntimeError("hand_type must be left or right")
tag_layout = LaunchConfiguration("tag_layout").perform(context).lower()
try:
profile_path = LaunchConfiguration("profile_config").perform(context).strip()
if not profile_path:
raise ValueError("online calibration requires a protected YAML Profile; use calibrate_hand --config")
expected = LaunchConfiguration("profile_config_expected_sha256").perform(context).strip()
if not expected or hashlib.sha256(Path(profile_path).read_bytes()).hexdigest() != expected:
raise ValueError("Profile changed between product validation and launch")
contract = ProductCalibrationContract(declarative=load_hand_profile(profile_path))
key = contract.typed_profile.key
if (key.model, key.side, key.layout) != (model, hand_type, tag_layout):
raise ValueError("launch identity differs from the protected Profile")
except ValueError as error:
raise RuntimeError(str(error)) from error
diagnostic = resolve_diagnostic_capture(
contract.typed_profile,
LaunchConfiguration("diagnostic_capture").perform(context).strip(),
)
views = required_observation_views(contract.typed_profile, diagnostic)
requested_tag_config = LaunchConfiguration("tag_config").perform(context)
if not requested_tag_config:
raise RuntimeError("tag_config is required; use calibrate_hand --config")
tag_config = Path(requested_tag_config).expanduser().resolve()
if not tag_config.is_file():
raise RuntimeError(f"tag config does not exist: {tag_config}")
topic_prefix = f"/{model.lower()}"
uses_hcan = contract.typed_profile.sdk_adapter == "o12_hcan_sdk"
if contract.typed_profile.sdk_adapter not in {"legacy_byte_sdk", "o12_hcan_sdk", "o30_ros"}:
raise RuntimeError("SDK adapter has no ROS launch binding")
topics = sdk_topics(contract.typed_profile)
command_topic, state_topic = topics.command, topics.feedback
requested_source = LaunchConfiguration("source_urdf_path").perform(context)
if not requested_source:
raise RuntimeError("source_urdf_path is required; use calibrate_hand --config")
source_urdf = Path(requested_source).expanduser().resolve()
if not source_urdf.is_file():
raise RuntimeError(f"source URDF does not exist: {source_urdf}")
expected_source_hash = LaunchConfiguration(
"source_urdf_expected_sha256"
).perform(context).strip().lower()
if contract.typed_profile.artifacts.publish_corrected_urdf:
if re.fullmatch(r"[0-9a-f]{64}", expected_source_hash) is None:
raise RuntimeError(
"this profile requires source_urdf_expected_sha256 confirmed "
"by the CAD/hardware owner"
)
actual_source_hash = hashlib.sha256(source_urdf.read_bytes()).hexdigest()
if actual_source_hash != expected_source_hash:
raise RuntimeError(
"source_urdf_expected_sha256 does not match source_urdf_path"
)
hand_serial = LaunchConfiguration("serial_number").perform(context)
if (
not hand_serial
or hand_serial == "UNSET"
or re.fullmatch(r"[A-Za-z0-9_.-]+", hand_serial) is None
or hand_serial in {".", ".."}
):
raise RuntimeError("serial_number must be a safe non-empty hand serial")
requested_session = LaunchConfiguration("session_dir").perform(context)
output_root = Path(
LaunchConfiguration("output_root").perform(context)
).expanduser().resolve()
if requested_session:
session_dir = Path(requested_session).expanduser().resolve()
else:
session_dir = (
output_root
/ hand_serial
/ datetime.now().strftime("%Y%m%d_%H%M%S")
)
session_dir.mkdir(parents=True, exist_ok=True)
camera_serials = {
view: LaunchConfiguration(f"{view}_camera_serial").perform(context)
for view in views
}
if any(not serial for serial in camera_serials.values()):
raise RuntimeError("all required observation camera serial numbers are required")
if len(set(camera_serials.values())) != len(views):
raise RuntimeError("required observation camera serial numbers must be unique")
cameras = []
components = []
raw_topics = []
info_topics = []
detection_topics = []
calibration_namespace = contract.typed_profile.namespace
for view in views:
namespace = f"{calibration_namespace}/{view}/camera"
raw_topic = f"{namespace}/image_raw"
info_topic = f"{namespace}/camera_info"
rect_topic = f"{namespace}/image_rect"
detector_namespace = f"{calibration_namespace}/{view}/apriltag"
detection_topic = f"{detector_namespace}/detections"
raw_topics.append(raw_topic)
info_topics.append(info_topic)
detection_topics.append(detection_topic)
cameras.append(
Node(
package="linkerhand_calibration",
executable="hikrobot_camera_node",
name="hikrobot_camera",
namespace=namespace,
output="screen",
emulate_tty=True,
condition=IfCondition(LaunchConfiguration("start_cameras")),
parameters=[
{
"serial_number": LaunchConfiguration(
f"{view}_camera_serial"
),
"expected_model": LaunchConfiguration("camera_model"),
"camera_name": LaunchConfiguration(
f"{view}_camera_name"
),
"frame_id": (
f"{model.lower()}_calibration_{view}_optical_frame"
),
"image_width": 1624,
"image_height": 1240,
"timestamp_journal_path": str(Path(LaunchConfiguration("session_dir").perform(context))
/ f"camera_timing_{view}.jsonl"),
"frame_rate": ParameterValue(
LaunchConfiguration("camera_frame_rate"),
value_type=float,
),
"exposure_time_us": ParameterValue(
LaunchConfiguration("exposure_time_us"),
value_type=float,
),
"gain_db": ParameterValue(
LaunchConfiguration(f"{view}_camera_gain_db"), value_type=float
),
"auto_exposure": ParameterValue(
LaunchConfiguration("auto_exposure"), value_type=bool
),
"camera_info_url": LaunchConfiguration(
f"{view}_camera_info_url"
),
}
],
)
)
components.extend(
[
ComposableNode(
package="image_proc",
plugin="image_proc::RectifyNode",
name=f"rectify_{view}",
namespace=namespace,
remappings=[
("image", raw_topic),
("camera_info", info_topic),
("image_rect", rect_topic),
],
parameters=[{"queue_size": 1}],
extra_arguments=[{"use_intra_process_comms": True}],
),
ComposableNode(
package="apriltag_ros",
plugin="AprilTagNode",
name="apriltag",
namespace=detector_namespace,
# Detector settings belong to the protected model YAML.
# A generic launch default must not silently replace its
# full-resolution setting for the small calibration Tags.
parameters=[str(tag_config)],
remappings=[
("image_rect", rect_topic),
("camera_info", info_topic),
],
extra_arguments=[{"use_intra_process_comms": True}],
),
]
)
vision = ComposableNodeContainer(
name=f"{model.lower()}_calibration_vision",
namespace="/",
package="rclcpp_components",
executable="component_container_mt",
composable_node_descriptions=components,
output="screen",
emulate_tty=True,
)
sdk = (
Node(
package="linkerhand_calibration",
executable="o12_sdk_bridge",
name="o12_sdk_bridge",
output="screen",
condition=IfCondition(LaunchConfiguration("start_sdk")),
parameters=[{
"vendor_config": LaunchConfiguration("vendor_sdk_config"),
"vendor_config_sha256": LaunchConfiguration("sdk_config_expected_sha256"),
"vendor_python_package": LaunchConfiguration("vendor_sdk_python_package"),
"vendor_package_sha256": LaunchConfiguration("sdk_package_expected_sha256"),
"hand_type": hand_type,
"topic_prefix": f"/{model.lower()}/{hand_type}",
}],
)
if uses_hcan
else Node(
package="linker_hand_ros2_sdk",
executable="linker_hand_sdk",
name="linker_hand_sdk",
output="screen",
condition=IfCondition(LaunchConfiguration("start_sdk")),
parameters=[{
"hand_type": hand_type,
"hand_joint": model,
"can": LaunchConfiguration("can_interface"),
"modbus": "None",
"topic_prefix": topic_prefix,
"move_on_startup": False,
"startup_speed": ParameterValue(
LaunchConfiguration("calibration_speed"), value_type=int
),
"startup_torque": 80,
# Match 30 Hz cameras so state/image p95 skew stays below 50 ms.
"state_poll_rate": 30.0,
# Calibration does not consume measured joint velocity. A
# G20 velocity read sends another five synchronous CAN
# queries, so keep it off the trajectory-critical path.
"velocity_poll_rate": 1.0,
# G20 sends an endpoint and L6 streams a bounded trajectory.
# Keep polling the real motor state during either command path;
# otherwise the SDK republishes stale state and creates large
# command-unit holes in the trajectory bins.
"defer_state_reads_while_commanding": False,
"repeat_position_commands": False,
"is_touch": False,
}],
)
)
if contract.typed_profile.sdk_adapter == "o30_ros":
from linkerhand_calibration.runtime.adapters.o30_ros import launch_parameters
sdk = Node(package="linker_hand_o30_ros2_sdk", executable="linker_hand_o30_ros2_sdk",
name="linker_hand_o30_sdk", output="screen",
condition=IfCondition(LaunchConfiguration("start_sdk")),
parameters=[launch_parameters(side=hand_type)])
calibration = Node(
package="linkerhand_calibration",
executable="three_camera_calibration_node",
name=f"{model.lower()}_calibration",
output="screen",
emulate_tty=True,
arguments=[
"--profile-id",
contract.typed_profile.key.profile_id,
"--profile-config", profile_path, "--profile-sha256", expected,
],
parameters=[
LaunchConfiguration("calibration_config"),
{
"serial_number": hand_serial,
"session_dir": str(session_dir),
"resume_raw_samples_path": LaunchConfiguration(
"resume_raw_samples_path"
),
"resume_mode": LaunchConfiguration("resume_mode"),
"training_policy": LaunchConfiguration("training_policy"),
"preparation_witnesses_json": ParameterValue(
LaunchConfiguration("preparation_witnesses_json"), value_type=str),
"capture_plan_expected_sha256": ParameterValue(
LaunchConfiguration("capture_plan_expected_sha256"), value_type=str),
"initial_command_file": LaunchConfiguration("initial_command_file"),
"reuse_camera_calibration": ParameterValue(LaunchConfiguration("reuse_camera_calibration"), value_type=bool),
"camera_optical_observations_file": LaunchConfiguration("camera_optical_observations_file"),
"command_topic": command_topic,
"state_topic": state_topic,
**({"setting_topic": topics.setting} if topics.setting else {}),
"camera_extrinsics_file": LaunchConfiguration(
"camera_extrinsics_file"
),
"source_urdf_path": str(source_urdf),
"source_urdf_expected_sha256": LaunchConfiguration(
"source_urdf_expected_sha256"
),
"camera_extrinsics_expected_sha256": LaunchConfiguration(
"camera_extrinsics_expected_sha256"
),
"calibration_config_expected_sha256": LaunchConfiguration(
"calibration_config_expected_sha256"
),
"tag_config_expected_sha256": LaunchConfiguration(
"tag_config_expected_sha256"
),
"sdk_config_expected_sha256": LaunchConfiguration(
"sdk_config_expected_sha256"
),
"sdk_package_expected_sha256": LaunchConfiguration("sdk_package_expected_sha256"),
"profile_config_expected_sha256": LaunchConfiguration(
"profile_config_expected_sha256"
),
"commands_enabled": ParameterValue(
LaunchConfiguration("commands_enabled"), value_type=bool
),
"diagnostic_capture": ParameterValue(
LaunchConfiguration("diagnostic_capture"), value_type=str
),
},
],
)
bag = ExecuteProcess(
condition=IfCondition(LaunchConfiguration("record_bag")),
cmd=[
"ros2",
"bag",
"record",
"--storage",
"mcap",
"--storage-preset-profile",
"zstd_fast",
"--max-bag-size",
"10737418240",
"--output",
str(session_dir / "rosbag"),
*raw_topics,
*info_topics,
*detection_topics,
command_topic,
state_topic,
*(
[
f"/{model.lower()}/{hand_type}/calibration_health",
]
if uses_hcan else []
),
f"{calibration_namespace}/status",
],
output="screen",
)
return [
LogInfo(
msg=(
f"{model} {hand_type} {tag_layout} calibration session: {session_dir}; "
f"source_urdf={source_urdf}"
)
),
LogInfo(
msg=(
"Camera mapping: " + " ".join(f"{view}={serial}" for view, serial in camera_serials.items())
)
),
*cameras,
vision,
Node(package="linkerhand_calibration", executable="tag_border_filter_node",
name="tag_border_filter", output="screen",
arguments=["--profile-config", profile_path, "--profile-sha256", expected,
"--views", *views]),
sdk,
calibration,
bag,
]
def generate_launch_description() -> LaunchDescription:
package_share = Path(
get_package_share_directory("linkerhand_calibration")
)
return LaunchDescription(
[
# Camera processes publish ~2 MB frames across DDS. Force the
# matching RMW and provide both current and legacy profile names
# so the configured 64 MB shared-memory segment is actually used.
SetEnvironmentVariable(
name="RMW_IMPLEMENTATION",
value="rmw_fastrtps_cpp",
),
SetEnvironmentVariable(
name="FASTDDS_DEFAULT_PROFILES_FILE",
value=str(package_share / "config" / "fastdds_large_images.xml"),
),
SetEnvironmentVariable(
name="FASTRTPS_DEFAULT_PROFILES_FILE",
value=str(package_share / "config" / "fastdds_large_images.xml"),
),
DeclareLaunchArgument("model", default_value=""),
DeclareLaunchArgument("hand_type", default_value=""),
DeclareLaunchArgument("tag_layout", default_value=""),
DeclareLaunchArgument("serial_number", default_value="UNSET"),
DeclareLaunchArgument("camera_model", default_value="MV-CS020-10U"),
DeclareLaunchArgument("camera_frame_rate", default_value="30.0"),
DeclareLaunchArgument("exposure_time_us", default_value="5000.0"),
DeclareLaunchArgument("gain_db", default_value="0.0"),
*[DeclareLaunchArgument(f"{view}_camera_gain_db",
default_value=LaunchConfiguration("gain_db")) for view in ("front", "side", "top")],
DeclareLaunchArgument("auto_exposure", default_value="false"),
DeclareLaunchArgument("can_interface", default_value="can0"),
DeclareLaunchArgument("calibration_speed", default_value="15"),
DeclareLaunchArgument("camera_extrinsics_file", default_value=""),
DeclareLaunchArgument(
"source_urdf_path", default_value=""
),
DeclareLaunchArgument(
"source_urdf_expected_sha256", default_value=""
),
DeclareLaunchArgument(
"camera_extrinsics_expected_sha256", default_value=""
),
DeclareLaunchArgument(
"calibration_config_expected_sha256", default_value=""
),
DeclareLaunchArgument(
"tag_config_expected_sha256", default_value=""
),
DeclareLaunchArgument("vendor_sdk_config", default_value=""),
DeclareLaunchArgument("vendor_sdk_python_package", default_value=""),
DeclareLaunchArgument("sdk_package_expected_sha256", default_value=""),
DeclareLaunchArgument(
"sdk_config_expected_sha256", default_value=""
),
DeclareLaunchArgument(
"profile_config_expected_sha256", default_value=""
),
DeclareLaunchArgument("profile_config", default_value=""),
DeclareLaunchArgument("commands_enabled", default_value="true"),
DeclareLaunchArgument("diagnostic_capture", default_value=""),
DeclareLaunchArgument("start_cameras", default_value="true"),
DeclareLaunchArgument("start_sdk", default_value="true"),
DeclareLaunchArgument("record_bag", default_value="false"),
DeclareLaunchArgument(
"output_root",
default_value=str(Path.cwd() / "calibration_output"),
),
DeclareLaunchArgument("session_dir", default_value=""),
DeclareLaunchArgument("resume_raw_samples_path", default_value=""),
DeclareLaunchArgument("resume_mode", default_value="verify"),
DeclareLaunchArgument("training_policy", default_value="fixed"),
DeclareLaunchArgument("preparation_witnesses_json", default_value=""),
DeclareLaunchArgument("capture_plan_expected_sha256", default_value=""),
DeclareLaunchArgument("initial_command_file", default_value=""),
DeclareLaunchArgument("reuse_camera_calibration", default_value="false"),
DeclareLaunchArgument("camera_optical_observations_file", default_value=""),
DeclareLaunchArgument(
"calibration_config",
default_value="",
),
DeclareLaunchArgument(
"tag_config",
default_value="",
),
OpaqueFunction(function=_launch_stack),
]
)
@@ -0,0 +1,211 @@
"""Launch three Hikrobot cameras for one-time checkerboard extrinsics."""
from pathlib import Path
from ament_index_python.packages import get_package_share_directory
from launch import LaunchDescription
from launch.actions import DeclareLaunchArgument, OpaqueFunction, SetEnvironmentVariable
from launch.substitutions import LaunchConfiguration
from launch_ros.actions import ComposableNodeContainer, Node
from launch_ros.descriptions import ComposableNode
from launch_ros.parameter_descriptions import ParameterValue
VIEWS = ("front", "side", "top")
def _launch(context):
cameras = []
rectifiers = []
serials = {}
for view in VIEWS:
serial = LaunchConfiguration(f"{view}_camera_serial").perform(context)
if not serial:
raise RuntimeError(f"{view}_camera_serial is required")
serials[view] = serial
namespace = f"/g20_extrinsics/{view}/camera"
cameras.append(
Node(
package="linkerhand_calibration",
executable="hikrobot_camera_node",
name="hikrobot_camera",
namespace=namespace,
output="screen",
emulate_tty=True,
parameters=[
{
"serial_number": serial,
"expected_model": LaunchConfiguration("camera_model"),
"camera_name": LaunchConfiguration(
f"{view}_camera_name"
),
"frame_id": f"g20_extrinsics_{view}_optical_frame",
"image_width": 1624,
"image_height": 1240,
"frame_rate": ParameterValue(
LaunchConfiguration("camera_frame_rate"),
value_type=float,
),
"exposure_time_us": ParameterValue(
LaunchConfiguration("exposure_time_us"),
value_type=float,
),
"gain_db": ParameterValue(
LaunchConfiguration("gain_db"), value_type=float
),
"auto_exposure": False,
"camera_info_url": LaunchConfiguration(
f"{view}_camera_info_url"
),
}
],
)
)
rectifiers.append(
ComposableNode(
package="image_proc",
plugin="image_proc::RectifyNode",
name=f"rectify_{view}",
namespace=namespace,
remappings=[
("image", f"{namespace}/image_raw"),
("camera_info", f"{namespace}/camera_info"),
("image_rect", f"{namespace}/image_rect"),
],
parameters=[{"queue_size": 1}],
extra_arguments=[{"use_intra_process_comms": True}],
)
)
container = ComposableNodeContainer(
name="g20_extrinsics_vision",
namespace="/",
package="rclcpp_components",
executable="component_container_mt",
composable_node_descriptions=rectifiers,
output="screen",
)
solver = Node(
package="linkerhand_calibration",
executable="three_camera_extrinsics_node",
name="g20_camera_extrinsics",
output="screen",
emulate_tty=True,
parameters=[
{
"output_file": LaunchConfiguration("output_file"),
"verification_extrinsics_file": LaunchConfiguration("verification_extrinsics_file"),
"checkerboard_columns": ParameterValue(
LaunchConfiguration("checkerboard_columns"), value_type=int
),
"checkerboard_rows": ParameterValue(
LaunchConfiguration("checkerboard_rows"), value_type=int
),
"square_size_m": ParameterValue(
LaunchConfiguration("square_size_m"), value_type=float
),
"enable_gui": ParameterValue(
LaunchConfiguration("enable_gui"), value_type=bool
),
"gui_refresh_hz": ParameterValue(
LaunchConfiguration("gui_refresh_hz"), value_type=float
),
"maximum_reprojection_rms_px": ParameterValue(
LaunchConfiguration("maximum_reprojection_rms_px"),
value_type=float,
),
"maximum_candidate_pair_reprojection_rms_px": ParameterValue(
LaunchConfiguration(
"maximum_candidate_pair_reprojection_rms_px"
),
value_type=float,
),
"maximum_single_camera_reprojection_rms_px": ParameterValue(
LaunchConfiguration(
"maximum_single_camera_reprojection_rms_px"
),
value_type=float,
),
"auto_capture_default": ParameterValue(
LaunchConfiguration("auto_capture_default"),
value_type=bool,
),
"auto_capture_stable_seconds": ParameterValue(
LaunchConfiguration("auto_capture_stable_seconds"),
value_type=float,
),
**{
f"{view}_camera_serial": serials[view]
for view in VIEWS
},
}
],
)
return [*cameras, container, solver]
def generate_launch_description() -> LaunchDescription:
package_share = Path(
get_package_share_directory("linkerhand_calibration")
)
camera_info = Path.home() / ".ros" / "camera_info"
return LaunchDescription(
[
# Keep the large-image transport deterministic even when the
# calling shell selected another ROS 2 RMW implementation.
SetEnvironmentVariable(
name="RMW_IMPLEMENTATION",
value="rmw_fastrtps_cpp",
),
SetEnvironmentVariable(
name="FASTDDS_DEFAULT_PROFILES_FILE",
value=str(
package_share / "config" / "fastdds_large_images.xml"
),
),
SetEnvironmentVariable(
name="FASTRTPS_DEFAULT_PROFILES_FILE",
value=str(
package_share / "config" / "fastdds_large_images.xml"
),
),
DeclareLaunchArgument("front_camera_serial", default_value="DB2163742"),
DeclareLaunchArgument("side_camera_serial", default_value="DB2163749"),
DeclareLaunchArgument("top_camera_serial", default_value="DB2163739"),
DeclareLaunchArgument("camera_model", default_value="MV-CS020-10U"),
DeclareLaunchArgument("front_camera_name", default_value="hikrobot_front_DB2163742"),
DeclareLaunchArgument("side_camera_name", default_value="hikrobot_side_DB2163749"),
DeclareLaunchArgument("top_camera_name", default_value="hikrobot_top_DB2163739"),
DeclareLaunchArgument("front_camera_info_url", default_value=str(camera_info / "hikrobot_DB2163742.yaml")),
DeclareLaunchArgument("side_camera_info_url", default_value=str(camera_info / "hikrobot_DB2163749.yaml")),
DeclareLaunchArgument("top_camera_info_url", default_value=str(camera_info / "hikrobot_DB2163739.yaml")),
DeclareLaunchArgument("camera_frame_rate", default_value="15.0"),
DeclareLaunchArgument("exposure_time_us", default_value="5000.0"),
DeclareLaunchArgument("gain_db", default_value="0.0"),
DeclareLaunchArgument("checkerboard_columns", default_value="8"),
DeclareLaunchArgument("checkerboard_rows", default_value="5"),
DeclareLaunchArgument("square_size_m", default_value="0.027"),
DeclareLaunchArgument("enable_gui", default_value="true"),
DeclareLaunchArgument("gui_refresh_hz", default_value="2.0"),
DeclareLaunchArgument(
"maximum_reprojection_rms_px", default_value="1.2"
),
DeclareLaunchArgument(
"maximum_candidate_pair_reprojection_rms_px",
default_value="1.5",
),
DeclareLaunchArgument(
"maximum_single_camera_reprojection_rms_px",
default_value="1.5",
),
DeclareLaunchArgument("auto_capture_default", default_value="false"),
DeclareLaunchArgument("verification_extrinsics_file", default_value=""),
DeclareLaunchArgument(
"auto_capture_stable_seconds", default_value="1.0"
),
DeclareLaunchArgument(
"output_file",
default_value=str(Path.cwd() / "config" / "g20_three_camera_extrinsics.yaml"),
),
OpaqueFunction(function=_launch),
]
)
@@ -0,0 +1,18 @@
"""Stable launch name for the profile-driven calibration stack."""
from __future__ import annotations
import importlib.util
from pathlib import Path
def generate_launch_description():
implementation = Path(__file__).with_name("three_camera_calibration.launch.py")
spec = importlib.util.spec_from_file_location(
"linkerhand_unified_calibration_launch", implementation
)
if spec is None or spec.loader is None:
raise RuntimeError("unified calibration launch implementation is missing")
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module.generate_launch_description()
+35
View File
@@ -0,0 +1,35 @@
<?xml version="1.0"?>
<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
<package format="3">
<name>linkerhand_calibration</name>
<version>0.1.0</version>
<description>Profile-driven hand calibration and validated URDF correction.</description>
<maintainer email="support@linker-robotics.com">lxp</maintainer>
<license>MIT</license>
<exec_depend>ament_index_python</exec_depend>
<exec_depend>apriltag_msgs</exec_depend>
<exec_depend>apriltag_ros</exec_depend>
<exec_depend>cv_bridge</exec_depend>
<exec_depend>image_proc</exec_depend>
<exec_depend>launch</exec_depend>
<exec_depend>launch_ros</exec_depend>
<exec_depend>linker_hand_ros2_sdk</exec_depend>
<exec_depend>rclcpp_components</exec_depend>
<exec_depend>rclpy</exec_depend>
<exec_depend>rosbag2</exec_depend>
<exec_depend>sensor_msgs</exec_depend>
<exec_depend>std_msgs</exec_depend>
<exec_depend>std_srvs</exec_depend>
<exec_depend>tf2_msgs</exec_depend>
<exec_depend>python3-numpy</exec_depend>
<exec_depend>python3-opencv</exec_depend>
<exec_depend>python3-scipy</exec_depend>
<exec_depend>python3-yaml</exec_depend>
<test_depend>python3-pytest</test_depend>
<export>
<build_type>ament_python</build_type>
</export>
</package>
+11
View File
@@ -0,0 +1,11 @@
[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"
[tool.pytest.ini_options]
markers = [
"quick: focused unit and contract tests without full artifact generation",
"replay: retained camera/hand observations and real pause regressions",
"integration: fitting, serialized artifacts, process or ROS integration",
"legacy: historical formats, profiles and compatibility contracts",
]
@@ -0,0 +1 @@
+4
View File
@@ -0,0 +1,4 @@
[develop]
script_dir=$base/lib/linkerhand_calibration
[install]
install_scripts=$base/lib/linkerhand_calibration
+116
View File
@@ -0,0 +1,116 @@
from glob import glob
from pathlib import Path
from setuptools import find_packages, setup
package_name = "linkerhand_calibration"
def package_data_tree(root: str, destination: str | None = None) -> list[tuple[str, list[str]]]:
"""Install a resource tree without flattening relative mesh paths."""
root_path = Path(root)
directories = [
root_path,
*sorted(path for path in root_path.rglob("*") if path.is_dir() and path.name != "__pycache__"),
]
result = []
for directory in directories:
files = sorted(
str(path)
for path in directory.iterdir()
if path.is_file()
and path.suffix not in {".py", ".pyc"}
# Generated calibration products belong under calibration_output,
# never in the installed immutable CAD input bundle.
and "calibrated" not in path.stem.lower()
)
if files:
result.append(
(str(Path("share") / package_name / (destination or root) /
directory.relative_to(root_path)), files)
)
return result
def legacy_urdf_data() -> list[tuple[str, list[str]]]:
"""Keep historical package:// URDF and mesh locations when installed."""
result = []
for model in ("g20", "l6", "o12", "o30", "o6"):
for side in ("left", "right"):
root = Path("linkerhand_calibration/models") / model / "urdf" / side
if root.is_dir():
result.extend(package_data_tree(str(root), f"urdf/{model}_{side}"))
return result
setup(
name=package_name,
version="0.1.0",
packages=find_packages(),
data_files=[
(
"share/ament_index/resource_index/packages",
["resource/" + package_name],
),
("share/" + package_name, ["package.xml", *sorted(glob("*.md"))]),
("share/" + package_name + "/launch", glob("launch/*.launch.py")),
] + package_data_tree("config") + package_data_tree("docs") + package_data_tree(
"linkerhand_calibration/models", "models") + legacy_urdf_data(),
install_requires=["setuptools", "numpy", "scipy", "PyYAML"],
tests_require=["pytest"],
zip_safe=True,
maintainer="lxp",
maintainer_email="support@linker-robotics.com",
description="Profile-driven hand calibration and validated URDF correction",
license="MIT",
entry_points={
"console_scripts": [
"rebuild_calibrated_urdf = linkerhand_calibration.runtime.artifacts.urdf_from_json:main",
"analyze_calibration_capture = linkerhand_calibration.runtime.diagnostic_analysis:main",
"analyze_image_solve = linkerhand_calibration.tools.image_solve_report:main",
"analyze_feedback_images = linkerhand_calibration.tools.feedback_image_report:main",
"compare_calibration_urdfs = linkerhand_calibration.urdf_comparison:main",
(
"hikrobot_camera_node = "
"linkerhand_calibration.hikrobot_camera:main"
),
"calibration_node = linkerhand_calibration.runtime.ros.entrypoint:main",
"tag_border_filter_node = linkerhand_calibration.runtime.ros.tag_border_filter:main",
"o12_sdk_bridge = linkerhand_calibration.runtime.adapters.o12_bridge:main",
(
"three_camera_calibration_node = "
"linkerhand_calibration.runtime.ros.entrypoint:main"
),
(
"three_camera_extrinsics_node = "
"linkerhand_calibration.extrinsics_node:main"
),
(
"offline_replay = "
"linkerhand_calibration.offline_replay:main"
),
(
"validate_g20_goldens = "
"linkerhand_calibration.compat.legacy_diagnostic_tools.models.g20.golden_regression:main"
),
(
"camera_alignment_view = "
"linkerhand_calibration.alignment_view:main"
),
(
"calibrated_joint_state_bridge = "
"linkerhand_calibration."
"calibrated_joint_state_bridge:main"
),
(
"calibrate_g20_right = "
"linkerhand_calibration.runtime.runner:main"
),
(
"calibrate_hand = "
"linkerhand_calibration.runtime.runner:main"
),
],
},
)
@@ -0,0 +1,84 @@
"""Shared read-only synthetic input; mutating tests must copy their records."""
import pytest
# Keep compatibility in one catalog, without moving modules imported as fixtures.
TIERS = {
"legacy": set("""acquisition alignment_view calibrated_joint_state_bridge core diagnostics
full_hand g20_right_product golden_regression l6_right_profile o12_full_hand_zero
o12_observation_resolution o12_right_profile o12_thumb_pnp o6_right_profile
offline_replay sample_schema storage trajectory urdf_comparison urdf_zero zero_calibration
resume_v2""".split()),
"replay": set("""recorded_diagnostic_replay recorded_side_preparation o12_recorded_replay
spatial_solve_order shared_tag_pose_bridge shared_zero_conditioning shared_pose_conditioning
measured_transfer transferred_hinge_geometry o30_side_observer resumed_image_reference
final_image_sources feedback_reversal_progress native_position_feedback
preparation_admission""".split()),
"integration": set("""all_model_artifact_pipeline all_view_image_acceptance axis_line_gauge
bounded_mimic_approximation calibration_coordinator cad_image_geometry
directional_command_mapping dual_mapping final_image_holdout frozen_candidate_selection
frozen_tag_replay image_model_selection image_motion_live_flow independent_urdf_export
json_urdf_rebuild measured_finalization measured_transfer_finalization measured_zero_mapping
o30_artifacts o6_tag_installation partial_o30_calibration parallel_image_replay
production_image_motion profile_finalization relative_standard_urdf single_pass_capture
transfer_artifact_contract unified_ros_host""".split()),
}
def pytest_addoption(parser):
parser.addoption("--timings-json", help="Write durations and outcomes for this selected run to JSON")
def pytest_collection_modifyitems(items):
for item in items:
if any(item.get_closest_marker(name) for name in ("quick", *TIERS)):
continue
name = item.path.stem.removeprefix("test_")
tier = next((tier for tier, names in TIERS.items() if name in names), "quick")
item.add_marker(getattr(pytest.mark, tier))
def pytest_configure(config):
import time
config._calibration_started = time.perf_counter()
config._calibration_timings = {}
config._calibration_source_sha256 = None
if config.getoption("--timings-json"):
import hashlib
from pathlib import Path
root = Path(__file__).resolve().parents[1]
digest = hashlib.sha256()
for path in sorted((*root.rglob("*.py"), *root.rglob("*.yaml"))):
digest.update(str(path.relative_to(root)).encode())
digest.update(path.read_bytes())
config._calibration_source_sha256 = digest.hexdigest()
@pytest.hookimpl(hookwrapper=True)
def pytest_runtest_makereport(item, call):
report = (yield).get_result()
result = item.config._calibration_timings.setdefault(item.nodeid, {
"tier": next(name for name in ("quick", *TIERS) if item.get_closest_marker(name)),
"phases": {}})
result["phases"][report.when] = {"seconds": report.duration, "outcome": report.outcome}
def pytest_sessionfinish(session):
path = session.config.getoption("--timings-json")
if path:
import json
import time
from pathlib import Path
output = Path(path)
output.parent.mkdir(parents=True, exist_ok=True)
output.write_text(json.dumps({"exit_status": int(session.exitstatus),
"elapsed_seconds": time.perf_counter()-session.config._calibration_started,
"source_sha256": session.config._calibration_source_sha256,
"tests": session.config._calibration_timings}, indent=2) + "\n")
@pytest.fixture(scope="session")
def o30_capture():
from o30_capture_fixture import synthetic_capture
return synthetic_capture()
@@ -0,0 +1,110 @@
"""Ideal camera/SDK transport for the REAL capture and session executor.
Only the sensor's pose estimator is idealized; the state machine, observation
joins, unique-image quality, four-cycle selection and finalizer are production
code. Real pinhole/IPPE behavior is independently tested in observation_capture.
"""
from collections import defaultdict
from types import SimpleNamespace
import numpy as np
from scipy.spatial.transform import Rotation
from linkerhand_calibration.core.geometry.extrinsics import transform_matrix
from linkerhand_calibration.core.geometry.pnp import SquareTagPose
from linkerhand_calibration.runtime.capture import CaptureFrame, ObservationCapture
from linkerhand_calibration.runtime.execution import SessionExecution
from linkerhand_calibration.runtime.reference_lock import ReferenceLock
from linkerhand_calibration.runtime.session import CalibrationPhase as Phase
from pose_branch_fixture import IdealPoseTracker
def collect_with_engine(profile, observations):
# One fixed camera geometry, independent of the task/model names.
normal = np.ones(3)/np.sqrt(3)
x = np.cross([0, 1, 0], normal); x /= np.linalg.norm(x)
rotation = np.column_stack((x, np.cross(normal, x), normal))
camera = np.eye(4); camera[:3, :3] = rotation; camera[:3, 3] = [0, 0, -.5]
camera_inverse = np.linalg.inv(camera)
fixed_roles = {view.name: next(t.role for t in view.tags if t.fixed_reference) for view in profile.vision.views}
fixed_poses = {}
frame_groups = defaultdict(lambda: defaultdict(list))
for row in observations:
name = row.get("joint", row.get("observation_joint"))
spec_name = name if "joint" in row else profile.measurement.cross_view_sources[name]
spec = profile.measurement.measurements[spec_name]
if spec.parent_role == fixed_roles[spec.view]:
fixed_poses[spec.view] = row["parent_pose_common"]
key = (row["task_name"], row["cycle"], row["direction"], row.get("sample_phase", "sweep"), row.get("steady_index"))
frame_groups[key][row["sample_id"]].append((row, spec))
poses = {view: {} for view in profile.vision.view_names}
class IdealPoseSensor(IdealPoseTracker):
def __init__(self, view):
super().__init__()
self.view = view
def estimate(self, role, corners, **kwargs):
return self.accept_ideal_pose(role, poses[self.view][role], kwargs["stamp_ns"])
def camera_pose(payload):
value = camera_inverse @ transform_matrix(payload["translation_xyz_m"], payload["quaternion_xyzw"])
return SquareTagPose(tuple(Rotation.from_matrix(value[:3, :3]).as_quat()), tuple(value[:3, 3]), 0.)
lock = ReferenceLock({v.name: next(t.tag_id for t in v.tags if t.fixed_reference) for v in profile.vision.views})
capture = ObservationCapture(profile, reference_lock=lock,
extrinsics=SimpleNamespace(transform=lambda _: camera),
trackers={view: IdealPoseSensor(view) for view in profile.vision.view_names})
execution = SessionExecution(profile)
execution.session.device_ready()
execution.session.start()
lock.begin_session()
current = profile.command.baseline_values
retained, stamp, phases = [], 0, set()
square = np.array([[-20, 20], [20, 20], [20, -20], [-20, -20]])
while execution.session.phase != Phase.CAPTURE_COMPLETE:
phase = execution.session.phase
phases.add(phase)
if phase == Phase.REFERENCE_LOCKING:
lock.start_locking()
for view, role in fixed_roles.items():
poses[view] = {role: camera_pose(fixed_poses[view])}
for _ in range(10):
stamp += 1
capture.consume(CaptureFrame(view, stamp, np.eye(3), {role: square}, current, current))
assert lock.locked
execution.session.reference_locked()
continue
if phase == Phase.EVALUATE:
quality = execution.evaluate(retained)
assert quality.passed, quality.failures
continue
motion = execution.motion(current)
assert motion is not None, phase
if motion.recording:
key = (motion.task_key, motion.cycle, motion.direction, motion.phase, motion.steady_index)
for rows in frame_groups[key].values():
first = rows[0][0]; view = first["view"]
poses[view] = {}
centers = {}
for row, spec in rows:
poses[view][spec.parent_role] = camera_pose(row["parent_pose_common"])
poses[view][spec.child_role] = camera_pose(row["child_pose_common"])
centers.setdefault(spec.parent_role, np.zeros(2))
centers[spec.child_role] = centers[spec.parent_role] + row["image_relative_xy_px"]
# Fixed references are physically stationary in this fixture;
# the image-circle test signal belongs only to moving Tags.
corners = {role: square+center for role, center in centers.items()}
if fixed_roles[view] in corners:
corners[fixed_roles[view]] = square
stamp += 1
unit = profile.command.unit
frame = CaptureFrame(view, stamp, np.eye(3), corners,
tuple(first[f"state_{unit}"]), tuple(first[f"command_vector_{unit}"]))
captured, moved = capture.consume(frame, motion)
assert moved is None
# The IPPE candidate branch is covered by real projected-corner
# tests, not these deliberately ideal pose measurements.
retained.extend(row for row in captured if row["kind"] != "pnp_candidate_frame")
current = motion.target
execution.motion_complete()
assert len(execution.completed_units) == 8*len(profile.motion.tasks)
assert Phase.RETURN_BASELINE in phases
return execution, retained
@@ -0,0 +1,443 @@
{
"source_sha256": "80cb767f034849d22fd7d897ad4cb9a1c01de060439016fefa06aa231542b9a4",
"camera_matrix": [
[
3792.732421875,
0.0,
606.0140166893543
],
[
0.0,
3825.36962890625,
568.5244182036549
],
[
0.0,
0.0,
1.0
]
],
"tag_size_m": 0.0165,
"images": [
{
"stamp_ns": 1789811400295661447,
"corners_xy": [
[
630.1279296874998,
928.3162231445312
],
[
686.1949462890624,
927.6565551757814
],
[
685.3428344726562,
870.0587158203125
],
[
629.3317260742188,
870.7624511718751
]
]
},
{
"stamp_ns": 1789811400329003207,
"corners_xy": [
[
630.280517578125,
928.2393798828126
],
[
686.3184204101562,
927.5789184570314
],
[
685.5235595703125,
869.9670410156248
],
[
629.4974365234375,
870.6890258789062
]
]
},
{
"stamp_ns": 1789811400362344967,
"corners_xy": [
[
630.4296875,
928.1881713867188
],
[
686.4510498046875,
927.5227661132812
],
[
685.7029418945314,
869.900146484375
],
[
629.6718139648438,
870.6118774414061
]
]
},
{
"stamp_ns": 1789811400395686727,
"corners_xy": [
[
630.3947143554688,
928.2260131835938
],
[
686.4204101562501,
927.5676879882811
],
[
685.6613769531249,
869.9398803710936
],
[
629.6418457031248,
870.6625976562499
]
]
},
{
"stamp_ns": 1789811400429028487,
"corners_xy": [
[
630.2294311523438,
928.3228149414064
],
[
686.2821044921874,
927.6596069335936
],
[
685.46533203125,
870.066650390625
],
[
629.4439697265625,
870.7839355468751
]
]
},
{
"stamp_ns": 1789811400495712007,
"corners_xy": [
[
630.1682739257811,
928.3910522460938
],
[
686.2355346679689,
927.7315673828125
],
[
685.405029296875,
870.1271362304688
],
[
629.3829956054685,
870.8333740234375
]
]
},
{
"stamp_ns": 1789811400529053767,
"corners_xy": [
[
630.31494140625,
928.3104248046875
],
[
686.3540039062498,
927.6571655273438
],
[
685.5723876953126,
870.0433959960936
],
[
629.5508422851567,
870.7587890625
]
]
},
{
"stamp_ns": 1789811400562395527,
"corners_xy": [
[
630.4141235351562,
928.2030639648438
],
[
686.4436645507812,
927.5493774414062
],
[
685.6757202148438,
869.9291381835938
],
[
629.6626586914062,
870.6368408203125
]
]
},
{
"stamp_ns": 1789811400795973611,
"corners_xy": [
[
630.3918457031251,
928.1535034179686
],
[
686.4117431640624,
927.4778442382811
],
[
685.6537475585939,
869.8693237304689
],
[
629.6341552734376,
870.5805664062499
]
]
},
{
"stamp_ns": 1789811400829315371,
"corners_xy": [
[
630.2717285156249,
928.1955566406247
],
[
686.3017578124998,
927.5195922851562
],
[
685.5221557617189,
869.9111938476565
],
[
629.4907226562503,
870.62109375
]
]
},
{
"stamp_ns": 1789811400862657131,
"corners_xy": [
[
630.1775512695311,
928.2653198242186
],
[
686.23046875,
927.5882568359375
],
[
685.400634765625,
869.9884643554686
],
[
629.3800659179688,
870.7053222656249
]
]
},
{
"stamp_ns": 1789811400929340651,
"corners_xy": [
[
630.2564697265625,
928.3482055664064
],
[
686.3138427734375,
927.6983642578125
],
[
685.5140380859375,
870.0744018554686
],
[
629.4822387695311,
870.7982177734375
]
]
},
{
"stamp_ns": 1789811400962682411,
"corners_xy": [
[
630.3780517578125,
928.2880859375002
],
[
686.40478515625,
927.6194458007812
],
[
685.6351928710938,
869.99658203125
],
[
629.6276245117188,
870.7251586914062
]
]
},
{
"stamp_ns": 1789811401029365931,
"corners_xy": [
[
630.2855224609376,
928.2488403320312
],
[
686.3333740234377,
927.5859375
],
[
685.5617065429688,
869.9732055664064
],
[
629.5308837890624,
870.688232421875
]
]
},
{
"stamp_ns": 1789811401062707691,
"corners_xy": [
[
630.1878662109376,
928.2838134765625
],
[
686.244873046875,
927.609619140625
],
[
685.4309692382812,
870.0062255859376
],
[
629.3936767578126,
870.7116699218751
]
]
},
{
"stamp_ns": 1789811401096049451,
"corners_xy": [
[
630.189208984375,
928.2930297851562
],
[
686.2364501953124,
927.6361083984375
],
[
685.4137573242188,
870.0328369140625
],
[
629.4002685546875,
870.746826171875
]
]
},
{
"stamp_ns": 1789811401129391211,
"corners_xy": [
[
630.2636108398438,
928.2960205078126
],
[
686.2976684570311,
927.627197265625
],
[
685.492919921875,
870.0244140625001
],
[
629.466064453125,
870.7437133789062
]
]
},
{
"stamp_ns": 1789811401162732971,
"corners_xy": [
[
630.3629760742185,
928.2514648437498
],
[
686.3906249999999,
927.6051025390625
],
[
685.624755859375,
869.9824829101564
],
[
629.606689453125,
870.6973876953125
]
]
},
{
"stamp_ns": 1789811401196074731,
"corners_xy": [
[
630.3822021484375,
928.1871337890625
],
[
686.4000854492188,
927.5312499999999
],
[
685.6293334960939,
869.9202880859376
],
[
629.6141357421875,
870.6192626953126
]
]
},
{
"stamp_ns": 1789811401229199593,
"corners_xy": [
[
630.2957763671876,
928.1724853515625
],
[
686.32470703125,
927.5040283203126
],
[
685.5545043945312,
869.896545410156
],
[
629.523620605469,
870.6052856445311
]
]
}
]
}
@@ -0,0 +1,850 @@
{
"source_session": "calibration_output/O30_RIGHT_001/20260919_165005",
"diagnostic_only": true,
"description": "Image-aligned feedback during command 255 to 223 reversal; feedback first catches up in the preceding direction, then returns. No command/angle calibration claim.",
"initial_command": 255,
"target_command": 223,
"initial_feedback": 221,
"frames": [
[
0.008996,
255.0,
221.0
],
[
0.042338,
255.0,
221.0
],
[
0.075679,
255.0,
221.0
],
[
0.109021,
255.0,
221.0
],
[
0.142363,
254.0,
221.0
],
[
0.175705,
254.0,
221.0
],
[
0.209058,
254.0,
221.0
],
[
0.2424,
253.0,
221.0
],
[
0.275742,
253.0,
221.0
],
[
0.309083,
252.0,
221.0
],
[
0.342425,
252.0,
221.0
],
[
0.375767,
251.0,
221.64954668688875
],
[
0.409109,
251.0,
228.398229765594
],
[
0.44245,
250.0,
247.0
],
[
0.475792,
249.0,
247.0
],
[
0.509134,
248.0,
247.0
],
[
0.542476,
248.0,
247.0
],
[
0.575817,
247.0,
247.0
],
[
0.609159,
246.0,
247.0
],
[
0.642501,
245.0,
247.0
],
[
0.675843,
244.0,
247.0
],
[
0.709184,
243.0,
247.0
],
[
0.742367,
242.0,
245.98337350676
],
[
0.775709,
241.0,
241.0
],
[
0.80905,
240.0,
241.0
],
[
0.842392,
239.0,
241.0
],
[
0.875734,
238.0,
241.0
],
[
0.909076,
237.0,
241.0
],
[
0.942417,
236.0,
241.0
],
[
0.975759,
235.0,
240.44438808889143
],
[
1.009101,
234.0,
235.0
],
[
1.042443,
233.0,
235.0
],
[
1.075785,
232.0,
235.0
],
[
1.109126,
231.0,
235.0
],
[
1.142468,
230.0,
234.52744808972707
],
[
1.17581,
230.0,
229.0
],
[
1.209152,
229.0,
229.0
],
[
1.242493,
228.0,
229.0
],
[
1.275771,
227.0,
229.0
],
[
1.309113,
227.0,
229.0
],
[
1.342455,
226.0,
229.0
],
[
1.375796,
226.0,
228.9274971081905
],
[
1.409138,
225.0,
226.93087409328646
],
[
1.44248,
225.0,
224.0
],
[
1.475822,
224.0,
224.0
],
[
1.509163,
224.0,
224.0
],
[
1.542505,
224.0,
224.0
],
[
1.609189,
223.0,
224.0
],
[
1.64253,
223.0,
224.0
],
[
1.675872,
223.0,
224.0
],
[
1.709214,
223.0,
224.0
],
[
1.742556,
223.0,
224.0
],
[
1.775897,
223.0,
224.0
],
[
1.809242,
223.0,
224.0
],
[
1.842584,
223.0,
224.0
],
[
1.875925,
223.0,
224.0
],
[
1.909267,
223.0,
224.0
],
[
1.942609,
223.0,
224.0
],
[
1.975951,
223.0,
221.15303107296222
],
[
2.009292,
223.0,
221.0
],
[
2.042634,
223.0,
221.0
],
[
2.075976,
223.0,
221.0
],
[
2.109318,
223.0,
221.0
],
[
2.142659,
223.0,
221.0
],
[
2.176001,
223.0,
221.0
],
[
2.209343,
223.0,
221.0
],
[
2.242685,
223.0,
221.0
],
[
2.276027,
223.0,
221.0
],
[
2.309368,
223.0,
221.0
],
[
2.342624,
223.0,
221.0
],
[
2.375966,
223.0,
221.0
],
[
2.409308,
223.0,
221.0
],
[
2.442649,
223.0,
221.0
],
[
2.475991,
223.0,
221.0
],
[
2.509333,
223.0,
221.0
],
[
2.542675,
223.0,
221.0
],
[
2.576016,
223.0,
221.0
],
[
2.609358,
223.0,
221.0
],
[
2.6427,
223.0,
221.0
],
[
2.676042,
223.0,
221.0
],
[
2.709384,
223.0,
221.0
],
[
2.742725,
223.0,
221.0
],
[
2.776067,
223.0,
221.0
],
[
2.809409,
223.0,
221.0
],
[
2.842751,
223.0,
221.0
],
[
2.876021,
223.0,
221.0
],
[
2.909363,
223.0,
221.0
],
[
2.942705,
223.0,
221.0
],
[
3.009388,
223.0,
221.0
],
[
3.04273,
223.0,
221.0
],
[
3.076072,
223.0,
221.0
],
[
3.109414,
223.0,
221.0
],
[
3.142755,
223.0,
221.0
],
[
3.176097,
223.0,
221.0
],
[
3.242781,
223.0,
221.0
],
[
3.276122,
223.0,
221.0
],
[
3.309464,
223.0,
221.0
],
[
3.342806,
223.0,
221.0
],
[
3.376148,
223.0,
221.0
],
[
3.409437,
223.0,
221.0
],
[
3.442779,
223.0,
221.0
],
[
3.47612,
223.0,
221.0
],
[
3.509462,
223.0,
221.0
],
[
3.542804,
223.0,
221.0
],
[
3.609487,
223.0,
221.0
],
[
3.642829,
223.0,
221.0
],
[
3.676171,
223.0,
221.0
],
[
3.709513,
223.0,
221.0
],
[
3.742854,
223.0,
221.0
],
[
3.776196,
223.0,
221.0
],
[
3.809538,
223.0,
221.0
],
[
3.84288,
223.0,
221.0
],
[
3.876221,
223.0,
221.0
],
[
3.909563,
223.0,
221.0
],
[
3.94292,
223.0,
221.0
],
[
3.976262,
223.0,
221.0
],
[
4.009604,
223.0,
221.0
],
[
4.042946,
223.0,
221.0
],
[
4.076288,
223.0,
221.0
],
[
4.109629,
223.0,
221.0
],
[
4.142971,
223.0,
221.0
],
[
4.176313,
223.0,
221.0
],
[
4.209655,
223.0,
221.0
],
[
4.242996,
223.0,
221.0
],
[
4.276338,
223.0,
221.0
],
[
4.30968,
223.0,
221.0
],
[
4.376363,
223.0,
221.0
],
[
4.409705,
223.0,
221.0
],
[
4.443047,
223.0,
221.0
],
[
4.476303,
223.0,
221.0
],
[
4.509644,
223.0,
221.0
],
[
4.542986,
223.0,
221.0
],
[
4.576328,
223.0,
221.0
],
[
4.60967,
223.0,
221.0
],
[
4.643011,
223.0,
221.0
],
[
4.676353,
223.0,
221.0
],
[
4.709695,
223.0,
221.0
],
[
4.743037,
223.0,
221.0
],
[
4.776378,
223.0,
221.0
],
[
4.80972,
223.0,
221.0
],
[
4.843062,
223.0,
221.0
],
[
4.876404,
223.0,
221.0
],
[
4.909745,
223.0,
221.0
],
[
4.943087,
223.0,
221.0
],
[
4.976429,
223.0,
221.0
],
[
5.009743,
223.0,
221.0
],
[
5.043085,
223.0,
221.0
],
[
5.076427,
223.0,
221.0
],
[
5.109769,
223.0,
221.0
],
[
5.14311,
223.0,
221.0
],
[
5.176452,
223.0,
221.0
],
[
5.209794,
223.0,
221.0
],
[
5.243136,
223.0,
221.0
],
[
5.276477,
223.0,
221.0
],
[
5.309819,
223.0,
221.0
],
[
5.343161,
223.0,
221.0
],
[
5.376503,
223.0,
221.0
],
[
5.409844,
223.0,
221.0
],
[
5.443186,
223.0,
221.0
],
[
5.476528,
223.0,
221.0
],
[
5.50987,
223.0,
221.0
],
[
5.543188,
223.0,
221.0
],
[
5.57653,
223.0,
221.0
],
[
5.609872,
223.0,
221.0
],
[
5.643213,
223.0,
221.0
],
[
5.676555,
223.0,
221.0
],
[
5.709897,
223.0,
221.0
],
[
5.77658,
223.0,
221.0
]
]
}
@@ -0,0 +1,474 @@
{
"source_session": "O6_RIGHT_001/20260914_161416",
"source_raw_sha256": "3eefc417ab968b54879241855336bf9ae5a5b5d31d8ae41c2915eac109afa912",
"scope": "Recorded frozen reference and five deformed front ID0 detections. No images after the pause were recorded; this fixture cannot prove actual recovery.",
"view": "front",
"tag_role": "front_base",
"tag_id": 0,
"tag_size_m": 0.016,
"camera_matrix": [
[
3792.732421875,
0.0,
606.0140166893543
],
[
0.0,
3825.36962890625,
568.5244182036549
],
[
0.0,
0.0,
1.0
]
],
"reference_corners_xy": [
[
651.6114807128906,
852.3683776855469
],
[
708.6465759277344,
845.8826293945312
],
[
701.8229675292969,
787.6893920898438
],
[
644.96826171875,
794.0107421875
]
],
"reference_pose": {
"rotation_xyzw": [
0.05122618750941407,
0.07257853631173206,
0.05376952559779321,
-0.9945939231148989
],
"translation_xyz_m": [
0.019507045482571185,
0.06870574180366773,
1.0452219935270852
]
},
"events": [
{
"kind": "pnp_branch_event",
"view": "front",
"image_stamp_ns": 1789373674703790511,
"tag_role": "front_base",
"tag_id": 0,
"reason": "pose_branch_unconfirmed",
"pnp_observation_evidence": {
"tag_role": "front_base",
"tag_id": 0,
"tag_size_m": 0.016,
"pose_source": "current_image",
"corners_xy": [
[
650.7820434570314,
849.603271484375
],
[
708.2871704101564,
846.6178588867189
],
[
701.3147583007812,
787.5760498046876
],
[
644.46142578125,
793.9281005859375
]
],
"selected_pose": null,
"reprojection_valid_candidates": [
{
"quaternion_xyzw": [
0.0689494439189896,
0.0892766701000514,
-0.052421998914305996,
0.9922336339738425
],
"translation_xyz_m": [
0.01927051064753879,
0.0683358712786946,
1.04173012169382
],
"reprojection_error_px": 0.8203549082285015
},
{
"quaternion_xyzw": [
-0.13467791812542612,
-0.07440102998631523,
-0.04520090653912901,
0.987057862110635
],
"translation_xyz_m": [
0.019286540244008814,
0.0683040199267154,
1.0416235980482782
],
"reprojection_error_px": 0.8884351664530162
}
],
"candidate_diagnostics": {
"solved_candidate_count": 2,
"reprojection_candidate_count": 2,
"independent_tilt_candidate_count": 2,
"maximum_reprojection_error_px": 1.5,
"maximum_independent_tilt_deg": 75.0,
"minimum_reprojection_error_px": 0.8203549082285015,
"minimum_candidate_tilt_deg": 12.9537577740523,
"maximum_candidate_tilt_deg": 17.701656618264686,
"pose_constraint": "fixed_reference",
"fixed_reference_reprojection_error_px": 1.5511578554957017,
"fixed_reference_verified": false,
"observation_stamp_ns": 1789373674703790511,
"branch_revision": 2,
"branch_status": "fixed_reference_pending",
"branch_reason": "pose_branch_unconfirmed",
"branch_confirmation_count": 1,
"branch_frozen": true
},
"branch_corrections_total": 1
}
},
{
"kind": "pnp_branch_event",
"view": "front",
"image_stamp_ns": 1789373674737107853,
"tag_role": "front_base",
"tag_id": 0,
"reason": "pose_branch_unconfirmed",
"pnp_observation_evidence": {
"tag_role": "front_base",
"tag_id": 0,
"tag_size_m": 0.016,
"pose_source": "current_image",
"corners_xy": [
[
650.986572265625,
849.4489135742189
],
[
708.4765625,
846.6978759765625
],
[
701.5152587890625,
787.5821533203124
],
[
644.6348266601564,
793.9254150390625
]
],
"selected_pose": null,
"reprojection_valid_candidates": [
{
"quaternion_xyzw": [
0.07274616669000304,
0.09173097100644584,
-0.05204806881576712,
0.9917582481243471
],
"translation_xyz_m": [
0.019305954335328467,
0.06827132134840262,
1.0408129484230706
],
"reprojection_error_px": 0.8723269389119234
},
{
"quaternion_xyzw": [
-0.1384302855795689,
-0.07679770133531316,
-0.044595240947531964,
0.9863824986225185
],
"translation_xyz_m": [
0.019322228608171357,
0.0682377527103236,
1.0406931830626773
],
"reprojection_error_px": 0.944197809557915
}
],
"candidate_diagnostics": {
"solved_candidate_count": 2,
"reprojection_candidate_count": 2,
"independent_tilt_candidate_count": 2,
"maximum_reprojection_error_px": 1.5,
"maximum_independent_tilt_deg": 75.0,
"minimum_reprojection_error_px": 0.8723269389119234,
"minimum_candidate_tilt_deg": 13.446654725220979,
"maximum_candidate_tilt_deg": 18.217183252762826,
"pose_constraint": "fixed_reference",
"fixed_reference_reprojection_error_px": 1.573755927601701,
"fixed_reference_verified": false,
"observation_stamp_ns": 1789373674737107853,
"branch_revision": 2,
"branch_status": "fixed_reference_pending",
"branch_reason": "pose_branch_unconfirmed",
"branch_confirmation_count": 2,
"branch_frozen": true
},
"branch_corrections_total": 1
}
},
{
"kind": "pnp_branch_event",
"view": "front",
"image_stamp_ns": 1789373674770184767,
"tag_role": "front_base",
"tag_id": 0,
"reason": "pose_branch_unconfirmed",
"pnp_observation_evidence": {
"tag_role": "front_base",
"tag_id": 0,
"tag_size_m": 0.016,
"pose_source": "current_image",
"corners_xy": [
[
651.1397705078125,
849.4150390625003
],
[
708.6453247070312,
846.7749633789064
],
[
701.6513061523439,
787.606018066406
],
[
644.8040161132812,
793.9556884765625
]
],
"selected_pose": null,
"reprojection_valid_candidates": [
{
"quaternion_xyzw": [
0.07377523792253451,
0.09322053207746203,
-0.051915478601721,
0.9915502658716917
],
"translation_xyz_m": [
0.01934209599907669,
0.068254351936264,
1.040451517901641
],
"reprojection_error_px": 0.9029827200918235
},
{
"quaternion_xyzw": [
-0.1394470128719977,
-0.07824625765923164,
-0.04434376576803557,
0.9861367472115171
],
"translation_xyz_m": [
0.0193585945536293,
0.06822023556286914,
1.040326908596307
],
"reprojection_error_px": 0.975293447689657
}
],
"candidate_diagnostics": {
"solved_candidate_count": 2,
"reprojection_candidate_count": 2,
"independent_tilt_candidate_count": 2,
"maximum_reprojection_error_px": 1.5,
"maximum_independent_tilt_deg": 75.0,
"minimum_reprojection_error_px": 0.9029827200918235,
"minimum_candidate_tilt_deg": 13.65513087280534,
"maximum_candidate_tilt_deg": 18.402160681532425,
"pose_constraint": "fixed_reference",
"fixed_reference_reprojection_error_px": 1.5711497009701978,
"fixed_reference_verified": false,
"observation_stamp_ns": 1789373674770184767,
"branch_revision": 2,
"branch_status": "fixed_reference_pending",
"branch_reason": "pose_branch_unconfirmed",
"branch_confirmation_count": 3,
"branch_frozen": true
},
"branch_corrections_total": 1
}
},
{
"kind": "pnp_branch_event",
"view": "front",
"image_stamp_ns": 1789373674803781247,
"tag_role": "front_base",
"tag_id": 0,
"reason": "pose_branch_unconfirmed",
"pnp_observation_evidence": {
"tag_role": "front_base",
"tag_id": 0,
"tag_size_m": 0.016,
"pose_source": "current_image",
"corners_xy": [
[
651.1066894531251,
849.4465332031251
],
[
708.6222534179689,
846.8680419921876
],
[
701.619140625,
787.6516723632811
],
[
644.7723388671875,
794.01220703125
]
],
"selected_pose": null,
"reprojection_valid_candidates": [
{
"quaternion_xyzw": [
0.07416052126135776,
0.09401877076851597,
-0.05184184633608467,
0.9914500041847227
],
"translation_xyz_m": [
0.019326739165784403,
0.06824498811606222,
1.0400731042057596
],
"reprojection_error_px": 0.9209144087717472
},
{
"quaternion_xyzw": [
-0.13983752470383345,
-0.07905290919387553,
-0.04421050999107296,
0.9860230905202062
],
"translation_xyz_m": [
0.019343352432883133,
0.06821053937063642,
1.0399448592973592
],
"reprojection_error_px": 0.9939407301090831
}
],
"candidate_diagnostics": {
"solved_candidate_count": 2,
"reprojection_candidate_count": 2,
"independent_tilt_candidate_count": 2,
"maximum_reprojection_error_px": 1.5,
"maximum_independent_tilt_deg": 75.0,
"minimum_reprojection_error_px": 0.9209144087717472,
"minimum_candidate_tilt_deg": 13.754987577665794,
"maximum_candidate_tilt_deg": 18.487617322056742,
"pose_constraint": "fixed_reference",
"fixed_reference_reprojection_error_px": 1.5736869605739345,
"fixed_reference_verified": false,
"observation_stamp_ns": 1789373674803781247,
"branch_revision": 2,
"branch_status": "fixed_reference_pending",
"branch_reason": "pose_branch_unconfirmed",
"branch_confirmation_count": 4,
"branch_frozen": true
},
"branch_corrections_total": 1
}
},
{
"kind": "pnp_branch_event",
"view": "front",
"image_stamp_ns": 1789373674837065731,
"tag_role": "front_base",
"tag_id": 0,
"reason": "pose_branch_conflict",
"pnp_observation_evidence": {
"tag_role": "front_base",
"tag_id": 0,
"tag_size_m": 0.016,
"pose_source": "current_image",
"corners_xy": [
[
650.91162109375,
849.4388427734373
],
[
708.4180297851561,
846.9037475585938
],
[
701.4273681640625,
787.6770629882815
],
[
644.5805053710939,
794.0317382812501
]
],
"selected_pose": null,
"reprojection_valid_candidates": [
{
"quaternion_xyzw": [
0.0745974181611575,
0.09433986520903168,
-0.051717641242694276,
0.9913932119095445
],
"translation_xyz_m": [
0.019272532256405614,
0.06824822341509994,
1.040046126872147
],
"reprojection_error_px": 0.9295222058852461
},
{
"quaternion_xyzw": [
-0.14027036228299425,
-0.07941984067154015,
-0.04406108200999516,
0.9859388091686081
],
"translation_xyz_m": [
0.019289181266401056,
0.068213529376978,
1.0399155768327384
],
"reprojection_error_px": 1.0031381095366472
}
],
"candidate_diagnostics": {
"solved_candidate_count": 2,
"reprojection_candidate_count": 2,
"independent_tilt_candidate_count": 2,
"maximum_reprojection_error_px": 1.5,
"maximum_independent_tilt_deg": 75.0,
"minimum_reprojection_error_px": 0.9295222058852461,
"minimum_candidate_tilt_deg": 13.81532839490434,
"maximum_candidate_tilt_deg": 18.55233483567943,
"pose_constraint": "fixed_reference",
"fixed_reference_reprojection_error_px": 1.6233466461226242,
"fixed_reference_verified": false,
"observation_stamp_ns": 1789373674837065731,
"branch_revision": 2,
"branch_status": "frozen_conflict",
"branch_reason": "pose_branch_conflict",
"branch_confirmation_count": 5,
"branch_frozen": true
},
"branch_corrections_total": 1
}
}
]
}
@@ -0,0 +1,459 @@
{
"source_session": "O6_RIGHT_001/20260914_160325",
"source_raw_sha256": "e08be16c6c77f031cdc524c89fdeb103f2a5cf2c3c8bb67187f6b5db570f640f",
"scope": "Recorded frozen reference and five conflicting front ID0 images; successful preparation images were not recorded. Not a full session or accuracy replay.",
"view": "front",
"tag_role": "front_base",
"tag_id": 0,
"tag_size_m": 0.016,
"reference_corners_xy": [
[
651.3810424804688,
852.2985229492188
],
[
708.4353942871094,
845.8116455078125
],
[
701.5877380371094,
787.6119079589844
],
[
644.7322692871093,
793.9474182128906
]
],
"reference_pose": {
"rotation_xyzw": [
0.051657382830113,
0.07233818005965809,
0.053787910495170524,
-0.9945881374666417
],
"translation_xyz_m": [
0.019443198546650248,
0.06867587597205813,
1.04523215512729
]
},
"camera_matrix": [
[
3792.732421875,
0.0,
606.0140166893543
],
[
0.0,
3825.36962890625,
568.5244182036549
],
[
0.0,
0.0,
1.0
]
],
"events": [
{
"kind": "pnp_branch_event",
"view": "front",
"image_stamp_ns": 1789373017897501233,
"tag_role": "front_base",
"tag_id": 0,
"reason": "pose_branch_unconfirmed",
"pnp_observation_evidence": {
"tag_role": "front_base",
"tag_id": 0,
"tag_size_m": 0.016,
"pose_source": "current_image",
"corners_xy": [
[
651.2639160156251,
851.8523559570312
],
[
708.3605346679686,
845.7075195312501
],
[
701.5051879882811,
787.6116333007814
],
[
644.6477050781251,
793.9578247070312
]
],
"selected_pose": null,
"reprojection_valid_candidates": [
{
"quaternion_xyzw": [
-0.0017637893722219381,
0.0741246018891116,
-0.058492815624425876,
0.9955305233704078
],
"translation_xyz_m": [
0.019470355602835353,
0.06889911011030934,
1.0489767358449047
],
"reprojection_error_px": 0.05631830982299966
},
{
"quaternion_xyzw": [
-0.06454724733730362,
-0.05935707358630751,
-0.05353332191340803,
0.9947082859418444
],
"translation_xyz_m": [
0.01948586951276129,
0.06889041042895316,
1.0489728093762585
],
"reprojection_error_px": 0.08873372663232251
}
],
"candidate_diagnostics": {
"solved_candidate_count": 2,
"reprojection_candidate_count": 2,
"independent_tilt_candidate_count": 2,
"maximum_reprojection_error_px": 1.5,
"maximum_independent_tilt_deg": 75.0,
"minimum_reprojection_error_px": 0.05631830982299966,
"minimum_candidate_tilt_deg": 8.504262310381518,
"maximum_candidate_tilt_deg": 10.061504700361334,
"observation_stamp_ns": 1789373017897501233,
"branch_revision": 1,
"branch_status": "conflict_pending",
"branch_reason": "pose_branch_unconfirmed",
"branch_confirmation_count": 1,
"branch_frozen": true
},
"branch_corrections_total": 0
}
},
{
"kind": "pnp_branch_event",
"view": "front",
"image_stamp_ns": 1789373017930878824,
"tag_role": "front_base",
"tag_id": 0,
"reason": "pose_branch_unconfirmed",
"pnp_observation_evidence": {
"tag_role": "front_base",
"tag_id": 0,
"tag_size_m": 0.016,
"pose_source": "current_image",
"corners_xy": [
[
651.2874145507811,
851.705810546875
],
[
708.3966674804688,
845.7094116210938
],
[
701.5343017578125,
787.6038208007812
],
[
644.6768798828125,
793.9531250000001
]
],
"selected_pose": null,
"reprojection_valid_candidates": [
{
"quaternion_xyzw": [
0.003890939029632483,
0.0723875846158807,
-0.0582059228393556,
0.99566910604546
],
"translation_xyz_m": [
0.019486955902090344,
0.06891798815024941,
1.0494180790291907
],
"reprojection_error_px": 0.08163328008782858
},
{
"quaternion_xyzw": [
-0.07018371470015455,
-0.05760421277028976,
-0.05325691004080239,
0.994444418957092
],
"translation_xyz_m": [
0.019501897842959144,
0.06890773159582059,
1.049410573675387
],
"reprojection_error_px": 0.12399867839301451
}
],
"candidate_diagnostics": {
"solved_candidate_count": 2,
"reprojection_candidate_count": 2,
"independent_tilt_candidate_count": 2,
"maximum_reprojection_error_px": 1.5,
"maximum_independent_tilt_deg": 75.0,
"minimum_reprojection_error_px": 0.08163328008782858,
"minimum_candidate_tilt_deg": 8.314273514007814,
"maximum_candidate_tilt_deg": 10.418858251220792,
"observation_stamp_ns": 1789373017930878824,
"branch_revision": 1,
"branch_status": "conflict_pending",
"branch_reason": "pose_branch_unconfirmed",
"branch_confirmation_count": 2,
"branch_frozen": true
},
"branch_corrections_total": 0
}
},
{
"kind": "pnp_branch_event",
"view": "front",
"image_stamp_ns": 1789373017964203500,
"tag_role": "front_base",
"tag_id": 0,
"reason": "pose_branch_unconfirmed",
"pnp_observation_evidence": {
"tag_role": "front_base",
"tag_id": 0,
"tag_size_m": 0.016,
"pose_source": "current_image",
"corners_xy": [
[
651.2019653320314,
851.4394531249999
],
[
708.349365234375,
845.7827758789062
],
[
701.4730834960938,
787.6358032226564
],
[
644.6278686523438,
793.9785156249999
]
],
"selected_pose": null,
"reprojection_valid_candidates": [
{
"quaternion_xyzw": [
0.015547389407951088,
0.07097620670743443,
-0.05751186024699874,
0.9956972645814344
],
"translation_xyz_m": [
0.019476327145696467,
0.06893103415003812,
1.0497373401099155
],
"reprojection_error_px": 0.15922816946232976
},
{
"quaternion_xyzw": [
-0.08179270149397419,
-0.0561873622981887,
-0.05244234274300198,
0.993681405173668
],
"translation_xyz_m": [
0.019490603849034997,
0.0689175370110156,
1.049722140431075
],
"reprojection_error_px": 0.2064577346482914
}
],
"candidate_diagnostics": {
"solved_candidate_count": 2,
"reprojection_candidate_count": 2,
"independent_tilt_candidate_count": 2,
"maximum_reprojection_error_px": 1.5,
"maximum_independent_tilt_deg": 75.0,
"minimum_reprojection_error_px": 0.15922816946232976,
"minimum_candidate_tilt_deg": 8.333461835216385,
"maximum_candidate_tilt_deg": 11.38993872662255,
"observation_stamp_ns": 1789373017964203500,
"branch_revision": 1,
"branch_status": "conflict_pending",
"branch_reason": "pose_branch_unconfirmed",
"branch_confirmation_count": 3,
"branch_frozen": true
},
"branch_corrections_total": 0
}
},
{
"kind": "pnp_branch_event",
"view": "front",
"image_stamp_ns": 1789373017997253983,
"tag_role": "front_base",
"tag_id": 0,
"reason": "pose_branch_unconfirmed",
"pnp_observation_evidence": {
"tag_role": "front_base",
"tag_id": 0,
"tag_size_m": 0.016,
"pose_source": "current_image",
"corners_xy": [
[
651.0892944335936,
851.2770996093753
],
[
708.2705688476564,
845.88818359375
],
[
701.3729858398438,
787.6652832031248
],
[
644.5391845703123,
794.0059814453125
]
],
"selected_pose": null,
"reprojection_valid_candidates": [
{
"quaternion_xyzw": [
0.023056471882254036,
0.07254119338325239,
-0.05704579812544366,
0.9954656956837376
],
"translation_xyz_m": [
0.019440361452008358,
0.06889820121116787,
1.0492236406616988
],
"reprojection_error_px": 0.22416292552376008
},
{
"quaternion_xyzw": [
-0.0892589805271742,
-0.05776484561035559,
-0.05173711763178937,
0.9929850591353404
],
"translation_xyz_m": [
0.019454762778121373,
0.06888246787152717,
1.0492014615765388
],
"reprojection_error_px": 0.27421207829911554
}
],
"candidate_diagnostics": {
"solved_candidate_count": 2,
"reprojection_candidate_count": 2,
"independent_tilt_candidate_count": 2,
"maximum_reprojection_error_px": 1.5,
"maximum_independent_tilt_deg": 75.0,
"minimum_reprojection_error_px": 0.22416292552376008,
"minimum_candidate_tilt_deg": 8.7308314332582,
"maximum_candidate_tilt_deg": 12.206445788097424,
"observation_stamp_ns": 1789373017997253983,
"branch_revision": 1,
"branch_status": "conflict_pending",
"branch_reason": "pose_branch_unconfirmed",
"branch_confirmation_count": 4,
"branch_frozen": true
},
"branch_corrections_total": 0
}
},
{
"kind": "pnp_branch_event",
"view": "front",
"image_stamp_ns": 1789373018030961996,
"tag_role": "front_base",
"tag_id": 0,
"reason": "pose_branch_conflict",
"pnp_observation_evidence": {
"tag_role": "front_base",
"tag_id": 0,
"tag_size_m": 0.016,
"pose_source": "current_image",
"corners_xy": [
[
651.0183715820312,
851.0774536132814
],
[
708.2586669921877,
846.02001953125
],
[
701.3419189453124,
787.6656494140623
],
[
644.4960327148436,
794.0057373046875
]
],
"selected_pose": null,
"reprojection_valid_candidates": [
{
"quaternion_xyzw": [
0.030940978354305437,
0.07516598998187739,
-0.05644175675597389,
0.9950914821778057
],
"translation_xyz_m": [
0.019406210239914932,
0.06881287778423942,
1.0479804729911537
],
"reprojection_error_px": 0.3049068030194769
},
{
"quaternion_xyzw": [
-0.0970848585178656,
-0.06038259334163152,
-0.05081850378140816,
0.9921421028972232
],
"translation_xyz_m": [
0.019420932377868627,
0.06879463727498322,
1.04794854719117
],
"reprojection_error_px": 0.3585928916271403
}
],
"candidate_diagnostics": {
"solved_candidate_count": 2,
"reprojection_candidate_count": 2,
"independent_tilt_candidate_count": 2,
"maximum_reprojection_error_px": 1.5,
"maximum_independent_tilt_deg": 75.0,
"minimum_reprojection_error_px": 0.3049068030194769,
"minimum_candidate_tilt_deg": 9.324876196298892,
"maximum_candidate_tilt_deg": 13.130053999046243,
"observation_stamp_ns": 1789373018030961996,
"branch_revision": 1,
"branch_status": "frozen_conflict",
"branch_reason": "pose_branch_conflict",
"branch_confirmation_count": 5,
"branch_frozen": true
},
"branch_corrections_total": 0
}
}
]
}
@@ -0,0 +1,60 @@
{
"source": "calibration_output/O6_RIGHT_001/20260915_121857/raw_samples.jsonl",
"source_sha256": "3f89b5010ff5b225a49233bc6020467f8f3445f844348d4fd0db2ddd1d51957c",
"image_topic": "/o6_calibration/front/camera/image_rect",
"crop_origin_xy": [
600,
730
],
"purpose": "fixed Tag border occlusion regression, no geometry certification",
"commands": [
[
255.0,
255.0,
255.0,
255.0,
255.0,
255.0
],
[
255.0,
254.0,
255.0,
255.0,
255.0,
255.0
],
[
255.0,
23.0,
255.0,
255.0,
255.0,
255.0
],
[
255.0,
20.0,
255.0,
255.0,
255.0,
255.0
],
[
255.0,
15.0,
255.0,
255.0,
255.0,
255.0
],
[
255.0,
12.0,
255.0,
255.0,
255.0,
255.0
]
]
}
@@ -0,0 +1,22 @@
# O6 原始观测回归切片
两个 `o6_front_20260914_*_raw_replay.json.gz` 文件分别来自不同会话;不拼接零位、安装关系或图像,不作为整只手精度验收。
Gzip 只压缩 JSON,`mtime=0`;`records` 中每条记录与原始日志完全一致,未删字段或重算候选。
| 来源会话 | 保存内容 | 未提供的证据 |
| --- | --- | --- |
| `20260914_175815` | 正面拇指 pitch/IP 两个方向的 395 条原始观测、会话头、相机模型 | 新版归零准备运动;第四轮独立精度验收 |
| `20260914_192637` | 正面归零准备运动最终选用的 120 条原始帧、原初始化报告、会话头、相机模型 | 暂停后未发生的 pitch/IP 扫描;完整诊断采集;第四轮独立精度验收 |
原始日志 SHA-256:
- `175815`:`8bdbf216bd4135f1bac16dee0535a8b72ea0e6b0f31ab2b9a2e8cc4a83be9c0d`
- `192637`:`757ba1d7cccae4bdb93553b2735e94862bc74f57f153198e1a9d3eff76d45c8d`
`192637` 的切片按原 `motion_branch_initialization.source_image_stamps` 选择,并保留每帧原始哈希。
`175815` 的切片按 `kind=diagnostic_observation_frame`、`view=front`、`task_name=thumb_pitch_ip_front` 选择。
测试重新计算原角点的 IPPE 候选,分别验证原始观测覆盖和已接受关节样本覆盖;原零位不被重拟合。
完整本地日志存在时,还比较每条切片记录与原记录,并校验原日志哈希;缺少完整日志时,该额外核验显式跳过。
运行 `test_recorded_diagnostic_replay.py` 通过,只说明这些明确边界成立。
新版完整采集流程使用另行标识的模拟时钟集成测试;不会把模拟完成解释为这两个真实会话完整通过。
@@ -0,0 +1,182 @@
{
"scope": "stationary_fixed_tag_ambiguity_regression_not_accuracy_certificate",
"source_raw_sha256": "43f7aa037caf28decf2e729735f26ffabe5fd6369179b130fa59d884ce54e4b6",
"camera_model": {
"kind": "rectified_camera_model",
"view": "side",
"matrix_source": "CameraInfo.P[:3,:3]",
"width": 1624,
"height": 1240,
"raw_k": [
3701.9669310172562,
0.0,
780.38448956403,
0.0,
3708.0764820855165,
543.1934166854517,
0.0,
0.0,
1.0
],
"raw_d": [
-0.0855955821613016,
1.7771811866066576,
-0.009882528169757824,
-0.0018744565873629446,
0.0
],
"rectification_r": [
1.0,
0.0,
0.0,
0.0,
1.0,
0.0,
0.0,
0.0,
1.0
],
"projection_p": [
3719.39794921875,
0.0,
779.2527216851595,
0.0,
0.0,
3715.812255859375,
538.8889945124574,
0.0,
0.0,
0.0,
1.0,
0.0
],
"camera_matrix": [
[
3719.39794921875,
0.0,
779.2527216851595
],
[
0.0,
3715.812255859375,
538.8889945124574
],
[
0.0,
0.0,
1.0
]
],
"input_is_rectified": true
},
"observation": {
"kind": "pnp_branch_event",
"view": "side",
"image_stamp_ns": 1789384038002424192,
"tag_role": "side_base",
"tag_id": 3,
"reason": "pose_branch_unconfirmed",
"task_name": null,
"motion_phase": null,
"command_unit": "u8",
"command_vector": [
255.0,
255.0,
255.0,
255.0,
255.0,
255.0
],
"feedback_vector": [
254.0,
255.0,
254.0,
254.0,
254.0,
254.0
],
"state_image_sync_error_ms": 7.491799,
"timing": {
"received_stamp_ns": 1789384038027697599,
"history_snapshot_stamp_ns": 1789384038027907158,
"latest_feedback_stamp_ns": 1789384038009915991,
"latest_command_stamp_ns": 1789384038027461363
},
"pnp_observation_evidence": {
"tag_role": "side_base",
"tag_id": 3,
"tag_size_m": 0.016,
"pose_source": "current_image",
"corners_xy": [
[
635.7402954101564,
871.7483520507814
],
[
715.5008544921875,
872.2428588867189
],
[
716.2201538085936,
792.0438842773436
],
[
636.2169799804688,
791.7636718749999
]
],
"selected_pose": null,
"reprojection_valid_candidates": [
{
"quaternion_xyzw": [
-0.044633764301794464,
0.0076389447486132234,
0.0021611953202176335,
0.9989718728984152
],
"translation_xyz_m": [
-0.020686883190194915,
0.058714895217251775,
0.744562855591804
],
"reprojection_error_px": 0.10935170446797024
},
{
"quaternion_xyzw": [
-0.0341108338913104,
-0.03511406600381762,
0.003990533332137572,
0.9987930361309315
],
"translation_xyz_m": [
-0.02067953829092587,
0.05871663804033328,
0.7445618482013543
],
"reprojection_error_px": 0.12294261238764193
}
],
"candidate_diagnostics": {
"motion_managed": false,
"motion_selection_committed": false,
"solved_candidate_count": 2,
"reprojection_candidate_count": 2,
"independent_tilt_candidate_count": 2,
"maximum_reprojection_error_px": 1.5,
"maximum_independent_tilt_deg": 75.0,
"minimum_reprojection_error_px": 0.10935170446797024,
"minimum_candidate_tilt_deg": 5.190794593307594,
"maximum_candidate_tilt_deg": 5.612019732803669,
"observation_stamp_ns": 1789384038002424192,
"branch_revision": 0,
"branch_status": "initializing",
"branch_reason": "pose_branch_unconfirmed",
"branch_confirmation_count": 0,
"branch_frozen": false,
"motion_evidence_verified": false,
"motion_evidence_id": ""
},
"branch_corrections_total": 0
}
}
}

Some files were not shown because too many files have changed in this diff Show More