Presa-Mano/docs/superpowers/specs/2026-05-20-right-arm-tab-design.md

# Tab "Braccio DX" — design

**Data**: 2026-05-20
**Autore**: brainstorm con Adriano
**Stato**: design approvato, pronto per writing-plans

## Obiettivo

Aggiungere una tab GUI dedicata all'operatività del braccio destro del robot **G1** in setup nuovo:
- Camera depth **fissa frontale** a `http://192.168.123.99:8878` (servizio Nuwa-like in docker sul robot).
- Camera **Nuwa sul polso destro** (eye-in-hand): la Nuwa esistente (`localhost:8877`) è stata spostata fisicamente sul polso.

La tab consente, in un unico posto:
1. Vedere fronte + polso, lanciare YOLO on-demand per cercare un oggetto (default `pestello`).
2. Su immagine polso, eseguire YOLO+SAM21 per ottenere centroide e distanza camera→oggetto.
3. Muovere il polso destro verso l'oggetto con offset XYZ configurabili.
4. Andare a una **Posa Home** preset o a una **Posa Custom** editabile, entrambe persistite in config.

## Non-goals

- **Niente** calibrazione eye-in-hand reale (`T_wrist_camera`). L'offset XYZ + sign flips è il workaround dichiarato.
- **Niente** sequenza approach+grasp. Il "muovi verso pezzo" è un singolo `wrist_relative`.
- **Niente** IK custom: ci si appoggia interamente a `wrist_absolute`/`wrist_relative` di G1.
- **Niente** persistenza delle detection. Ogni snapshot/detect è stateless.
- **Niente** segmentazione/distanza sul flusso fronte: il fronte serve solo per detection 2D (overview).

## Architettura

### Nuovi moduli

| File | Ruolo |
|---|---|
| `src/presa_mano/api/right_arm_routes.py` | Router `/api/right_arm/*` |
| `web/right_arm.js` | Logica e wiring della tab (vanilla, pattern di `work_plane.js`) |
| `tests/test_right_arm_geometry.py` | Unit test: delta move, RPY↔quat |
| `tests/test_right_arm_routes.py` | Integration: tutti gli endpoint con `respx` |

### Modifiche a moduli esistenti

| File | Modifica |
|---|---|
| `src/presa_mano/main.py` | Include `right_arm_routes.router` con prefix `/api/right_arm` |
| `src/presa_mano/api/_deps.py` | Aggiunge `front_camera() -> NuwaClient` (legge `services.front_camera`) |
| `src/presa_mano/clients/g1.py` | Aggiunge `arms_neutral()` (proxy a `POST /arms/go_neutral`) — disponibile ma non usato dal Home |
| `src/presa_mano/geometry.py` | Aggiunge `rpy_to_quaternion(roll, pitch, yaw)` e `quaternion_to_rpy(q)` in gradi |
| `web/index.html` | Nuova tab `right-arm` tra "Vista 3D" e "Movimento EE"; markup pannello |
| `config.yaml` | Aggiunge `services.front_camera` e blocco `tab_right_arm` (vedi sotto) |

### Niente client nuovo per la front camera

Il servizio frontale risponde con lo stesso envelope `{success, data, error}` e gli stessi endpoint (`/api/rgb`, `/api/depth`, `/api/intrinsics`, `/api/status`, `/api/health`) della Nuwa: si riusa `NuwaClient` puntato al nuovo base_url.

## Config

Aggiunte a `config.yaml`:

```yaml
services:
  front_camera:
    base_url: http://192.168.123.99:8878
    timeout_s: 5.0

tab_right_arm:
  yolo_class: pestello
  yolo_conf_front: 0.4
  yolo_conf_wrist: 0.4
  move_offset_camera_mm: { x: 0, y: 0, z: 100 }
  axis_sign_cam_to_wrist:  { x: 1, y: -1, z: -1 }
  max_step_m: 0.15
  z_floor_m: null            # se settato, clip Z target a max(target, floor)
  home_pose:
    position:   [0.30, -0.20, 0.30]   # m, frame base
    rpy_deg:    [0, 0, 0]
  custom_pose:
    position:   [0.30, -0.20, 0.30]
    rpy_deg:    [0, 0, 0]
```

**Persistenza**: la GUI usa `PUT /api/config` (deep-merge esistente) per aggiornare `tab_right_arm.move_offset_camera_mm`, `axis_sign_cam_to_wrist` e `custom_pose`. Home è considerata stabile: editabile solo a mano nel file o via API esplicita.

