Presa-Mano/README.md

# presa-mano

Microservizio Python (FastAPI) che orchestra:

1. **Calibrazione hand-eye** (eye-to-hand) tra la **Nuwa depth camera** (fissa) e la
   **base del robot**, usando un **ArUco sul polso**. Supporta **G1** e **H1**.
2. **Riconoscimento oggetto** via YOLO (bbox) + **segmentazione 3D** via SAM2.1 →
   nuvola di punti dell'oggetto.
3. **Calibrazione piano di lavoro** + filtro "sotto piano" applicato a ogni cloud.
4. **Pianificazione presa**: asse dell'oggetto (PCA) + posa polso per il robot attivo.

## Microservizi usati

| Servizio          | URL (default)         | Scopo                                              |
|-------------------|-----------------------|----------------------------------------------------|
| Nuwa-HP60C        | http://localhost:8877 | RGB, depth, point cloud, intrinsics                |
| Marker-finder     | http://localhost:8082 | Detection 2D ArUco (corners + pose)                |
| YOLO Server       | http://localhost:8879 | Bbox oggetto da prendere                           |
| SAM21 (NuwaSeg)   | http://localhost:8002 | Segmentazione promptable: bbox → cloud 3D filtrata |
| G1 API Server     | http://localhost:8765 | Controllo polso/mano G1 (dry-run se down)          |
| H1 API Server     | http://localhost:8767 | Controllo polso/mano H1 (network host, 4 DoF)      |

Il servizio **presa-mano** espone GUI + API su **http://localhost:8890**. Il robot attivo
è scelto da `config.yaml > robot.active` (`g1` | `h1`); l'orchestrator fa routing
automatico verso il bridge corrispondente.

## Quick start

```bash
docker compose up -d presa-mano
# Apri http://localhost:8890
```

## GUI

Tab principali:

- **Calibrazione**: muovi il polso in varie pose, *Acquisisci sample*, poi *Risolvi*.
  Salva `data/calibration_<side>.yaml`.
- **Calibrazione Piano**: clicca due angoli sull'RGB per definire la ROI sul tavolo
  → *Calcola piano* fa il fit SVD sui punti depth, mostra in 3D (vista camera) il
  piano e l'intera scena con punti esclusi in rosso / tenuti in ciano. Il parametro
  *offset (mm)* regola la soglia del filtro "punti sotto piano" (positivo = buffer
  permissivo, negativo = esclude anche un buffer sopra il piano per togliere rumore
  depth). *Salva piano* persiste in `data/work_plane.json`.
- **Cerca modello**: rileva oggetto via YOLO, segmenta via SAM21 (con fallback bbox
  se SAM21 è down), visualizza bbox + asse, esegui (toggle dry-run).
- **Movimento EE**: lettura pose correnti, invio pose assolute/relative, apri/chiudi mano,
  emergency stop.

## Pipeline cloud-from-bbox

Dopo che YOLO ha trovato un bbox, gli endpoint `/api/grasp/{plan,execute}`,
`/api/perception/{scan,object_points}` estraggono la nuvola di punti
dell'oggetto con questa pipeline:

1. **SAM21** segmenta il bbox usando RGB + depth allineata IR→RGB
   (`perception/depth_align.py`) → cloud nell'OpenCV camera frame, in metri.
   Su fallimento (transport / `SEGMENTATION_EMPTY` / `<10` punti) → fallback
   trasparente al path bbox legacy (Nuwa ROI pointcloud).
2. **Filtro piano**: se `data/work_plane.json` esiste, scarta i punti con
   `signed_distance < -offset_mm/1000` (vedi tab Calibrazione Piano).
3. Le response includono `source ∈ {"sam21","bbox_roi"}`, `plane_applied`,
   `n_points_before_plane` e — su fallback SAM21 — `sam21_fallback_reason`.

Disabilitabile via `grasp.use_sam21: false` in `config.yaml`.

## Calibrazione automatica via script

In `scripts/`:

| Script                     | Cosa fa                                                                  |
|----------------------------|--------------------------------------------------------------------------|
| `explore_and_calibrate.py` | Probe assiale dell'envelope di visibilità tag → workspace JSON + PNG → N sample random nel workspace → solve. |
| `extend_calibration.py`    | Estende la calibrazione esistente fino a `n_used >= TARGET_GOOD` (default 30). Riusa il workspace, NON cancella i sample. |
| `repeatability.py`         | N detection consecutive a polso fermo per misurare σ del marker-finder (diagnostica bias vs noise). |

Tutti producono file in `data/`: `workspace_<side>.json`, `workspace_<side>.png`,
`samples_<side>.json`, `calibration_<side>.yaml`.

## Configurazione

`config.yaml` contiene i default; l'API espone `GET/PUT /api/config` per override
runtime (es. cambiare ID/size ArUco, robot attivo, side di default).

Default rilevanti:

- `calibration.method: DANIILIDIS` — sui dati H1+Nuwa con bias intrinsics di
  marker-finder, DANIILIDIS dà ~4× meno residuo di TSAI (default OpenCV).
- `robot.active: h1` / `robot.wrist_side: right`.

## Caveat noti

- **Wrist passthrough**: i campi `speed_mm_s` e `traj_step_mm` non sono nello schema
  di `/api/wrist/{absolute,relative}`. Per move "precisi" (closed-loop, slow,
  waypoint fitti) bisogna chiamare direttamente il bridge robot, es.
  `POST http://localhost:8767/wrist/absolute` su H1.
- **Marker-finder intrinsics**: il sibling service usa intrinsics D435i bakeate che
  non corrispondono alla Nuwa → bias sistematico in `T_cam_marker`. È il floor del
  residuo hand-eye (~14 mm su H1+Nuwa). Per scendere serve ricalibrare quel servizio.
- **H1 4 DoF**: nessun polso articolato. Si comanda solo posizione; l'orientamento
  del polso è output dell'IK e drifta con la posa (fino a ~30° su Y ai bordi
  dell'envelope). I solver hand-eye risentono della scarsa diversità rotazionale.
- **`/api/arms/go_neutral`**: il proxy nell'orchestrator non è montato (404). Per
  riportare le braccia H1 a home: `POST http://localhost:8767/arms/go_neutral` diretto.

Vedi `CLAUDE.md` per i dettagli di architettura e per le frame conventions
(Nuwa native vs OpenCV vs Nuwa ROI).