orisys-app/apps/autocal/docs/motion-correction-plan.zh.md

Autocal 运动与多点标定修正计划

状态：待实施，2026-10-14。审查基准：orisys-app 的 dc5a6f8，范围为 d06501d..dc5a6f8。本文件是工程师任务清单和后续复查依据，不表示实机问题已经修复。整体范围沿用阶段一计划，数据含义以标定数据格式为准。

已知事实与待确认项

用户确认 yaw 台承载传感器，左侧主要表现为 pitch 方向不符合预期。当前链 R_pitch @ R_yaw 与这一叠放关系相符，不能据此交换矩阵顺序。执行层没有按测点左右反转 pitch，反号来自求解器选取不同的逆解分支。

截图显示值经舍入；以下为按三位小数法向重新归一化后的离线结果，不是实机测量：

测点	sensor XYZ（mm）	sensor 法向	当前选解 yaw/pitch	另一等价解 yaw/pitch
右	4.872, 5.444, 16.176	0.595, 0.673, 0.439	+36.42° / −47.69°	−143.58° / +47.69°
左	−2.698, 5.186, 18.228	−0.343, 0.699, 0.627	−61.32° / +45.64°	+118.68° / −45.64°

两组分支都能在现有模型中对准法向。只反转左点 pitch 会留下约 91° 误差。修正朝上判断也不保证默认选解变成负 pitch：必须另行确认平台允许的姿态分支。

已确认缺陷	位置与后果
朝上参考错误	motion/kinematics.py::uprightness 用平台 Y 判断朝上，错误标记候选姿态
接触高度错误	PlatformStack.solve 计算了旋转后的 landed，却把旋转前 Z 传给执行入口
姿态缓存过期	ui/multipoint_panel.py::_align 对已有可达姿态不重新求解，安装或工具位置变化后可能执行旧目标
多点分析断开	session_review.py 拒绝 autocal-multipoint-1.0，新采集不能进入既有复核界面

截图右点的 Y 为 +16.176，而当前零安装角、零 Y 偏移下应为 −16.176。先核对截图对应版本、当时设置与表格是否更新，不从这一异常直接推出轴翻转。

任务顺序与分工

建议一名熟悉 Autocal 的工程师负责软件，一名平台负责人参加坐标确认和实机验收。任务 1→2→3 是运动修正链；任务 4 在原始数据含义确认后可独立开展。当前不启动代理，也不包含自动力闭环或硬件驱动改写。

完成	任务	依赖	估计人时
[ ]	0：固定坐标和实机约定	无	2–3
[ ]	1：修正姿态判断和选解	0	4–6
[ ]	2：统一接触高度与执行目标	0、1	4–6
[ ]	3：消除旧姿态执行	1、2	3–4
[ ]	4：接通多点记录复核	多点字段确认	6–8
[ ]	5：端到端验收和交接	1–4	3–4

软件和离线验证预计 22–31 人时，约单人 3–4 个工作日；额外预留 2–4 小时设备联调，不含硬件故障等待。估算需根据任务 0 的测量结果调整。

0：先固定坐标约定

记录传感器、yaw、pitch、平台 XY 和压头 Z 的零位与正方向，实际旋转中心、安装偏移、工具位置和当前驱动器映射。区分台体旋转轴和传感器自身坐标；不要用“看起来向左”代替正方向定义。实测显示模型缺少旋转中心偏移时，再补对应几何量。

交付一张坐标图、参数快照和左右点记录。每点保存 UV、XYZ、法向、两个候选角、选解理由、最终五轴目标、控制器反馈与照片。核对右点 Y 异常。实机动作须由平台负责人先明确设备、无接触间隙、角度/行程边界和停机条件；本计划本身不授权动作。

1：修正朝上判断和选解

修改 motion/kinematics.py，补充 test_kinematics.py 与 test_ik_analytical.py。

• 朝上参考来自真正的安装后名义朝上方向，在同一坐标系中比较；默认映射下为平台 +Z，而不是平台 +Y。
• 候选先满足方向、残差容差、行程和实机约定，再决定分支。等价解不因浮点残差的微小差异改变选择。若两解均允许，采用稳定且有说明的选择规则；需要固定接近姿态时，由平台负责人确认规则，不按 UV 左右硬编码符号。
• 测试名义法向、左右截图、中心/边缘和行程边界。用独立旋转矩阵检查 R @ n 指向 +Z，角误差不大于 1e-5°，并验证平台朝上向量。截图角度允许因舍入与界面值相差 0.1°。

在界面显示所选分支及理由，无法满足约定时拒绝执行。不要仅让原测试保持通过；新回归须在审查基准上失败。

2：统一接触高度与执行目标

修改 PlatformStack.solve 和两个 UI 执行入口，补充 test_kinematics.py、test_pose_move.py。