## Endpoint `/api/right_arm/*`

Pattern di risposta: `{..., "timings_ms": {step: ms, ..., total: ms}}` ovunque.

| Method | Path | Body / Query | Risposta sintetica |
|---|---|---|---|
| `GET`  | `/state` | — | `{wrist:{position, quaternion, rpy_deg}, robot_active, side, home_pose, custom_pose, offset_camera_mm, axis_signs, max_step_m, z_floor_m}` |
| `POST` | `/activate` | — | `PUT /api/config {robot:{active:"g1", wrist_side:"right"}}`; ritorna nuovo `/state` |
| `GET`  | `/snapshot/front` | — | streaming `image/jpeg` da `front_camera().rgb_jpeg()` |
| `GET`  | `/snapshot/wrist` | — | streaming `image/jpeg` da `nuwa().rgb_jpeg()` |
| `POST` | `/detect/front` | `{class_name?, conf?, proxy_base_url?}` | `{detections:[{class, confidence, bbox}], image_size:[w,h]}` |
| `POST` | `/detect/wrist` | `{class_name?, conf?}` | `{detection, bbox, centroid_camera_m, distance_m, n_sam21_points}` |
| `POST` | `/move/toward` | `{class_name?, conf?, dry_run?, force?}` | vedi data flow |
| `POST` | `/home` | `{dry_run?}` | `wrist_absolute(side=right, position=home_pose.position, quaternion=rpy_to_quat(home_pose.rpy_deg))` |
| `POST` | `/custom_pose` | `{dry_run?}` | come `/home` ma con `custom_pose` |
| `PUT`  | `/custom_pose` | `{position?, rpy_deg?}` | aggiorna `tab_right_arm.custom_pose` |
| `PUT`  | `/offset` | `{move_offset_camera_mm?, axis_sign_cam_to_wrist?}` | aggiorna config |

### YOLO ↔ front camera: fallback proxy

Il YOLO server (`:8879`) prende `image_url` e fa pull. Se non raggiunge `192.168.123.99:8878`, `/detect/front` riprova con `image_url = <proxy_base_url>/api/right_arm/snapshot/front`. La GUI passa `window.location.origin` come `proxy_base_url`. Se anche questo fallisce → 502.

### Default `dry_run`

- `/move/toward`: default **`true`** (gesto pericoloso).
- `/home`, `/custom_pose`: default **`false`** (gesti progettati).

## Data flow — `/move/toward`

1. GUI invia `{class_name, conf, dry_run, force}`.
2. Backend esegue internamente la stessa funzione di `/detect/wrist`:
   - `nuwa.rgb_jpeg()` + `nuwa.depth_png()` + `nuwa.intrinsics()` (3 GET, skew accettato).
   - YOLO su `nuwa.rgb_url()` filtrato per `class_name`, top per confidence → `bbox`.
   - SAM21 `segment_pointcloud(rgb, depth, intrinsics, bbox)` → Nx3 in metri, frame **camera RGB OpenCV** (X-right, Y-down, Z-forward).
   - Se `len(points) < 10` → 422.
   - `centroid_camera_m = points.mean(axis=0)`; `distance_m = ||centroid||`.
3. Calcolo delta in frame polso:
   ```
   off_m       = move_offset_camera_mm / 1000
   sign        = axis_sign_cam_to_wrist
   delta_wrist = sign * (centroid_camera_m - off_m)
   ```
   Nessuna rotazione: si assume assi camera ≈ assi polso a meno dei segni (calibrazione empirica via flag). Default `(+1, -1, -1)` riflette l'inversione tipica Y-down/Z-forward camera OpenCV vs Y-up/Z-up polso — da tarare empiricamente.
4. Guardia: se `||delta_wrist|| > max_step_m` e `force != true` → 422.
5. Z floor (se `z_floor_m != null`):
   - leggo `wrist_before.position.z`, calcolo `target_z = wrist_before.z + delta_wrist[2]`.
   - se `target_z < z_floor` → clip `delta_wrist[2] = z_floor - wrist_before.z`; annoto `z_clipped: true` in response.
