把当前控制栈收成一份可克隆的源码：腕部看不见时用顶视一次定到基座，二阶段对孔和手外标定跟着进同一份树。

现场 site.yaml、权重和编译产物仍不入库；模板只留占位符。

Co-authored-by: Cursor <cursoragent@cursor.com>

handeye/README.md

@@ -16,7 +16,7 @@
 | 模式 | 相机装在哪 | 解出的 X 是什么 | 本项目的用法 |
 |------|-----------|----------------|-------------|
 | `eye_in_hand` | **相机装在机械臂末端（法兰/手腕）上** | 相机 → 法兰 | **D405 腕部相机（当前使用）** |
-| `eye_to_hand` | **相机固定在旁边不动** | 相机 → 机械臂基座 | D435 顶置相机（预留） |
+| `eye_to_hand` | **相机固定在旁边不动** | 相机 → 机械臂基座 | D435 顶置相机 |
 
 **怎么选**：看相机是不是跟着机械臂动。
 - 跟着动 → `eye_in_hand`
@@ -50,40 +50,36 @@ handeye/
    `handeye_workdir`。两条臂若共用一个工作目录，先标定的那份采点会被后
    标定的覆盖，而症状是"标定结果突然变得很差"，不容易联想到是目录冲突。
 
-**命名约定**：`<臂号>_<模式>.yaml`
-- 臂号 = Flexiv 序列号后两位（`Rizon4-063989` → `89`，`Rizon4-063991` → `91`）
-- 模式 = `eye_in_hand` | `eye_to_hand`
-
-运行时谁读结果：`config/site.yaml` 里 `robots[89].paths.handeye_file` 指向
-`handeye/results/89_eye_in_hand.yaml`，再由各 launch 文件发布成静态 TF。
-**换模式 = 把 site.yaml 里那个路径改成 `_eye_to_hand` 那份**，不需要改代码。
+**命名约定**：
+- 眼在手上：`<臂号>_eye_in_hand.yaml`（`paths.handeye_file` 指向它）
+- 眼在手外：`<臂号>_<相机>_eye_to_hand.yaml`（S03 按这个名字自己找，
+  不要改 `paths.handeye_file`）
+- 臂号 = Flexiv 序列号后两位（`Rizon4-063989` → `89`）
+- 示教点：`<臂号>_<模式>.yaml`（两种模式的关节角完全不同，分开存）
 
 ---
 
 ## 3. 标定板（最容易出错的地方）
 
-当前使用的板：
+两种装法用**两块不同的物理板**，尺寸按模式分开写，不能共用一组键：
 
-```
-内角点  8 列 × 11 行      (注意是"内角点"，不是方格数！)
-方格边长 15 mm (0.015 m)
-```
+| 模式 | 物理板 | 内角点（列 × 行） | 方格边长 | `site.yaml` 里的位置 |
+|------|--------|-------------------|----------|----------------------|
+| `eye_in_hand` | A5（腕部相机看台面） | 8 × 11 | 15 mm (`0.015`) | `handeye.boards.eye_in_hand` |
+| `eye_to_hand` | A4（板装在法兰上） | 11 × 8 | 20 mm (`0.020`) | `handeye.boards.eye_to_hand` |
 
-**这个尺寸必须三处一致**，否则标定结果会系统性偏错：
-
-| 位置 | 内容 |
-|------|------|
-| `config/site.yaml` → `handeye.board_cols/rows/square_size_m` | 8 / 11 / 0.015 |
-| `handeye/calibrate.yaml` | `board_cols/rows/square_size_m` |
-| `src/.../handeye_calibrate.py` 的参数默认值 | 代码兜底 |
-
-> ⚠️ **历史上这里出过问题**：曾经三处分别写着 `9×6/0.025`、`11×16/0.011`、
-> `8×11/0.015`，谁生效取决于覆盖顺序。症状是"标定流程跑得很顺、不报错，
-> 但结果明显不对"，非常难查。现已统一为 `8×11/0.015`。
-> **换板子时，请把上面三处一起改。**
+权威只有 `config/site.yaml` 的 `handeye.boards.<模式>`。`run_handeye.sh` 按
+`--mode` 取对应那一组，用 `-p` 传给节点。`handeye/calibrate.yaml` 和节点默认值
+只是兜底（眼在手上那块板），**没配过的模式会被脚本当场拦下**，不会静默用兜底
+尺寸去标（那会让结果系统性偏，还不报错）。
 
 怎么看内角点：把棋盘当成一张网格，**数内部的黑白交叉点**，
