# O30 右手 V6：纯 URDF、普通线性映射

用户选择了可移植性优先的方案。V5 已完整备份，V6 不包含分段映射，自定义标签和查表都不参与运行。只通过标准 URDF 的关节 origin 和 limit 完成校准。

## 使用与迁移

```bash
./hands/O30/scripts/run_o30_right_mujoco_plan.sh
```

默认使用模型目录的 `linkerhand_o30_right_linear_calibrated.urdf`。

可直接迁移的目录是 `exports/O30_right_V6_linear/`，压缩包为 `exports/O30_right_V6_linear.zip`。包含相同 URDF、18 MB 网格、通道顺序、参考指令、说明和文件校验值。必需资产只有 URDF 与 meshes，其他文件用于说明与复现。

另一台电脑若接收 SDK 0～255，只需按关节名读取标准 limit：

```text
q = lower + (upper - lower) * clip(sdk, 0, 255) / 255
```

零位已经写入 origin，不再额外加偏移。不需要本项目的分段映射代码。如果输入本身为弧度，直接按关节名设置。20 路 SDK 顺序见迁移包 `joint_order.txt`；不要使用 URDF 元素顺序替代 SDK 顺序。

保证的是相同输入、基座位姿和模型下的运动学目标一致，不是不同仿真器/控制器的动力学轨迹完全一致。

## 本轮拟合与取舍

V5 中间指令与新端点不在同一直线上，所以纯线性模型不能逐点保留。V6 联合优化标准零位和行程参数，并用四组碰撞网格接触、指尖区域限制、原零位、旧照片、最新小指照片及姿态小改动先验约束。连杆尺寸、关节轴、质量、惯量及网格未修改。

正式三组初始值，每组逐步收紧四次接触约束，共 6,430 次目标评估；其中一组通过最终验收，其余两组未通过接触容差而被排除。完整搜索记录保存在模型目录 `o30_right_linear_calibration.json`。

六个满行程角度（包含零位偏移的原始模型角度）为：

- 无名指指根：90.50°。
- 无名指指尖：89.95°。
- 小指指根：93.63°。
- 小指中间：91.21°。
- 小指指尖：89.98°。
- 中指指尖：89.78°。

四组对指均满足 0.2 mm 仿真网格接触容差，实际残余间隙/穿透小于 0.001 mm；零位无检测到的穿透，各关节相对 V5 零位变化最大 0.71°。这些数字是仿真内部检查，不是真机精度。

**不再保证对指时每个中间关节角与 V5 相同。** 最大变化约 14.45°，主要涉及小指根部与中指末端等需要兼顾端点的关节；拇指部分关节也参与补偿。需要通过新旧对比图评估这一折中。

90° 端点目标仍来自上一轮照片的近似估计，原完整数组与相机参数未知。本版保留该不确定性，没有通过新增真机测量确定完整机械行程。

“其他通道使用已知零位”的六组端点均无检测到的穿透。“其他通道全 0”的假设中，旧版已有约 1.81～6.00 mm 穿透，本版约 2.09～6.49 mm；因此不把全 0 当作推荐张开姿态，也不声称该未知背景已与真机匹配。

## 验证与图像

`reports/o30_right_linear_calibration/`：

- `pinches_left.png`：四组对指及零位，左视图；上排 V5，下排 V6。
- `pinches_front.png`：相同姿态的正面比较。
- `endpoints.png`：六个单关节测试姿态，上排 V5，下排 V6。
- `validation.json`：拟合指标与实际模型验证。
- `portable_native_validation.json`：迁移到独立临时目录后的原生 URDF 加载验证。

已通过：

- 49 组实际运行模型与优化模型的导出一致性检查。
- 只读取标准 URDF origin、axis、limit 的独立运动学计算，与本机 MuJoCo 连杆位置差异小于 1e-13 m。
- 将迁移包复制到独立临时目录，通过 MuJoCo 原生 URDF 加载器加载，不导入本项目任何映射代码；37 组普通线性输入与本机姿态一致，位置差异小于 1e-13 m。
- 七项回归测试，包括四组 ROS 消息对指、V5 兼容、非法映射拒绝、切回线性时清除分段映射、按纯 URDF 上下限换算。

这些是本机独立加载路径的验证，并非已经在另一台物理电脑实测。关节范围内随机输入只验证映射一致，不证明全运动路径无碰撞。

```bash
O30_RIGHT_PREPARE_ONLY=1 ./hands/O30/scripts/run_o30_right_mujoco_plan.sh
OPENBLAS_NUM_THREADS=1 venv/bin/python tools/o30_right_calibration/fit_linear.py --check --render
source /opt/ros/jazzy/setup.bash
PYTHONPATH="$PWD/venv/lib/python3.12/site-packages:$PYTHONPATH" python3 tools/o30_right_calibration/test_calibration.py
```

重新拟合：

```bash
OPENBLAS_NUM_THREADS=1 venv/bin/python tools/o30_right_calibration/fit_linear.py --fit --starts 3
O30_RIGHT_PREPARE_ONLY=1 ./hands/O30/scripts/run_o30_right_mujoco_plan.sh
venv/bin/python tools/o30_right_calibration/fit_linear.py --check --render
```

重新拟合后若要迁移，应更新 exports 内的副本，当前压缩包是本次已验证的 V6 快照。

## V5 备份与切换

完整备份：`backups/o30_v5_piecewise_20260921_142809/`，含模型、网格、运行脚本、桥接/映射代码、标注、拟合工具与报告。65 个文件的 SHA256 校验通过，清单为 `manifest.json`。

历史说明保留在 `README_v5.md`。原 V5 URDF/JSON 未覆盖，运行中的 V5 XML另存为 `linker_hand_o30_right_endpoint_v5.xml`。

一键运行 V5（会自动加载其分段映射）：

```bash
./hands/O30/legacy/run_o30_right_v5_piecewise.sh
```

恢复 V6：

```bash
./hands/O30/scripts/run_o30_right_mujoco_plan.sh
```

代码保留对旧映射格式的兼容仅用于回退；V6 模型不含映射节点，已验证运行时分段表为空。