Presa-Mano/docs/superpowers/specs/2026-05-21-pose-3d-tab-design.md

# Design — Tab "Pose 3D" (editor visuale + jog dei polsi)

**Data:** 2026-05-21
**Stato:** approvato per implementazione

## Obiettivo

Aggiungere una tab "3D" alla GUI di `presa-mano` che permetta di:

1. Visualizzare la posa corrente dei polsi destro e sinistro del robot attivo in un viewport 3D.
2. Trascinare in 3D (gizmo translate+rotate) un polso alla volta per definire una nuova posa.
3. Validare la posa via il bridge G1 e (se in modalità Jog) muovere il robot reale.
4. Salvare/caricare pose con nome per riuso.

Sostituisce il workflow attuale che richiede di editare manualmente campi numerici X/Y/Z + RPY nella tab Braccio DX, e fornisce una rappresentazione visuale per le 3 UCS di riferimento (base, polso DX, polso SX) finora invisibili.

## Modalità di lavoro

Toggle in header tab, due valori mutuamente esclusivi:

- **Editor**: il drag aggiorna SOLO la posa ghost locale (preview). Il bottone "Applica" abilita un commit *simulato* (il ghost diventa "current" lato client, robot non si muove). Utile per pianificare/visualizzare senza rischio.
- **Jog**: il drag aggiorna il ghost; al rilascio del mouse (`mouseup`) parte automaticamente un comando reale `wrist_absolute` con `dry_run=false`. Nessun bottone Apply. 1 drag = 1 move.

Safety guard in modalità Jog: prima dell'auto-apply, calcolo `||ghost_target − current_wrist||`. Se supera `pose_3d.live_max_step_m` (default 0.15 m), mostro un dialog di conferma "Movimento richiesto X mm. Procedi?" prima di inviare al robot.

**Flag `precise`**: tutti i comandi reali (Editor Apply non incluso — è sim locale) hanno per default `precise=true` (controllo accurato del bridge). Il pannello espone un checkbox **"Precise"** abilitato di default; l'utente può disattivarlo se sa che il movimento è approssimativo / fuori workspace nominale (evita `arms: error_timeout` su movimenti grandi). Il toggle è di sessione, non persistito.

## Architettura

```
┌─────────────────────────────────────────────────────────────────┐
│ BROWSER                                                         │
│  web/pose_3d.html (markup) + web/pose_3d.js (Three.js + UI)     │
│  web/pose_3d.css                                                │
│  - Scene Three.js: torso, 2 link, 2 polso-sphere, 3 UCS         │
│  - TransformControls: gizmo translate+rotate sul polso attivo   │
│  - Sidebar: side selector, mode toggle, gizmo toggle, readout,  │
│    bottoni Apply (Editor)/Sblocca, save/load pose               │
│  - Polling GET /api/pose_3d/state ogni 1s per sync con robot    │
└──────────────────────────┬──────────────────────────────────────┘
                           │ HTTP /api/pose_3d/*
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│ ORCHESTRATOR (FastAPI, presa-mano)                              │
│  src/presa_mano/api/pose_3d_routes.py                           │
│   - GET  /state              -> {left_wrist, right_wrist, poses}│
│   - POST /apply              -> wrist_absolute(side, pos, quat) │
│   - GET  /poses              -> dict {nome: NamedPose}          │
│   - PUT  /poses/{name}       -> salva/aggiorna posa             │
│   - DELETE /poses/{name}     -> rimuove                         │
│   - POST /poses/{name}/go    -> esegue posa salvata             │
│   - POST /unlock             -> proxy POST :8765/unlock         │
│  config.yaml > pose_3d.{named_poses, live_max_step_m}           │
└──────────────────────────┬──────────────────────────────────────┘
                           │ chiama _deps.g1() (robot attivo h1|g1)
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│ G1_API_Server (port 8765, esistente, NON modificato)            │
│  - GET /wrist            -> {left_wrist, right_wrist}           │
│  - POST /wrist/absolute  -> IK + motion                         │
│  - POST /unlock          -> sblocco arms (recovery error_timeout)│
└─────────────────────────────────────────────────────────────────┘
```