• 分开表示安装后、旋转前的点与最终接触点。XY 平移后，最终点应落在工具 XY；接触高度取旋转后坐标。默认偏移 (0,0,8) 下，两截图的旋转后 Z 约为 19.051 和 21.578 mm，不是 13.444 和 13.186 mm。
• 明确接触高度到压头轴绝对目标的关系，包括机械零位和工具高度。只有该关系确认后才生成运动目标；不要把几何 Z 直接视为已标定的控制器零位。保留接触高度、无接触预定位和加载深度的不同含义。
• 预览、目标表、确认框和执行计划使用同一求解结果。以非零安装偏移、安装角和工具 XY 测试，独立计算坐标误差应小于 1e-6 mm；实机误差阈值另由设备负责人确定。

更新逆解说明中的旋转、高度和行程描述；修正其中把 arccos 称为正负方向不可区分的说法。不要把单纯改变多轴下发顺序当作修正机械旋转链。

3：执行前重新求解测点

修改 ui/multipoint_panel.py 和必要的 SiteSpec 状态，新增对应 UI 回归测试。

• 每次对准前按当前几何和安装设置重新求解，而不是只看缓存的 in_range。优先直接复用现有快速求解器，暂不建立第二套缓存失效机制。
• 几何版本变化时不能拿旧 UV 映射直接执行；旧 XYZ、法向和当前映射不一致时要求重新确认测点。新的目标须重新经过现有 MotionService 行程与连接检查。
• 修改安装 X/Y/Z、安装角和工具位置后，确认框及实际提交的目标都更新；无解、越界或非有限值时不发送命令。记录当前求解参数及目标，保持期间不能对准其他点。

数据记录留在 Autocal，纯几何计算留在 kinematics，轴单位和驱动映射留在 motion service。UI 不自行复制矩阵、反转轴符号或导入 Studio 私有模块。

4：接通多点数据复核

修改 session_review.py 的读取入口及需要的复核 UI；复用既有保持窗口统计、诊断和拟合能力，不另建一套分析器。

• 将 autocal-multipoint-1.0 的实际目录、trial、参考窗口和录像索引转换为既有分析输入。先确认时间基准、力单位、模拟标记及帧来源；缺失字段显式报告，不补成有效零值。
• 全新进程打开两个测点、每点两个 trial 的会话，显示采集覆盖、有效窗口、加载/卸载曲线和初步法向灵敏度。保持原有 finger 会话读取行为。
• 未完成 trial、模拟数据、缺失视频或无效参考不得产生正式标定结论。分析结果写入 derived，原始文件哈希不变。增加完整、缺失、中止及原格式的回归样本。

当前拟合仍为诊断结果。本任务不自动写回 SDK 标定系数，也不引入新采集格式；确有字段歧义时先更新数据契约并说明旧记录的解释限制。

5：验收与后续复查

检查点 A：任务 1–3 完成，先审查差异、离线几何证明和 mock 下发记录，再进入设备联调。检查点 B：任务 4–5 完成，从采集目录重开到图表的完整链通过后交接。

工程师提交以下证据供后续复查：

证据	要求
代码差异	基准/完成提交、修改清单、坐标与分支决策理由；未涉及的历史缺陷单独说明
回归	新测试在旧代码上的失败结果、修后结果、实际收集和跳过数量
运动链	两个截图点与至少三个边界点：输入→候选→选解→几何接触点→五轴目标→单位换算→mock 下发；不得通过实机运行测试自动化
实机	有授权的低速无接触核对，比较正负 pitch、非零 yaw 和零位；按已确定阈值记录位置、姿态与反馈，不用离线残差替代测量
数据	脱敏多点会话、录像/索引、重开截图、有效性理由和拟合结果；原始数据哈希

复查将重点检查独立预期值、分支选择、Z 零位关系、旧姿态、失败时是否仍下发，以及新旧数据是否都可复核。未提供设备证据时只能验收软件，不能宣布实机错向已修复。完成后提供提交或差异和证据目录；复查需由用户再次发起，不安排自动监控。

从 app 根运行首轮相关测试；每次使用新的 --basetemp 目录：

cd D:\orisys_ws\orisys-app
& .venv-build/Scripts/python.exe -m pytest apps/autocal/tests/test_kinematics.py apps/autocal/tests/test_ik_analytical.py apps/autocal/tests/test_pose_move.py apps/autocal/tests/test_multipoint.py apps/autocal/tests/test_session_review.py apps/autocal/tests/test_record_overview.py -p no:cacheprovider --basetemp=.scratch/autocal-motion-fix/pytest-01
& .venv-build/Scripts/python.exe tools/lint_gate.py

新增 UI 回归加入上述命令；若修改共用录制入口，追加对应 shared record 测试。文档门禁使用工作区真实解释器，按 AUTHORING 执行，不通过扩大 baseline 获得通过。