diff --git a/docs/superpowers/plans/2026-06-03-cross-camera-tag-alignment.md b/docs/superpowers/plans/2026-06-03-cross-camera-tag-alignment.md
new file mode 100644
index 0000000..05bf7c4
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-03-cross-camera-tag-alignment.md
@@ -0,0 +1,1059 @@
+# Cross-camera tag overlay + Nuwa→frontale alignment — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Detect ArUco tags on both the Nuwa (wrist) and D435i (front) cameras with per-camera colors, and add a persistent Umeyama similarity calibration that overlays the Nuwa point cloud onto the D435i cloud via a tag seen by both.
+
+**Architecture:** Backend gains a pure `umeyama_similarity` helper, a camera-agnostic `_detect_tags_on`, a combined `GET /tags` endpoint, and a `POST /align` endpoint that fits + persists the matrix to `config.yaml > pose_3d.cross_camera`. The vanilla-JS Pose 3D frontend generalizes the existing front-tag overlay to both cameras and renders the Nuwa cloud through the D435i transform pipeline when the calibration is enabled.
+
+**Tech Stack:** Python 3.10 / FastAPI / numpy / pytest (backend); vanilla JS + Three.js (frontend, no JS test runner — `web/` is served statically, no linter).
+
+**Spec:** `docs/superpowers/specs/2026-06-03-cross-camera-tag-alignment-design.md`
+
+**Note on JS testing:** there is no JavaScript test harness in this repo and the system `node` is too old to even parse the optional-chaining already used throughout `web/pose_3d.js`. Frontend tasks therefore use **manual browser verification** (reload `http://localhost:8890`, open the Pose 3D tab). Keep edits small and self-contained.
+
+---
+
+## Task 1: `umeyama_similarity` helper (geometry.py)
+
+**Files:**
+- Modify: `src/presa_mano/geometry.py` (append new function)
+- Test: `tests/test_geometry_umeyama.py` (create)
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/test_geometry_umeyama.py`:
+
+```python
+"""Unit test per umeyama_similarity (absolute orientation con scala)."""
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from presa_mano.geometry import umeyama_similarity, rpy_deg_to_quaternion_xyzw, quat_xyzw_to_R
+
+
+def _known_transform():
+ # scala 1.5, rotazione nota, traslazione nota
+ R = quat_xyzw_to_R(rpy_deg_to_quaternion_xyzw(10.0, -20.0, 35.0))
+ s = 1.5
+ t = np.array([0.3, -0.1, 0.2])
+ return s, R, t
+
+
+def test_recovers_known_similarity():
+ s, R, t = _known_transform()
+ rng = np.random.default_rng(0)
+ src = rng.normal(size=(8, 3))
+ dst = (s * (R @ src.T)).T + t
+
+ s_hat, R_hat, t_hat, rmse = umeyama_similarity(src, dst)
+
+ assert abs(s_hat - s) < 1e-6
+ assert np.allclose(R_hat, R, atol=1e-6)
+ assert np.allclose(t_hat, t, atol=1e-6)
+ assert rmse < 1e-6
+
+
+def test_forbids_reflection():
+ # Anche con dati che potrebbero indurre una riflessione, det(R)=+1
+ rng = np.random.default_rng(1)
+ src = rng.normal(size=(5, 3))
+ dst = rng.normal(size=(5, 3))
+ _, R_hat, _, _ = umeyama_similarity(src, dst)
+ assert np.linalg.det(R_hat) > 0
+
+
+def test_raises_on_too_few_points():
+ with pytest.raises(ValueError):
+ umeyama_similarity(np.zeros((2, 3)), np.zeros((2, 3)))
+
+
+def test_raises_on_degenerate_points():
+ # tutti i punti coincidenti → varianza nulla
+ src = np.ones((4, 3))
+ dst = np.ones((4, 3)) * 2.0
+ with pytest.raises(ValueError):
+ umeyama_similarity(src, dst)
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/test_geometry_umeyama.py -v`
+Expected: FAIL with `ImportError: cannot import name 'umeyama_similarity'`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Append to `src/presa_mano/geometry.py`:
+
+```python
+def umeyama_similarity(src: np.ndarray, dst: np.ndarray):
+ """Fit dst ≈ s·R·src + t (Umeyama 1991, con scala uniforme).
+
+ src, dst: (N,3) array di punti corrispondenti.
+ Ritorna (scale: float, R: (3,3), t: (3,), rmse: float in unità di dst).
+ Solleva ValueError se N<3 o il set è degenere (varianza nulla).
+ """
+ src = np.asarray(src, dtype=float).reshape(-1, 3)
+ dst = np.asarray(dst, dtype=float).reshape(-1, 3)
+ if src.shape != dst.shape:
+ raise ValueError(f"shape mismatch: {src.shape} vs {dst.shape}")
+ n = src.shape[0]
+ if n < 3:
+ raise ValueError(f"servono almeno 3 punti, ricevuti {n}")
+
+ mu_src = src.mean(axis=0)
+ mu_dst = dst.mean(axis=0)
+ src_c = src - mu_src
+ dst_c = dst - mu_dst
+
+ var_src = (src_c ** 2).sum() / n
+ if var_src < 1e-12:
+ raise ValueError("punti src degeneri (varianza nulla)")
+
+ cov = (dst_c.T @ src_c) / n
+ U, D, Vt = np.linalg.svd(cov)
+ S = np.eye(3)
+ if np.linalg.det(U) * np.linalg.det(Vt) < 0:
+ S[2, 2] = -1.0 # vieta riflessioni
+ R = U @ S @ Vt
+ scale = float((D * np.diag(S)).sum() / var_src)
+ t = mu_dst - scale * (R @ mu_src)
+
+ pred = (scale * (R @ src.T)).T + t
+ rmse = float(np.sqrt(((pred - dst) ** 2).sum(axis=1).mean()))
+ return scale, R, t, rmse
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `uv run pytest tests/test_geometry_umeyama.py -v`
+Expected: 4 passed.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/presa_mano/geometry.py tests/test_geometry_umeyama.py
+git commit -m "feat(geometry): umeyama_similarity (rot+trasl+scala uniforme)"
+```
+
+---
+
+## Task 2: Camera-agnostic tag detection + `GET /api/pose_3d/tags`
+
+**Files:**
+- Modify: `src/presa_mano/api/pose_3d_routes.py` (extract helper from `get_front_tags`, add `/tags`)
+- Test: `tests/test_pose_3d_tags.py` (create)
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/test_pose_3d_tags.py`:
+
+```python
+"""Test del nuovo endpoint multi-camera GET /api/pose_3d/tags."""
+from __future__ import annotations
+
+from unittest.mock import patch, MagicMock
+
+from fastapi.testclient import TestClient
+
+from presa_mano.main import app
+
+client = TestClient(app)
+
+
+def _fake_camera(corner_depth_m=0.32):
+ cam = MagicMock()
+ cam.intrinsics.return_value = {
+ "rgb": {"fx": 600.0, "fy": 600.0, "cx": 320.0, "cy": 240.0}
+ }
+ cam.rgb_url.return_value = "http://cam/rgb.png"
+
+ def _measure(u, v, radius=2):
+ # punto 3D fittizio coerente; z costante → quad planare
+ return {"point_m": {"x": u / 1000.0, "y": v / 1000.0, "z": corner_depth_m},
+ "depth_mm": int(corner_depth_m * 1000)}
+ cam.measure.side_effect = _measure
+ return cam
+
+
+def _fake_marker(found_ids):
+ mk = MagicMock()
+ found = [{
+ "id": i,
+ "corners": [[100, 100], [140, 100], [140, 140], [100, 140]],
+ } for i in found_ids]
+ mk.detect_url.return_value = {"found": found, "not_found": []}
+ return mk
+
+
+def test_tags_returns_both_cameras():
+ with patch("presa_mano.api.pose_3d_routes._deps.nuwa") as nuwa_f, \
+ patch("presa_mano.api.pose_3d_routes._deps.front_camera") as front_f, \
+ patch("presa_mano.api.pose_3d_routes._deps.marker") as mk_f:
+ nuwa_f.return_value = _fake_camera()
+ front_f.return_value = _fake_camera()
+ mk_f.return_value = _fake_marker([5])
+ r = client.get("/api/pose_3d/tags?ids=0-9")
+ assert r.status_code == 200
+ body = r.json()
+ assert set(body["cameras"].keys()) == {"nuwa", "d435"}
+ assert body["cameras"]["nuwa"]["frame"] == "nuwa_rgb_optical"
+ assert body["cameras"]["d435"]["frame"] == "d435_rgb_optical"
+ assert body["cameras"]["nuwa"]["tags"][0]["id"] == 5
+ assert body["cameras"]["d435"]["tags"][0]["id"] == 5
+
+
+def test_tags_one_camera_offline_reports_error():
+ with patch("presa_mano.api.pose_3d_routes._deps.nuwa") as nuwa_f, \
+ patch("presa_mano.api.pose_3d_routes._deps.front_camera") as front_f, \
+ patch("presa_mano.api.pose_3d_routes._deps.marker") as mk_f:
+ nuwa = MagicMock()
+ nuwa.intrinsics.side_effect = RuntimeError("nuwa down")
+ nuwa_f.return_value = nuwa
+ front_f.return_value = _fake_camera()
+ mk_f.return_value = _fake_marker([5])
+ r = client.get("/api/pose_3d/tags?ids=0-9")
+ assert r.status_code == 200
+ body = r.json()
+ assert body["cameras"]["nuwa"]["tags"] == []
+ assert "error" in body["cameras"]["nuwa"]
+ assert body["cameras"]["d435"]["tags"][0]["id"] == 5
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/test_pose_3d_tags.py -v`
+Expected: FAIL with 404 (endpoint `/tags` not registered yet).
+
+- [ ] **Step 3: Refactor `get_front_tags` into a helper + add `/tags`**
+
+In `src/presa_mano/api/pose_3d_routes.py`, replace the whole `get_front_tags` function (currently `@router.get("/front_tags") def get_front_tags(...)`, lines ~274-391) with the extracted helper + two endpoints. The body of the per-camera measurement logic is moved verbatim into `_detect_tags_on`:
+
+```python
+def _detect_tags_on(client, frame_label: str, ids: str,
+ probe_size_mm: float = 40.0) -> list[dict]:
+ """Detect ArUco su `client` (qualsiasi NuwaClient) + misura 3D dei corner
+ via depth. Schema per-tag identico al vecchio front_tags."""
+ mk = _deps.marker()
+ intr = client.intrinsics()
+ rgb = (intr or {}).get("rgb") or {}
+ if not rgb or "fx" not in rgb:
+ raise RuntimeError(f"intrinsics rgb mancanti: {intr!r}")
+ K = {
+ "camera_matrix": [
+ [float(rgb["fx"]), 0.0, float(rgb["cx"])],
+ [0.0, float(rgb["fy"]), float(rgb["cy"])],
+ [0.0, 0.0, 1.0],
+ ],
+ "dist_coeffs": [
+ float((rgb.get("distortion") or {}).get(k, 0.0))
+ for k in ("k1", "k2", "p1", "p2", "k3")
+ ],
+ }
+ id_list = _parse_id_range(ids)
+ markers = [{"id": int(i), "size_mm": float(probe_size_mm)} for i in id_list]
+ det = mk.detect_url(markers=markers, image_url=client.rgb_url(), intrinsics=K)
+
+ tags_out: list[dict[str, Any]] = []
+ for m in det.get("found", []):
+ corners = m.get("corners") or []
+ if len(corners) != 4:
+ continue
+ pts3d: list[list[float]] = []
+ depths: list[Optional[int]] = []
+ try:
+ for (u, v) in corners:
+ md = client.measure(int(round(u)), int(round(v)), radius=2)
+ pt = (md or {}).get("point_m") or {}
+ d_mm = (md or {}).get("depth_mm")
+ if not pt or d_mm in (None, 0):
+ pts3d.append([float("nan")] * 3)
+ depths.append(None)
+ else:
+ pts3d.append([float(pt["x"]), float(pt["y"]), float(pt["z"])])
+ depths.append(int(d_mm))
+ cu = sum(c[0] for c in corners) / 4.0
+ cv = sum(c[1] for c in corners) / 4.0
+ cmd = client.measure(int(round(cu)), int(round(cv)), radius=4)
+ cpt = (cmd or {}).get("point_m") or {}
+ center3d = ([float(cpt["x"]), float(cpt["y"]), float(cpt["z"])]
+ if cpt else [float("nan")] * 3)
+ except Exception as e:
+ log.warning("tags(%s): measure failed for id=%s: %s",
+ frame_label, m.get("id"), e)
+ continue
+
+ valid_d = [d for d in depths if d is not None]
+ if len(valid_d) >= 3:
+ sd = sorted(valid_d)
+ median_d = (sd[len(sd)//2 - 1] + sd[len(sd)//2]) / 2 if len(sd) % 2 == 0 else sd[len(sd)//2]
+ for i, d in enumerate(depths):
+ if d is None:
+ continue
+ if abs(d - median_d) / median_d > 0.20:
+ pts3d[i] = [float("nan")] * 3
+
+ def _L(a: list[float], b: list[float]) -> Optional[float]:
+ if any(x != x for x in a + b):
+ return None
+ return (sum((a[i] - b[i]) ** 2 for i in range(3))) ** 0.5 * 1000.0
+
+ edges_mm = [_L(pts3d[i], pts3d[(i + 1) % 4]) for i in range(4)]
+ valid_edges = [e for e in edges_mm if e is not None]
+ edge_mean = sum(valid_edges) / len(valid_edges) if valid_edges else None
+
+ distance_m: Optional[float] = None
+ if all(x == x for x in center3d):
+ distance_m = (sum(c ** 2 for c in center3d)) ** 0.5
+
+ tags_out.append({
+ "id": int(m["id"]),
+ "corners_pixel": [[float(c[0]), float(c[1])] for c in corners],
+ "corners_3d_optical_m": pts3d,
+ "corner_depths_mm": depths,
+ "center_3d_optical_m": center3d,
+ "edge_mm_per_side": edges_mm,
+ "edge_mm": edge_mean,
+ "distance_m": distance_m,
+ })
+ return tags_out
+
+
+_TAG_CAMERAS = {
+ "nuwa": ("nuwa_rgb_optical", _deps.nuwa),
+ "d435": ("d435_rgb_optical", _deps.front_camera),
+}
+
+
+@router.get("/tags")
+def get_tags(ids: str = "0-49", probe_size_mm: float = 40.0) -> dict[str, Any]:
+ """Detect ArUco su tutte le camere attive (Nuwa polso + D435i frontale).
+ Una camera offline riporta tags=[] + error, non fa fallire l'altra."""
+ sw = Stopwatch()
+ cameras: dict[str, Any] = {}
+ for key, (frame_label, factory) in _TAG_CAMERAS.items():
+ try:
+ with sw.step(key):
+ tags = _detect_tags_on(factory(), frame_label, ids, probe_size_mm)
+ cameras[key] = {"tags": tags, "frame": frame_label}
+ except Exception as e:
+ cameras[key] = {"tags": [], "frame": frame_label,
+ "error": f"{type(e).__name__}: {e}"}
+ return {"cameras": cameras, "timings_ms": sw.as_dict()}
+```
+
+Note: `_TAG_CAMERAS` references `_deps.nuwa`/`_deps.front_camera` as factory functions (called per-request, preserving the per-request-client convention). Keep `_parse_id_range` where it is. Delete the old `get_front_tags` (the `/front_tags` route is gone; the GUI is updated in Task 5).
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `uv run pytest tests/test_pose_3d_tags.py -v`
+Expected: 2 passed.
+
+- [ ] **Step 5: Run the full pose_3d suite for regressions**
+
+Run: `uv run pytest tests/test_pose_3d_routes.py tests/test_pose_3d_tags.py -v`
+Expected: all pass (no `/front_tags` test exists today, so nothing breaks).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/presa_mano/api/pose_3d_routes.py tests/test_pose_3d_tags.py
+git commit -m "feat(pose_3d): GET /tags multi-camera, rimuovi /front_tags"
+```
+
+---
+
+## Task 3: `POST /api/pose_3d/align` — fit + persist calibration
+
+**Files:**
+- Modify: `src/presa_mano/api/pose_3d_routes.py` (add `/align`, import `umeyama_similarity` + `update_config`)
+- Test: `tests/test_pose_3d_align.py` (create)
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/test_pose_3d_align.py`:
+
+```python
+"""Test POST /api/pose_3d/align: fit Umeyama + persistenza config."""
+from __future__ import annotations
+
+from unittest.mock import patch, MagicMock
+
+import numpy as np
+from fastapi.testclient import TestClient
+
+from presa_mano.main import app
+from presa_mano.config import get_config
+
+client = TestClient(app)
+
+# corner pixel del tag (quad)
+_CORNERS_PX = [[100, 100], [140, 100], [140, 140], [100, 140]]
+
+
+def _cam_with_points(points_by_pixel):
+ """points_by_pixel: dict (u,v)->(x,y,z) in metri. Center = media."""
+ cam = MagicMock()
+ cam.intrinsics.return_value = {"rgb": {"fx": 600.0, "fy": 600.0, "cx": 320.0, "cy": 240.0}}
+ cam.rgb_url.return_value = "http://cam/rgb.png"
+
+ def _measure(u, v, radius=2):
+ key = (int(u), int(v))
+ if key in points_by_pixel:
+ x, y, z = points_by_pixel[key]
+ else: # center
+ xs = [p[0] for p in points_by_pixel.values()]
+ ys = [p[1] for p in points_by_pixel.values()]
+ zs = [p[2] for p in points_by_pixel.values()]
+ x, y, z = sum(xs)/len(xs), sum(ys)/len(ys), sum(zs)/len(zs)
+ return {"point_m": {"x": x, "y": y, "z": z}, "depth_mm": int(z * 1000)}
+ cam.measure.side_effect = _measure
+ return cam
+
+
+def _marker(found_ids):
+ mk = MagicMock()
+ mk.detect_url.return_value = {
+ "found": [{"id": i, "corners": _CORNERS_PX} for i in found_ids],
+ "not_found": [],
+ }
+ return mk
+
+
+def test_align_fits_and_persists():
+ # nuwa corner 3D noti; d435 = 2·nuwa (scala 2, no rot, no trasl)
+ nuwa_pts = {
+ (100, 100): (0.10, 0.10, 0.30),
+ (140, 100): (0.14, 0.10, 0.30),
+ (140, 140): (0.14, 0.14, 0.30),
+ (100, 140): (0.10, 0.14, 0.30),
+ }
+ d435_pts = {k: (v[0]*2, v[1]*2, v[2]*2) for k, v in nuwa_pts.items()}
+ with patch("presa_mano.api.pose_3d_routes._deps.nuwa") as nuwa_f, \
+ patch("presa_mano.api.pose_3d_routes._deps.front_camera") as front_f, \
+ patch("presa_mano.api.pose_3d_routes._deps.marker") as mk_f:
+ nuwa_f.return_value = _cam_with_points(nuwa_pts)
+ front_f.return_value = _cam_with_points(d435_pts)
+ mk_f.return_value = _marker([7])
+ r = client.post("/api/pose_3d/align?ids=0-9&align_id=7")
+ assert r.status_code == 200
+ body = r.json()
+ assert body["found_in_both"] is True
+ assert abs(body["scale"] - 2.0) < 1e-3
+ assert body["align_id"] == 7
+ # persistito in config
+ cc = get_config()["pose_3d"]["cross_camera"]
+ assert abs(cc["scale"] - 2.0) < 1e-3
+ assert cc["align_id"] == 7
+ assert len(cc["R"]) == 3 and len(cc["t"]) == 3
+
+
+def test_align_tag_missing_in_one_camera_does_not_save():
+ pts = {(100,100):(0.1,0.1,0.3),(140,100):(0.14,0.1,0.3),
+ (140,140):(0.14,0.14,0.3),(100,140):(0.1,0.14,0.3)}
+ with patch("presa_mano.api.pose_3d_routes._deps.nuwa") as nuwa_f, \
+ patch("presa_mano.api.pose_3d_routes._deps.front_camera") as front_f, \
+ patch("presa_mano.api.pose_3d_routes._deps.marker") as mk_f:
+ # marker server vede il tag solo su una "immagine" → ma qui detect_url è
+ # condiviso; simuliamo l'assenza usando align_id non presente
+ nuwa_f.return_value = _cam_with_points(pts)
+ front_f.return_value = _cam_with_points(pts)
+ mk_f.return_value = _marker([1]) # nessun tag id=99
+ r = client.post("/api/pose_3d/align?ids=0-9&align_id=99")
+ assert r.status_code == 200
+ body = r.json()
+ assert body["found_in_both"] is False
+ assert body.get("error")
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/test_pose_3d_align.py -v`
+Expected: FAIL with 404 (no `/align` route).
+
+- [ ] **Step 3: Add imports + the `/align` endpoint**
+
+In `src/presa_mano/api/pose_3d_routes.py`, extend the config import and add numpy + the geometry helper near the top:
+
+```python
+import numpy as np
+from ..config import get_config, set_config_value, update_config
+from ..geometry import normalize_quaternion, umeyama_similarity
+```
+
+(Adjust the existing `from ..config import ...` and `from ..geometry import ...` lines rather than duplicating them.)
+
+Then add the endpoint after `get_tags`:
+
+```python
+@router.post("/align")
+def post_align(ids: str = "0-49", align_id: int = 0,
+ probe_size_mm: float = 40.0) -> dict[str, Any]:
+ """Calibrazione cross-camera: trova `align_id` su Nuwa e D435i, fitta una
+ similarità (rot+trasl+scala) Nuwa-optical → D435-optical e la PERSISTE in
+ config.yaml > pose_3d.cross_camera. Se il tag non è visto da entrambe, NON
+ sovrascrive la matrice salvata."""
+ sw = Stopwatch()
+ found: dict[str, Optional[dict]] = {}
+ for key, (frame_label, factory) in _TAG_CAMERAS.items():
+ try:
+ with sw.step(key):
+ tags = _detect_tags_on(factory(), frame_label, ids, probe_size_mm)
+ found[key] = next((t for t in tags if int(t["id"]) == int(align_id)), None)
+ except Exception as e:
+ log.warning("align: camera %s failed: %s", key, e)
+ found[key] = None
+
+ missing = [k for k, v in found.items() if v is None]
+ if missing:
+ return {"found_in_both": False, "align_id": int(align_id),
+ "error": f"tag {align_id} non visto da: {', '.join(missing)}",
+ "timings_ms": sw.as_dict()}
+
+ # corrispondenze corner, scartando i NaN su una delle due camere
+ src, dst = [], []
+ for cn, cd in zip(found["nuwa"]["corners_3d_optical_m"],
+ found["d435"]["corners_3d_optical_m"]):
+ if any(x != x for x in cn) or any(x != x for x in cd):
+ continue
+ src.append(cn)
+ dst.append(cd)
+ if len(src) < 3:
+ return {"found_in_both": False, "align_id": int(align_id),
+ "error": f"corner validi insufficienti ({len(src)}/4)",
+ "timings_ms": sw.as_dict()}
+
+ try:
+ with sw.step("umeyama"):
+ scale, R, t, rmse = umeyama_similarity(np.array(src), np.array(dst))
+ except ValueError as e:
+ return {"found_in_both": False, "align_id": int(align_id),
+ "error": f"fit fallito: {e}", "timings_ms": sw.as_dict()}
+
+ payload = {
+ "align_id": int(align_id),
+ "scale": float(scale),
+ "R": [[float(x) for x in row] for row in R],
+ "t": [float(x) for x in t],
+ "rmse_mm": float(rmse * 1000.0),
+ "n_corners": len(src),
+ }
+ update_config({"pose_3d": {"cross_camera": payload}})
+ return {"found_in_both": True, **payload, "timings_ms": sw.as_dict()}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `uv run pytest tests/test_pose_3d_align.py -v`
+Expected: 2 passed. (The autouse `_restore_config_yaml` fixture in `tests/conftest.py` reverts the `config.yaml` write.)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/presa_mano/api/pose_3d_routes.py tests/test_pose_3d_align.py
+git commit -m "feat(pose_3d): POST /align fit Umeyama cross-camera + persistenza"
+```
+
+---
+
+## Task 4: Expose `cross_camera` in `GET /state`
+
+**Files:**
+- Modify: `src/presa_mano/api/pose_3d_routes.py:97-108` (the `get_state` return dict)
+- Test: `tests/test_pose_3d_routes.py` (add one test)
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `tests/test_pose_3d_routes.py`:
+
+```python
+def test_state_includes_cross_camera_block():
+ with patch("presa_mano.api.pose_3d_routes._deps.g1") as g1_factory:
+ g1 = MagicMock()
+ g1.wrist.return_value = _fake_wrist_pair()
+ g1_factory.return_value = g1
+ r = client.get("/api/pose_3d/state")
+ assert r.status_code == 200
+ assert "cross_camera" in r.json() # {} se mai calibrato
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/test_pose_3d_routes.py::test_state_includes_cross_camera_block -v`
+Expected: FAIL with `KeyError`/assert (no `cross_camera` key).
+
+- [ ] **Step 3: Add the key to the return dict**
+
+In `get_state`, add the line inside the returned dict (next to `"cloud_params"`):
+
+```python
+ "cloud_params": cfg.get("cloud_params") or {},
+ "cross_camera": cfg.get("cross_camera") or {},
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `uv run pytest tests/test_pose_3d_routes.py -v`
+Expected: all pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/presa_mano/api/pose_3d_routes.py tests/test_pose_3d_routes.py
+git commit -m "feat(pose_3d): /state espone blocco cross_camera"
+```
+
+---
+
+## Task 5: Frontend — generalize tag overlay to both cameras
+
+**Files:**
+- Modify: `web/pose_3d.js` (state, render/poll functions, colors, acquire/toggle wiring)
+
+No automated test (vanilla JS). Manual verification at the end.
+
+- [ ] **Step 1: Add the Nuwa tag color + generalize state**
+
+In `web/pose_3d.js`, near `const FRONT_TAG_COLOR = 0x4dd0e1;` (line ~1797) add:
+
+```javascript
+const NUWA_TAG_COLOR = 0xff3b30; // rosso: tag visti dalla camera Nuwa (polso)
+const TAG_COLORS = { nuwa: NUWA_TAG_COLOR, d435: FRONT_TAG_COLOR };
+```
+
+Replace the `front_tags` state block (lines ~230-232) with:
+
+```javascript
+ tags: { // overlay tag per camera (gruppi THREE child del cloud node)
+ nuwa: { group: null },
+ d435: { group: null },
+ },
+```
+
+- [ ] **Step 2: Replace the per-camera render/clear helpers**
+
+Replace `clearFrontTagsGroup` / `addOneFrontTag` / `renderFrontTags` (lines ~1858-1912) with parameterized versions:
+
+```javascript
+function clearTagsGroup(camKey) {
+ const grp = state.tags[camKey].group;
+ if (!grp) return;
+ if (grp.parent) grp.parent.remove(grp);
+ grp.traverse(o => {
+ if (o.geometry) o.geometry.dispose();
+ if (o.material) {
+ if (Array.isArray(o.material)) o.material.forEach(m => m.dispose());
+ else o.material.dispose();
+ }
+ });
+ state.tags[camKey].group = null;
+}
+
+function addOneTag(grp, t, color) {
+ const c = t.corners_3d_optical_m;
+ if (!Array.isArray(c) || c.length !== 4) return;
+ if (c.some(p => !p || p.some(v => !Number.isFinite(v)))) return;
+ const v = new Float32Array(5 * 3);
+ for (let i = 0; i < 4; i++) { v[3*i]=c[i][0]; v[3*i+1]=c[i][1]; v[3*i+2]=c[i][2]; }
+ v[12] = c[0][0]; v[13] = c[0][1]; v[14] = c[0][2];
+ const geom = new THREE.BufferGeometry();
+ geom.setAttribute('position', new THREE.BufferAttribute(v, 3));
+ grp.add(new THREE.Line(geom, new THREE.LineBasicMaterial({ color })));
+ const edge_s = Number.isFinite(t.edge_mm) ? `${t.edge_mm.toFixed(1)}mm` : '?';
+ const dist_s = Number.isFinite(t.distance_m) ? `${(t.distance_m * 1000).toFixed(0)}mm` : '?';
+ const sprite = makeCompactLabel(`id=${t.id} · ${edge_s} · d=${dist_s}`);
+ const ctr = t.center_3d_optical_m;
+ if (ctr && ctr.every(Number.isFinite)) sprite.position.set(ctr[0], ctr[1] - 0.04, ctr[2]);
+ grp.add(sprite);
+}
+
+function renderTags(camKey, tags, color) {
+ clearTagsGroup(camKey);
+ if (!tags || tags.length === 0) return;
+ const parent = getCloudParent(camKey);
+ if (!parent) { console.warn(`[pose_3d] tags: parent ${camKey} non disponibile`); return; }
+ const grp = new THREE.Group();
+ grp.name = `${camKey}_tags_group`;
+ applyCloudLikeTransform(grp, camKey);
+ parent.add(grp);
+ state.tags[camKey].group = grp;
+ for (const t of tags) addOneTag(grp, t, color);
+}
+```
+
+- [ ] **Step 3: Replace `pollFrontTags` with the multi-camera `pollTags`**
+
+Replace `pollFrontTags` (lines ~1914-1930) with:
+
+```javascript
+async function pollTags() {
+ const ids = ($('p3FrontTagIds')?.value || '0-49').trim();
+ const status = $('p3FrontTagStatus');
+ try {
+ const r = await jsonFetch(`/api/pose_3d/tags?ids=${encodeURIComponent(ids)}`);
+ const cams = r.cameras || {};
+ const parts = [];
+ for (const camKey of ['nuwa', 'd435']) {
+ const c = cams[camKey] || {};
+ renderTags(camKey, c.tags || [], TAG_COLORS[camKey]);
+ if (c.error) parts.push(`${camKey}: err`);
+ else parts.push(`${camKey}: ${(c.tags || []).length}`);
+ }
+ if (status) status.textContent = parts.join(' · ');
+ } catch (e) {
+ if (status) status.textContent = `errore: ${e?.message || e}`;
+ }
+}
+```
+
+- [ ] **Step 4: Update the toggle + acquire wiring**
+
+In `bindFrontTagFinder` (lines ~1932-1945) change the two `pollFrontTags()`→`pollTags()` calls and the clear branch:
+
+```javascript
+function bindFrontTagFinder() {
+ const cb = $('p3ShowFrontTags');
+ if (!cb) return;
+ cb.addEventListener('change', () => {
+ if (cb.checked) {
+ pollTags();
+ } else {
+ clearTagsGroup('nuwa');
+ clearTagsGroup('d435');
+ const s = $('p3FrontTagStatus');
+ if (s) s.textContent = '—';
+ }
+ });
+}
+```
+
+In `acquireClouds` change the post-acquire line (added in the previous fix):
+
+```javascript
+ if ($('p3ShowFrontTags')?.checked) pollTags();
+```
+
+- [ ] **Step 5: Manual verification**
+
+Reload `http://localhost:8890`, open Pose 3D → MISC tab → check "Mostra tag visibili". Then Acquisisci. Expect: D435i tags drawn cyan, Nuwa tags drawn red (when a tag is in each camera's view); status shows `nuwa: N · d435: M`. No repeated network calls between acquisitions (Network tab: `/tags` only fires on toggle + Acquisisci).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add web/pose_3d.js
+git commit -m "feat(pose_3d): overlay tag su entrambe le camere (Nuwa rosso, D435i ciano)"
+```
+
+---
+
+## Task 6: Frontend — rename UI section + add alignment controls (index.html)
+
+**Files:**
+- Modify: `web/index.html` (rename "Tag camera frontale"; add alignment row to "Cloud cross-camera")
+
+- [ ] **Step 1: Rename the tag section header**
+
+In `web/index.html` line ~514, change:
+
+```html
+ Tag camera frontale
+```
+to:
+```html
+ Tags
+```
+
+And the checkbox label (line ~516) stays as-is (it already reads "Mostra tag visibili (quad + dim + dist)").
+
+- [ ] **Step 2: Add the alignment controls inside "Cloud cross-camera"**
+
+In `web/index.html`, inside the "Cloud cross-camera" ``, immediately after the D435i scale row (after line ~451, the `
` that closes the `p3D435ScaleXY` row), insert:
+
+```html
+
+
+
+
+
+ —
+```
+
+- [ ] **Step 3: Manual verification**
+
+Reload the page. The MISC tab section now reads "Tags". The CAMERAS tab "Cloud cross-camera" section shows the new checkbox, tag-id input, "Allinea" button, and a status line.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add web/index.html
+git commit -m "feat(pose_3d): rinomina sezione Tags + controlli Allinea cross-camera"
+```
+
+---
+
+## Task 7: Frontend — alignment matrix application (Nuwa cloud placement)
+
+**Files:**
+- Modify: `web/pose_3d.js` (state.align, `d435LocalMatrix`, `applyNuwaCloudPlacement`, hook into `buildOrUpdateCloud`/`applyCloudTransform`)
+
+- [ ] **Step 1: Add alignment state**
+
+In `web/pose_3d.js`, inside the big `state` object (near `cloud_points`, line ~224) add:
+
+```javascript
+ align: { enabled: false, id: 0, matrix: null /* THREE.Matrix4 */ },
+```
+
+- [ ] **Step 2: Add a shared D435 local-matrix helper**
+
+Add near `applyCloudTransform` (line ~1623). This extracts the matrix the D435i cloud uses relative to its parent, so the aligned Nuwa cloud can reuse it:
+
+```javascript
+// Matrix4 locale (rispetto al parent getCloudParent('d435')) usata dal cloud
+// D435i: hand-eye (M·S) oppure URDF (T·R·S). Riusata per piazzare la Nuwa
+// allineata nello stesso frame del D435i.
+function d435LocalMatrix() {
+ const sv = readCloudScaleVec('d435');
+ const S = new THREE.Matrix4().makeScale(sv[0], sv[1], sv[2]);
+ if (useD435Handeye()) {
+ const M = getD435HandeyeMatrix();
+ if (M) return M.clone().multiply(S);
+ }
+ const t = getCloudTransform('d435');
+ const T = new THREE.Matrix4().makeTranslation(t.offset_m[0], t.offset_m[1], t.offset_m[2]);
+ const e = new THREE.Euler(
+ t.rpy_deg[0]*Math.PI/180, t.rpy_deg[1]*Math.PI/180, t.rpy_deg[2]*Math.PI/180, 'XYZ');
+ const R = new THREE.Matrix4().makeRotationFromEuler(e);
+ return T.multiply(R).multiply(S);
+}
+```
+
+- [ ] **Step 3: Add `applyNuwaCloudPlacement` and route the Nuwa branch through it**
+
+Add the function (near `applyCloudTransform`):
+
+```javascript
+// Piazza la nuvola Nuwa: in modalità allineata la renderizza nel frame del
+// D435i (parent + pipeline D435i · matrice di allineamento); altrimenti usa il
+// piazzamento URDF normale.
+function applyNuwaCloudPlacement() {
+ const pts = state.cloud_points.nuwa;
+ if (!pts) return;
+ const aligned = state.align.enabled && state.align.matrix;
+ if (aligned) {
+ const parent = getCloudParent('d435');
+ if (parent) {
+ if (pts.parent !== parent) parent.add(pts);
+ pts.matrixAutoUpdate = false;
+ pts.matrix.copy(d435LocalMatrix()).multiply(state.align.matrix);
+ pts.matrixWorldNeedsUpdate = true;
+ return;
+ }
+ }
+ if (state.align.enabled && !state.align.matrix) {
+ const s = $('p3AlignStatus');
+ if (s) { s.textContent = 'nessuna calibrazione: premi Allinea'; s.style.color = 'var(--dim)'; }
+ }
+ // fallback URDF normale
+ const parent = getCloudParent('nuwa');
+ if (parent && pts.parent !== parent) parent.add(pts);
+ pts.matrixAutoUpdate = true;
+ applyCloudTransform('nuwa');
+}
+```
+
+In `buildOrUpdateCloud` (line ~1606-1608), special-case nuwa so the new path is used:
+
+```javascript
+ // (Ri-)attacca al parent corretto e applica transform optical→link
+ if (camKey === 'nuwa') {
+ applyNuwaCloudPlacement();
+ } else {
+ if (pts.parent !== parent) parent.add(pts);
+ applyCloudTransform(camKey);
+ }
+ applyCloudVisibility();
+ return pts;
+```
+
+Note: for nuwa the early `getCloudParent('nuwa')`/`parent.add` at the top of `buildOrUpdateCloud` is now superseded by `applyNuwaCloudPlacement` (which re-parents as needed); leaving the initial `parent` lookup is harmless.
+
+- [ ] **Step 4: Manual verification (no calibration yet)**
+
+Reload, acquire clouds with "Allinea Nuwa→frontale" **off** → Nuwa cloud sits where it does today (URDF, on the wrist link). Turning the flag on with no calibration → status reads "nessuna calibrazione: premi Allinea", Nuwa stays in URDF placement (no crash).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add web/pose_3d.js
+git commit -m "feat(pose_3d): piazzamento Nuwa allineato nel frame D435i (matrice)"
+```
+
+---
+
+## Task 8: Frontend — `doAlign`, persistence, load-from-config wiring
+
+**Files:**
+- Modify: `web/pose_3d.js` (doAlign, bindings, applyCrossCameraFromCfg, save flag, call from pollState + init)
+
+- [ ] **Step 1: Add `matrixFromAlign`, `doAlign`, and config load/save helpers**
+
+Add near `pollTags`:
+
+```javascript
+// Costruisce una THREE.Matrix4 (colonna-major) da {scale,R,t}: p' = s·R·p + t.
+function matrixFromAlign(cc) {
+ if (!cc || !Array.isArray(cc.R) || cc.R.length !== 3 || !Array.isArray(cc.t)) return null;
+ const s = Number.isFinite(cc.scale) ? cc.scale : 1;
+ const R = cc.R, t = cc.t;
+ return new THREE.Matrix4().set(
+ s*R[0][0], s*R[0][1], s*R[0][2], t[0],
+ s*R[1][0], s*R[1][1], s*R[1][2], t[1],
+ s*R[2][0], s*R[2][1], s*R[2][2], t[2],
+ 0, 0, 0, 1,
+ );
+}
+
+async function doAlign() {
+ const ids = ($('p3FrontTagIds')?.value || '0-49').trim();
+ const alignId = parseInt($('p3AlignTagId')?.value, 10) || 0;
+ const status = $('p3AlignStatus');
+ if (status) { status.textContent = 'allineamento…'; status.style.color = 'var(--dim)'; }
+ try {
+ const r = await jsonFetch(
+ `/api/pose_3d/align?ids=${encodeURIComponent(ids)}&align_id=${alignId}`,
+ { method: 'POST' });
+ if (!r.found_in_both) {
+ if (status) { status.textContent = r.error || 'tag non visto da entrambe'; status.style.color = 'var(--danger)'; }
+ return;
+ }
+ state.align.matrix = matrixFromAlign(r);
+ state.align.id = r.align_id;
+ if (status) {
+ status.textContent = `scala=${r.scale.toFixed(3)} · rmse=${r.rmse_mm.toFixed(1)}mm · n=${r.n_corners}`;
+ status.style.color = 'var(--ok)';
+ }
+ applyNuwaCloudPlacement();
+ } catch (e) {
+ if (status) { status.textContent = `errore: ${e?.message || e}`; status.style.color = 'var(--danger)'; }
+ }
+}
+
+// Persistenza del solo flag + align_id (la matrice la salva il backend in /align).
+async function saveCrossCameraFlag() {
+ try {
+ await jsonFetch('/api/config', {
+ method: 'PUT',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ pose_3d: { cross_camera: {
+ enabled: $('p3AlignEnabled')?.checked === true,
+ align_id: parseInt($('p3AlignTagId')?.value, 10) || 0,
+ } } }),
+ });
+ } catch (e) { console.warn('[pose_3d] save cross_camera failed:', e?.message || e); }
+}
+
+// Ripopola UI + matrice dalla config (guardato come applyCloudParamsFromCfg).
+function applyCrossCameraFromCfg(cc) {
+ if (state.cross_camera_populated) return;
+ if (!cc || Object.keys(cc).length === 0) { state.cross_camera_populated = true; return; }
+ const en = $('p3AlignEnabled'); if (en) en.checked = cc.enabled === true;
+ const id = $('p3AlignTagId'); if (id && Number.isFinite(cc.align_id)) id.value = String(cc.align_id);
+ state.align.enabled = cc.enabled === true;
+ state.align.id = cc.align_id || 0;
+ const m = matrixFromAlign(cc);
+ if (m) state.align.matrix = m;
+ const status = $('p3AlignStatus');
+ if (status && Number.isFinite(cc.rmse_mm)) {
+ status.textContent = `caricata · scala=${(cc.scale||1).toFixed(3)} · rmse=${cc.rmse_mm.toFixed(1)}mm`;
+ }
+ state.cross_camera_populated = true;
+}
+```
+
+- [ ] **Step 2: Bind the button + flag**
+
+In `bindFrontTagFinder` (or alongside the other bindings in the init/bind function that wires `p3CloudAcquireBtn` — line ~1949), add:
+
+```javascript
+ $('p3AlignBtn')?.addEventListener('click', doAlign);
+ $('p3AlignEnabled')?.addEventListener('change', () => {
+ state.align.enabled = $('p3AlignEnabled').checked === true;
+ saveCrossCameraFlag();
+ applyNuwaCloudPlacement();
+ });
+ $('p3AlignTagId')?.addEventListener('change', saveCrossCameraFlag);
+```
+
+- [ ] **Step 3: Load from config in `pollState`**
+
+In `pollState` (after `applyCloudParamsFromCfg(s.cloud_params);`, line ~785) add:
+
+```javascript
+ applyCrossCameraFromCfg(s.cross_camera);
+```
+
+- [ ] **Step 4: Manual verification (full flow)**
+
+With a tag visible to both cameras: set its id in "tag id", press **Allinea** → status shows `scala=… rmse=…mm`, the Nuwa cloud snaps onto the D435i cloud. Toggle "Allinea Nuwa→frontale" off → Nuwa returns to URDF placement; on → snaps back (no recompute). Reload the page → checkbox/id restored, and if it was enabled the Nuwa cloud is placed via the saved matrix after the first `/clouds` acquire. Press Allinea with the tag hidden from one camera → status shows "tag non visto…", previous overlay unchanged.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add web/pose_3d.js
+git commit -m "feat(pose_3d): doAlign + persistenza/caricamento calibrazione cross-camera"
+```
+
+---
+
+## Task 9: Docs — CLAUDE.md endpoint list + README
+
+**Files:**
+- Modify: `CLAUDE.md` (Pose 3D endpoint bullet)
+- Modify: `README.md` (Pose 3D tab description, if it lists endpoints/features)
+
+- [ ] **Step 1: Update CLAUDE.md endpoint list**
+
+In `CLAUDE.md`, in the "Pose 3D" useful-endpoints bullet, replace the `front_tags` reference with the new endpoints and add the alignment note. Change the Pose 3D bullet to include:
+
+```
+- Pose 3D: `GET /api/pose_3d/state` (… + `cross_camera` calibration), `GET /api/pose_3d/tags` (ArUco su Nuwa + D435i), `POST /api/pose_3d/align?align_id=N` (fit Umeyama Nuwa→frontale, persiste in `pose_3d.cross_camera`), `GET /api/pose_3d/clouds`, `CRUD /api/pose_3d/poses/{name}`.
+```
+
+Add a conventions note under "Conventions to preserve":
+
+```
+- **Pose 3D cross-camera alignment:** `POST /api/pose_3d/align` fits an Umeyama similarity (rot+trasl+uniform scale) mapping Nuwa-optical → D435-optical from a tag (`align_id`) seen by both cameras, and persists it to `config.yaml > pose_3d.cross_camera`. The frontend renders the Nuwa cloud through the D435i transform pipeline (`d435LocalMatrix()` · alignMatrix) when `cross_camera.enabled`. If the tag isn't seen by both, the saved matrix is NOT overwritten and the cloud falls back to URDF placement.
+```
+
+- [ ] **Step 2: Update README (if applicable)**
+
+Open `README.md`, find the Pose 3D tab section, and update any feature list / endpoint mention to match (tags on both cameras, red Nuwa tags, cross-camera alignment button). If README has no such detail, skip.
+
+- [ ] **Step 3: Run the full backend suite (final regression)**
+
+Run: `uv run pytest -q`
+Expected: all pass.
+
+- [ ] **Step 4: Verify the working tree config.yaml is unchanged**
+
+Run: `git status --short config.yaml`
+Expected: no output (the test fixture restored it).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add CLAUDE.md README.md
+git commit -m "docs(pose_3d): tags multi-camera + calibrazione cross-camera"
+```
+
+---
+
+## Self-Review notes
+
+- **Spec coverage:** tags-both-cameras → Task 2/5; red Nuwa → Task 5 (`NUWA_TAG_COLOR`); rename "Tags" → Task 6; Umeyama helper → Task 1; `/align` fit+persist → Task 3; flag+button UI → Task 6; matrix apply + D435-pipeline render → Task 7; persistence+load → Task 3/4/8; fallback-to-URDF → Task 7; tests → Tasks 1-4; `/front_tags` removal → Task 2. All covered.
+- **Type/name consistency:** `clearTagsGroup`, `renderTags(camKey,tags,color)`, `addOneTag(grp,t,color)`, `pollTags`, `applyNuwaCloudPlacement`, `d435LocalMatrix`, `matrixFromAlign`, `applyCrossCameraFromCfg`, `saveCrossCameraFlag`, `doAlign`, `state.tags`, `state.align`, `_detect_tags_on`, `get_tags`, `post_align`, `umeyama_similarity` — used consistently across tasks. UI ids: `p3AlignEnabled`, `p3AlignTagId`, `p3AlignBtn`, `p3AlignStatus`, reused `p3FrontTagIds`/`p3ShowFrontTags`/`p3FrontTagStatus`.
+- **Frame note:** alignment is fit in raw optical space (pre flip/scale-XY); rendering reuses the full D435i pipeline so both clouds get the same downstream flips/scale and stay overlaid.
+```