Dipendenze frontend (CDN, no build step):

- `three@0.160` (~600 KB minified)
- `three/examples/jsm/controls/OrbitControls`
- `three/examples/jsm/controls/TransformControls`

Caricate via `<script type="importmap">` direttamente in `web/index.html`.

Non cambia:
- La tab Braccio DX esistente — la tab 3D è additiva.
- Endpoint G1_API_Server.
- Endpoint `wrist_routes.py` (`/api/wrist/*`) generico — riusato sotto il cofano.

## Componenti frontend

### Scene Three.js

```
Scene
 ├── lights (ambient + directional)
 ├── GridHelper (piano XY a Z=0, 2m × 2m)
 ├── BaseUCS              terna RGB 200 mm, sempre visibile
 ├── Torso                Box 0.20 × 0.40 × 0.50, opacity 0.7
 │
 ├── ArmRight (Group)
 │    ├── ArmLinkRight    LineSegments shoulder→wrist
 │    ├── WristSphereRight Sphere r=0.04, ciano, hit-test target
 │    └── WristUCSRight   terna RGB 100 mm orientata dal quaternion
 │
 ├── ArmLeft (Group)      come sopra, sfera rossa
 │
 ├── GhostRight (Group)   copia ArmRight con opacity 0.4,
 │                          visibile solo se c'è target locale non applicato
 └── GhostLeft (Group)
```

Dimensioni torso e posizione spalle: hardcoded sensate per G1 (torso a (0,0,0.40) m, spalla dx ~(0,−0.20,0.60), sx ~(0,+0.20,0.60)). Solo estetica — non influenzano IK (server-side).

Camera: `PerspectiveCamera` + `OrbitControls`. Posizione iniziale (1, −1, 0.8) m, target (0, 0, 0.3). Wheel = zoom, drag = orbit, shift+drag = pan.

### Interazione

- **Selezione polso**: raycaster su mouse-click. Click su `WristSphereRight` o `WristSphereLeft` → attiva polso (highlight + TransformControls attached).
- **Click su empty space** → deseleziona, gizmo nascosto.
- **TransformControls** ha 2 mode: `translate` (frecce) / `rotate` (anelli). Toggle nel pannello (radio "T" / "R", oppure tasti `t`/`r` da tastiera).
- **Durante drag**: posizione/rotazione del Ghost si aggiorna live; il polso "reale" resta fermo. Numeri X/Y/Z/RPY nel pannello aggiornati in tempo reale.
- **Al mouseup**:
  - Editor mode: nessuna chiamata HTTP. Ghost resta lì. Per committarlo, bottone Apply.
  - Jog mode: auto-fire `POST /apply` con `dry_run=false`. Se `||target−current|| > live_max_step_m`, prima dialog di conferma.

### Pannello sidebar

```
┌─────────────────────────────────┐
│ [Editor] [Jog]   ← toggle       │
│                                 │
│ Polso attivo: ● Destro ○ Sinistro │
│ Gizmo: ● Sposta ○ Ruota         │
│ ☑ Precise (controllo accurato)  │
│                                 │
│ ─ Posa target ──────────────    │
│  X [0.300] Y [-0.200] Z [0.300] │ readonly, mm
│  R [0.0°] P [0.0°] W [0.0°]     │ readonly
│  Stato: ● modificata            │
│                                 │
│  (Editor) [Applica] [Annulla]   │
│  (Jog) nessun bottone           │
│                                 │
│ ─ Pose salvate ─────────────    │
│  ▼ [seleziona...]               │
│  [Vai] [Salva con nome] [✕]    │
│                                 │
│  [Sblocca braccia]              │
└─────────────────────────────────┘
```

