5.5 KiB
O30 右手 V6：纯 URDF、普通线性映射
用户选择了可移植性优先的方案。V5 已完整备份，V6 不包含分段映射，自定义标签和查表都不参与运行。只通过标准 URDF 的关节 origin 和 limit 完成校准。
使用与迁移
./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：
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 上下限换算。
这些是本机独立加载路径的验证，并非已经在另一台物理电脑实测。关节范围内随机输入只验证映射一致，不证明全运动路径无碰撞。
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
重新拟合：
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（会自动加载其分段映射）：
./hands/O30/legacy/run_o30_right_v5_piecewise.sh
恢复 V6：
./hands/O30/scripts/run_o30_right_mujoco_plan.sh
代码保留对旧映射格式的兼容仅用于回退；V6 模型不含映射节点，已验证运行时分段表为空。