-是「方格数 − 1」。比如 A5 板上画了 9×12 个格子 → 内角点是 8×11。
+是「方格数 − 1」。A5 板上画了 9×12 个格子 → 内角点 8×11；
+A4 板上画了 12×9 个格子 → 内角点 11×8。列/行顺序不用纠结，检测端两种顺序都会试。
+
+> ⚠️ **历史上这里出过问题**：曾经三处分别写着 `9×6/0.025`、`11×16/0.011`、
+> `8×11/0.015`，谁生效取决于覆盖顺序。后来又把两块板合成一组键，于是标眼在手外
+> 时静默用了 A5 的 15 mm。症状都是"标定流程跑得很顺、不报错，但结果明显不对"。
 
 ---
 
@@ -97,7 +93,8 @@ handeye/
 bash ~/ros2/scripts/run_handeye.sh teach --arm 89
 ```
 
-会弹出实时预览窗口，里面能看到标定板有没有被识别到。操作：
+会弹出实时预览窗口（**只显示画面，不做棋盘检测**——真正的角点稳定判定在
+`calibrate` 那一步）。操作：
 
 | 按键 | 作用 |
 |------|------|
@@ -190,20 +187,25 @@ bash ~/ros2/scripts/run_handeye.sh teach --ros --auto-solve --arm 89
 ### 切换 eye-in-hand / eye-to-hand
 
 ```bash
-# 用腕部相机（默认）
+# 用腕部相机 + A5 板（默认，板放台面不动）
 bash ~/ros2/scripts/run_handeye.sh --arm 89 teach
 
-# 用固定相机
-bash ~/ros2/scripts/run_handeye.sh --arm 89 teach --mode eye_to_hand
+# 用固定相机 + A4 板（板必须装到法兰上，相机不动）
+# 前置：另开终端 bash ~/ros2/scripts/run_camera_d435.sh --preview
+bash ~/ros2/scripts/run_handeye.sh --arm 89 teach --mode eye_to_hand --points 12
 bash ~/ros2/scripts/run_handeye.sh --arm 89 merge --mode eye_to_hand
 bash ~/ros2/scripts/run_handeye.sh --arm 89 calibrate --mode eye_to_hand
 ```
 
-`--mode` 会把读写的文件切到 `<臂号>_<模式>.yaml`，所以：
+`--mode` 会同时切：标定板、相机、示教点文件、结果文件。所以：
 
 - 两种模式**互不覆盖**，可以分别标定、共存
-- 跑完想切换使用，改 `config/site.yaml` 里 `robots[89].paths.handeye_file`
-  指向对应那份即可，代码不用动
+- 眼在手上结果：`handeye/results/<臂号>_eye_in_hand.yaml`（`T` = 相机 → 法兰）
+- 眼在手外结果：`handeye/results/<臂号>_<相机>_eye_to_hand.yaml`
+  （`T` = 相机 → 这条臂的基座；双臂共用一台 D435 时必须按臂分开）
+- **不要**把 `paths.handeye_file` 改成眼在手外那份 —— 那条路径是腕部相机
+  （S05 精拍定位）用的。手外那份由 `gauge_assembly.launch` 按名字自己找，
+  并以 **基座 ← 相机** 发布 TF（不是法兰 ← 相机）
 
 传了非法模式会立刻报错并退出（不会悄悄退回默认值 —— 那会导致"以为标的是
 eye-to-hand、其实算的是 eye-in-hand"这种最难查的错）。