### State client

```js
state = {
  mode: 'editor' | 'jog',
  active_side: 'right' | 'left' | null,
  gizmo_mode: 'translate' | 'rotate',
  precise: true,                  // checkbox sidebar, default true
  current: { right: {position, quaternion}, left: {position, quaternion} },
  target:  { right: {position, quaternion} | null, left: ... },
  saved_poses: { name: {side, position, quaternion, note?}, ... }
}
```

Cicli:
- `state.current` → aggiornato ogni 1s da `GET /api/pose_3d/state` (auto-sync).
- `state.target[side]` → aggiornato solo durante drag dell'utente.
- Editor mode + Apply: legge `state.target` → POST /apply `dry_run=true, precise=state.precise` → al successo, `state.current = state.target` localmente; `state.target = null`.
- Jog mode + mouseup: legge `state.target` → check soglia → POST /apply `dry_run=false, precise=state.precise` → al successo, `target = null`, next polling sincronizza `current` con il robot vero.

## Componenti backend

### Router `src/presa_mano/api/pose_3d_routes.py`

Tutti gli endpoint operano sul **robot attivo** globale (`_deps.active_robot_key()`). Supporto simmetrico per `side ∈ {"left", "right"}`. Coerente con il principio di selettore robot globale.

```python
class WristPose(BaseModel):
    position: list[float]    # [x, y, z] in m
    quaternion: list[float]  # [x, y, z, w]

class NamedPose(BaseModel):
    side: Literal["left", "right"]
    position: list[float]
    quaternion: list[float]
    note: str | None = None

class StateResponse(BaseModel):
    robot_active: str
    wrist: dict[str, WristPose]      # {"left": ..., "right": ...}
    poses: dict[str, NamedPose]
    live_max_step_m: float
    timings_ms: dict[str, float]

class ApplyReq(BaseModel):
    side: Literal["left", "right"]
    position: list[float] = Field(min_length=3, max_length=3)
    quaternion: list[float] = Field(min_length=4, max_length=4)
    dry_run: bool = True
    precise: bool = True

# Endpoints
@router.get("/state")          # → StateResponse
@router.post("/apply")         # ApplyReq → {result, applied, timings_ms}
@router.get("/poses")          # → {name: NamedPose}
@router.put("/poses/{name}")   # NamedPose → {name, pose}
@router.delete("/poses/{name}")
@router.post("/poses/{name}/go")  # {dry_run: bool} → apply response
@router.post("/unlock")        # → bridge /unlock response
```

### Schema config

```yaml
pose_3d:
  live_max_step_m: 0.15
  named_poses:
    # vuoto al primo deploy; popolato dall'utente via API/GUI
    {}
```

### Quaternion normalization

Server-side: prima di passare al bridge, ogni quaternion ricevuto via `/apply` viene normalizzato. Se `||q|| < 1e-6` → 422 `quaternion is degenerate`.

### Edge cases

| Scenario | Risposta |
|---|---|
| `side` non in `{left,right}` | 422 (Pydantic Literal) |
| `position` shape errato | 422 (Pydantic) |
| `quaternion` degenere (zero norm) | 422 esplicito |
| Bridge G1 down | 502 `G1 unavailable: <err>` |
| Bridge `arms: error_timeout` | passthrough: `result.completed=false`, `stalled=true`. Client mostra UI con bottone Sblocca |
| `PUT /poses/{name}` con nome non valido | 422 `name must match ^[A-Za-z0-9_-]{1,40}$` |
| `POST /poses/{name}/go` su nome inesistente | 404 |
| `DELETE /poses/{name}` su nome inesistente | 404 |
| `PUT /poses/{name}` su nome esistente | 200 (sovrascrive); frontend chiede confirm |

### Riuso & coesistenza

