制定 Autocal 运动与多点标定修正计划
明确姿态选解、接触高度、旧姿态和多点分析的任务与验收证据。文档门禁通过，方案尚未实施。
This commit is contained in:
ykcheungab
@@ -0,0 +1,112 @@
|
|||||||
|
# Autocal 运动与多点标定修正计划
|
||||||
|
|
||||||
|
状态：待实施，2026-10-14。审查基准：`orisys-app` 的 `dc5a6f8`，范围为 `d06501d..dc5a6f8`。本文件是工程师任务清单和后续复查依据，不表示实机问题已经修复。整体范围沿用[阶段一计划](implementation-plan.zh.md)，数据含义以[标定数据格式](calibration-data-format.zh.md)为准。
|
||||||
|
|
||||||
|
## 已知事实与待确认项
|
||||||
|
|
||||||
|
用户确认 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`；实机误差阈值另由设备负责人确定。
|
||||||
|
|
||||||
|
更新[逆解说明](inverse-kinematics.md)中的旋转、高度和行程描述；修正其中把 `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` 目录：
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
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 获得通过。
|
||||||
Reference in New Issue
Block a user