6. `g1(dry_run=req.dry_run).wrist_relative(side="right", delta_position=delta_wrist.tolist())`.
7. Response:
   ```json
   {
     "detection": {...},
     "centroid_camera_m": [x,y,z],
     "distance_m": 0.187,
     "offset_camera_m": [0,0,0.1],
     "axis_signs": [1,-1,-1],
     "delta_wrist_m": [dx,dy,dz],
     "delta_wrist_mm": [dx_mm,dy_mm,dz_mm],
     "z_clipped": false,
     "wrist_before": {position:[...], quaternion:[...]},
     "wrist_after":  {position:[...], quaternion:[...]} or null,
     "applied": true,
     "timings_ms": {...}
   }
   ```

**Logging**: ogni `/move/toward` log INFO con `class, conf, centroid_camera, offset, sign, delta_wrist, dry_run, applied`. Primo dato per debug empirico dei sign flip.

**Niente sweep automatici**: una call = un move (rispetta `feedback_no_sweep_live_robot`).

## Error map

| Condizione | HTTP | Detail |
|---|---|---|
| YOLO unreachable | 502 | `"YOLO unreachable: ..."` |
| YOLO 0 detections (post-filter classe) | 404 | `"no '<class>' detected"` |
| Front cam unreachable | 502 | `"front_camera unreachable: ..."` |
| SAM21 unreachable | 502 | `"sam21 unreachable: ..."` |
| SAM21 < 10 punti | 422 | `"too few sam21 points: N"` |
| G1 unreachable | 502 | `"G1 unavailable: ..."` |
| `robot.active != g1` o `wrist_side != right` | 412 | `"activate G1 right first"` |
| `\|\|delta_wrist\|\| > max_step` senza `force` | 422 | `"delta_wrist {N}mm > max {M}mm"` |
| `home_pose`/`custom_pose` malformati | 422 | pydantic validation |

## Layout GUI

Nuova tab tra "Vista 3D" e "Movimento EE", label **Braccio DX**.

```
+----------------------------------------------------------------------+
| [ Braccio DX attivo: g1 / right ]   [ Attiva G1 right ]  ← se diverso |
+----------------------------------------------------------------------+
| FRONTE                  | POLSO                  | BRACCIO DX        |
|  <img .front>           |  <img .wrist>          |  Posa corrente:   |
|  classe [pestello ▼]    |  classe [pestello ▼]   |   X: 0.301 m      |
|  conf  [0.40 ]          |  conf  [0.40 ]         |   Y:-0.187 m      |
|  [ Cerca su fronte ]    |  [ Cerca su polso ]    |   Z: 0.302 m      |
|  ── risultato ──        |  ── risultato ──       |   R: 12.4°        |
|  classe: pestello       |  classe: pestello      |   P: -3.1°        |
|  conf: 0.87             |  conf: 0.91            |   Y: 88.6°        |
|  bbox: [120,80,210,180] |  bbox: [...]           |   [ Refresh ]     |
|                         |  centroide cam:        |                   |
|  auto-refresh 1s [✓]    |   x: 0.012  y:-0.003   |                   |
|                         |   z: 0.187  (m)        |                   |
|                         |  distanza: 187 mm      |                   |
|                         |  punti SAM21: 1842     |                   |
|                         |  auto-refresh 1s [✓]   |                   |
+----------------------------------------------------------------------+
| OFFSET PRESA RISPETTO A CAMERA (mm)   SIGN FLIP cam→polso             |
|  X [   0]  Y [   0]  Z [ 100]         X [+1]  Y [-1]  Z [-1]          |
|  [ Salva offset ]    [ Muovi verso pezzo ]   dry-run [✓]              |
+----------------------------------------------------------------------+
| POSA HOME (preset)              | POSA CUSTOM (editabile)             |
|  X [ 0.30] Y [-0.20] Z [ 0.30]  |  X [ 0.30] Y [-0.20] Z [ 0.30]      |
|  R [   0] P [   0  ] Y [   0]   |  R [   0] P [   0  ] Y [   0]       |
|  [ Vai a Home ]                 |  [ Vai a Custom ] [ Salva custom ]  |
|                                 |  [ Usa posa corrente ]              |
+----------------------------------------------------------------------+
```

### Interazioni