- **Non duplica** la logica di right_arm_routes.py (tab Braccio DX).
- `pose_3d.named_poses` indipendente da `tab_right_arm.{home_pose,custom_pose}`.
- `precise=True` ereditato di default da G1Client (modificato in sessione precedente).

## Error handling

### Frontend

- Fetch fallisce (5xx/network): banner rosso in cima al pannello con `detail`, niente alert modali.
- Bridge `stalled` dopo Apply: pannello mostra `position_error_mm` e bottone "Sblocca braccia". Conserva la modifica locale (ghost resta dove l'utente l'aveva trascinato): l'utente può ritentare con Apply senza ridraggare.
- Polling `/state` fallisce: dim del riquadro 3D + label "stato non aggiornato — ultimo successo: 12s fa". Non blocca interazioni offline.
- Drag su polso, poi cambio active radio button: il drag corrente viene committato come target locale e l'altro polso diventa attivo.
- Jog mode + delta > soglia: dialog `confirm()` standard con i due bottoni Sì/No.

### Backend

- Tutti gli endpoint hanno `Stopwatch` step e ritornano `timings_ms`.
- Errori da G1Client → 502 con detail.
- Validazione Pydantic auto su tutti i request body.

## Testing

### Unit (puro, no I/O)

`tests/test_pose_3d_quaternion.py`:
- normalizzazione quaternion non normalizzato → norma 1
- quaternion zero/degenere → ValueError

### Integration (FastAPI TestClient + G1 mockato)

`tests/test_pose_3d_routes.py`:

- `test_state_returns_both_wrists` — mocka `_deps.g1().wrist()`, verifica struttura.
- `test_state_502_on_g1_down` — `G1Unavailable` → 502.
- `test_apply_dry_run_calls_g1_with_dry_run_true` — verifica kwargs passati a `wrist_absolute`.
- `test_apply_real_calls_g1_dry_run_false`.
- `test_apply_422_bad_quaternion_degenerate`.
- `test_apply_422_bad_side`.
- `test_apply_normalizes_quaternion` — passa quat non normalizzato, verifica che al G1 arriva normalizzato.
- `test_put_pose_persists_in_config` — usa fixture `_restore_config_yaml`.
- `test_put_pose_422_bad_name` — nome con caratteri non validi.
- `test_get_poses_returns_saved`.
- `test_delete_pose_404_when_missing`.
- `test_delete_pose_removes`.
- `test_go_pose_404_when_missing`.
- `test_go_pose_executes_via_apply`.
- `test_unlock_proxies_to_bridge` — mocka httpx.

### Test manuale post-implementazione

1. Apri tab 3D → torso + 2 polso-sfere con UCS, current pose riflette robot.
2. Click polso dx → gizmo translate appare.
3. Trascina freccia X +50 mm → ghost dx avanti di 5 cm, numeri pannello aggiornati.
4. Editor mode + Apply → ghost diventa current locale, robot non si muove (verifico log).
5. Jog mode + drag +10 mm + rilascio → robot si muove di 1 cm.
6. Jog mode + drag +200 mm → dialog conferma; cliccando No, ghost resta lì, robot fermo.
7. Save pose "test1" → voce in dropdown.
8. Sposta polso manualmente, poi Load+Vai "test1" → robot torna alla posa salvata.

## Out of scope (rinviato a future iterazioni)

- Visualizzazione realistica del braccio durante drag (richiede IK client-side o nuovo endpoint bridge).
- Joint mode (controllo per giunto, es. elbow=90°) — il bridge G1 al momento non espone endpoint per setting di singoli giunti; serve estensione del bridge.
- Streaming continuo del jog (drag attivo → robot insegue in tempo reale) — più complesso e rischioso. Per ora discreto (1 drag = 1 move al mouseup).
- Migrazione dei named_poses dai config orchestrator ai preset del bridge G1 — pianificata ma fuori scope.
- URDF reale del G1 con mesh — schema semplificato per ora.
- Test JS frontend.