# UMI handheld gripper — ArUco markers (cad agent, 2026-07-07)

The handheld UMI gripper (smith300-derived, `umi_gripper.urdf` in the cad recovery tree) carries an 80mm
marker cube on its static body for scene-camera pose tracking. Same conventions as the fiducial exoskeleton
(`fiducial_exo.md`): **DICT_6X6_250**, print at 100% scale, no mirror-flips.

| Face | Board | IDs | Layout |
|---|---|---|---|
| TOP (+y in gripper/servo frame) | 3×3 GridBoard | **190–198** | 20 mm markers, 5 mm sep, 5 mm margin (80×80 sheet) |
| BACK (+x, away from fingers) | 3×3 GridBoard | **200–208** | 20 mm markers, 5 mm sep, 5 mm margin (80×80 sheet) |

Generated via `cv2.aruco.GridBoard((3,3), 0.020, 0.005, DICT_6X6_250, ids).generateImage(..., marginSize=...)`
— margin baked into the PNG (no manual scaling). Superseded: single markers 240/241 (2026-07-07, deprecated).
Sim textures verified: 9/9 detected per face in MuJoCo renders (mj_umi bundle).

- IDs chosen clear of existing allocations: exoskeleton arm1 217–225, arm2 226–234, smith300 arm base 100–108.
- Print sheets: `stl_transfers/umi_markers/aruco_umi_{top,back}_grid.png` (203.2 dpi embedded — print
  "actual size"; verify a marker measures 20±0.3 mm with calipers per the exo print rule).
- The cube's print STL has **full-face (80.4 mm) × 0.6 mm registration recesses** on those two faces plus an **8 mm corner
  notch** (deeper) — the sheet's marked corner goes into the notch corner; wrong orientation won't seat flat.
- Marker→gripper-frame transforms: cube AABB in the gripper (servo_0-of-gripper) frame is x 47..127,
  y −29..51, z ±40 (mm); marker centers = face centers. Exact `T_marker_in_gripper` derivable from
  `gnode_aruco_cube_shelled.stl` in the cad recovery tree when the detection side wants it.

Cross-agent: detection/PnP side is yam_calib's domain — this note is the cad-side spec handoff.


## smith300 arm base board (regenerated 2026-07-07, same IDs as the original allocation)
- 3×3 GridBoard, DICT_6X6_250, **IDs 100–108**, **42.29 mm markers, 10.57 mm sep, 6 mm margin** → 160×160 mm sheet. (Margin added 2026-07-07; supersedes the historic margin-0 / 45.7 mm layout — detection code must use the new constants: GridBoard((3,3), 0.0422857, 0.0105714, ...).)
- Sheet: `stl_transfers/arm_markers/aruco_arm_base_grid.png` (print actual size; marker calipers 42.3±0.5).
- Mounts flat on the detachable fiducial tray (Part B, `fiducial_mount.stl`) — board top faces up at table level.
- Sim: `stl_transfers/mj_arm/arm.xml` — textured board + position actuators; detection-verified in renders.


## Canonical constants module (2026-07-07)
`aruco_boards.py` (cad recovery tree + `stl_transfers/arm_markers/`) is THE source of truth for all board
specs + ID allocations. Import `board(ARM_BASE)` / `board(UMI_TOP)` / `board(UMI_BACK)` — never redefine
constants inline. Verified: `check_no_overlaps()` PASS across arm(100-108), UMI(190-198, 200-208),
exoskeleton(217-225, 226-234); every shipped PNG decode-checked against its registry IDs (9/9 each).


## UMI v2 wand single-slab board (2026-07-09)
- v2 gripper carries ONE board on its 120x80 slab (+x face, flat — no recess): **4x3 GridBoard,
  IDs 150-161**, 20mm markers, 5mm sep/margin. Sheet: `stl_transfers/umi_markers/aruco_umi_v2_grid.png`
  (print actual size; caliper a marker at 20±0.3). Glue orientation matters (no notch): match the sim
  render — ID 150 at the top-outer corner with the 120 side vertical.
- v1 cube boards (190-198/200-208) stay RESERVED while the printed v1 wand exists.
- Registry: `aruco_boards.py` UMI_V2. Sim: mj_umi_v2 bundle, 12/12 detection-verified.


**2026-07-12 scale fix (UMI v2 board):** the first printed run of `aruco_umi_v2_grid.png` had a letterbox
bug (markers ~18.95mm, not 20.0 — would bias PnP depth ~5%). Fixed sheets are marked "FIXED SCALE v2" on
the print page; markers exactly 20.0mm, pitch 25.0mm. DESTROY any old v2 sheet prints. Detection must build
the board from `aruco_boards.py` UMI_V2 — physical sheet now matches the constants exactly.