- **Auto-refresh immagini**: `setInterval` ogni 1s (configurabile per pannello); chiama `/snapshot/{front,wrist}` e aggiorna `<img>` con object URL (revoca quello precedente).
- **YOLO trigger separato**: pulsanti "Cerca su fronte"/"Cerca su polso". Il bbox è disegnato su un `<canvas>` overlay e persiste finché non parte un nuovo detect.
- **"Muovi verso pezzo"**: primo click esegue con `dry_run=true` e mostra il delta calcolato in mm in un riquadro di conferma; secondo click conferma `dry_run=false`. Toggle `dry-run` esplicito sempre visibile (se off, salta lo step di preview).
- **"Salva offset"** → `PUT /offset`; **"Salva custom"** → `PUT /custom_pose`.
- **"Usa posa corrente"**: copia la posa attuale del polso (convertita in RPY) nei campi custom (no save automatico).
- **Banner**: rosso se `robot.active != g1` o `wrist_side != right`. In quel caso visibile il pulsante "Attiva G1 right" che chiama `POST /activate`. Verde altrimenti.
- **Refresh posa polso**: `setInterval` 2s, override manuale con pulsante "Refresh".

## Testing

### Unit (`tests/test_right_arm_geometry.py`)

- `rpy_to_quaternion` / `quaternion_to_rpy` roundtrip su 10+ campioni.
- Casi del delta:
  - centroid=(0,0,1), offset=(0,0,0), sign=(1,1,1) → delta=(0,0,1)
  - centroid=(0,0,1), offset=(0,0,0.1), sign=(1,-1,-1) → delta=(0,0,-0.9)
  - applicazione sign solo dopo (centroid - offset)
- Z-floor clip: target sotto floor → delta_z ridotto; flag `z_clipped` settato.
- Guardia `max_step`: oltre soglia → eccezione; con `force=True` passa.

### Integration (`tests/test_right_arm_routes.py`)

Con `respx`: mock di Nuwa, front camera, YOLO, SAM21, G1. Coverage:

- `/state` con e senza `home_pose` definita.
- `/activate` cambia config e ritorna nuovo state.
- `/snapshot/{front,wrist}` ritorna JPEG e content-type giusto.
- `/detect/front` con YOLO ok; con YOLO che fallisce su URL diretto e funziona via proxy; con 0 detection.
- `/detect/wrist` con YOLO+SAM21 ok; con SAM21 < 10 punti (422); con SAM21 unreachable (502).
- `/move/toward` dry_run vs no; force vs guardia; z_floor clip; 412 quando active diverso.
- `/home` e `/custom_pose` dry_run.
- `PUT /custom_pose` e `PUT /offset` aggiornano config (verifica round-trip via `GET /api/config`).

### Smoke manuale

In ordine, da riportare nel design al follow-up:
1. `POST /api/right_arm/activate` → state mostra `g1/right`.
2. `POST /api/right_arm/home` (dry_run=true) → preview pose target; poi `dry_run=false`.
3. `GET /api/right_arm/snapshot/front` → JPEG riconoscibile.
4. `POST /api/right_arm/detect/wrist` → centroide e distanza coerenti con scena nota.
5. `POST /api/right_arm/move/toward` (dry_run=true) → delta in mm ragionevole; rifiuta se non c'è pestello in scena.

## Sicurezza fisica

- **Dry-run di default** su `/move/toward`.
- **`max_step_m`** come guardia hard, bypassabile solo con `force=true` esplicito.
- **`z_floor_m`** clip preventivo sulla Z (memoria `feedback_z_floor_safe`).
- **Banner rosso** se non in `g1/right`: impedisce visivamente comandi su robot/braccio sbagliato.
- **Nessuno sweep**: ogni call è un singolo move (memoria `feedback_no_sweep_live_robot`).

## Tradeoff accettati

- 3 GET separati per rgb+depth+intrinsics ad ogni `/detect/wrist`: piccolo skew temporale, scene lente → accettabile.
- Switching `robot.active=g1` è globale: rompe flow H1 left attivi. Il banner + pulsante esplicito lo rende visibile.
- Assunzione "assi camera ≈ assi polso a meno dei segni": semplifica enormemente ma costringe l'utente a tarare i sign flip empiricamente. Documentato nel layout.

## Memorie applicabili

- `feedback_no_sweep_live_robot` → niente loop di test sul fisico.
- `feedback_reason_in_grasp_point` → distanze ragionate sul punto di presa (offset XYZ rappresenta proprio la differenza camera↔grasp).
- `feedback_z_floor_safe` → clip Z implementato.
- `project_emergency_stop_behavior` → motivazione per **non** usare `go_neutral` sul Home.
- `project_h1_wrist_is_hand_tcp` → analogamente, su G1 verifichiamo che `position` ritornata da `/api/wrist` sia il TCP (assunto, da confermare in smoke test).