docs: roadmap Fase 2 (precisione misurata, valutazione C++ vs algoritmico)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

ROADMAP.md

@@ -2,6 +2,36 @@
 
 Lista ragionata di miglioramenti futuri. Priorità = impatto / effort, non urgenza temporale.
 
+## Fase 2 COMPLETATA (precisione rotazione + robustezza + perf)
+
+Root cause della rotazione imprecisa: lo score satura a 1.0 sulla spread
+bitmap dilatata (raggio 4-5) → il refine non vedeva gradiente né in angolo
+né in posizione, e `cv2.minMaxLoc` sul plateau saturo spostava il centro
+sull'angolo della finestra (errore sistematico 3·√2 ≈ 4.24 px).
+
+| Fix | Dettaglio |
+|---|---|
+| Refine su bitmap fine | `_refine_angle` ottimizza su spread raggio 1 (`spread_fine`, cached); score finale ricalcolato su spread coarse per mantenere semantica soglie |
+| Picco sub-pixel nel refine | centroide plateau / fit quadratico al posto di minMaxLoc (bias top-left) |
+| LM least-squares pos+angolo | `_subpixel_refine_lm` riscritto: snap edge ±2px lungo normale + LSQ 3x3 (dx, dy, dθ), ON di default |
+| Round feature offsets | troncamento `astype(int32)` → `np.round` (bias ~0.25 px) |
+| Centro rotazione coerente | `_prepare_padded_template`: rotazione attorno al centro reale del template nel padding (bias ≤0.5 px dipendente dall'angolo) |
+| `_angle_list` include estremo | range parziali ±tol ora testano anche +tol |
+| `_refine_pose_joint` rimosso | Nelder-Mead su funzione a gradini satura: terminava subito; param ora alias di refine_angle |
+| pyramid_propagate di default | kernel windowed (feature campionano l'intera scena: prima il crop troncava le feature → score 0); picchi = massimi locali (non top-K pixel); disattivato automaticamente per template elongati (>2:1) dove il picco top-level non localizza |
+| Piramide 3 livelli default | con clamp automatico sulla dimensione template (min 12 px al top) |
+| Cache scena: hash completo | prima hashava solo i primi 64KB → collisioni tra scene con stessa banda superiore → risultati della scena sbagliata |
+| Web server | lock matcher (race con threadpool FastAPI), LRU `_IMG_CACHE`, clamp ROI ovunque (400/422 invece di 500), `filtro_fp=off` disabilita davvero NCC, `_draw_matches` su crop locale |
+| GUI/legacy | centro overlay `(W-1)/2`→`W/2`, spread_radius default 5→4, EdgeShapeMatcher: angle list endpoint + cap candidati + save template_gray |
+
+Misure (GT sintetica 7 pose, scena 900x700, VPS 2 core):
+- Errore angolare mediano: **2.3° → 0.05°** (step 5°); a step 2° era 4.4° → **0.03°**
+- Errore posizione mediano: **4.24 px → 0.04 px**
+- find GT scene: 4.7s → 1.7s; scena reale 646x482: 1.14s → 0.81s
+- Benchmark suite 16 scenari: 96.5s → 84.2s, match count ≥ baseline
+  (eccezioni: dado_full -1 = match borderline su parte diversa;
+  lama_part_preciso 25→18 con baseline al cap max_matches)
+
 ## Fase 1 COMPLETATA (branch `speedFase1`)
 
 | ID | Voce | Status | Note |
@@ -84,9 +114,14 @@ Benchmark suite 16 scenari (4 immagini × full/part × fast/preciso):
 ## Target performance produzione
 
 Obiettivi da documento tecnico Vision Suite (Fase Beta):
-- [ ] **Precisione posizionale mediana**: <0.5 px → **raggiunto con subpixel (attualmente ~0.1-0.3 px atteso)**
-- [ ] **Precisione angolare mediana**: <1.0° → **raggiunto con refinement (~0.5°)**
-- [ ] **Latency mediana**: <50 ms su 1920×1080 → **attuale ~1.7s su 830×822 (serve GPU o ulteriore CPU)**
+- [x] **Precisione posizionale mediana**: <0.5 px → **0.04 px misurato su GT sintetica (Fase 2)**
+- [x] **Precisione angolare mediana**: <1.0° → **0.05° misurato su GT sintetica (Fase 2)**
+- [ ] **Latency mediana**: <50 ms su 1920×1080 → **~0.8s su 646×482 con 2 core; da misurare su hardware produzione**
 - [ ] **F1 score dataset sintetico**: >0.95 → **da misurare con dataset sintetico**
 
-Prossimo blocker per target: **latency**. Via più promettente: GPU (CuPy) o coarse-to-fine angolare.
+Prossimo blocker per target: **latency**. Nota: i kernel hot sono gia'
+Numba JIT (≈ velocita' C, prange parallelo): un port C++ dei kernel vale
+solo il margine SIMD esplicito (~2-4x con AVX2 su AND+popcount byte-wise).
+Prima di scriverlo conviene esaurire le vie algoritmiche rimaste:
+riduzione varianti al top-level (auto angle step per livello, stile
+Halcon), greediness di default, e GPU (CuPy/OpenCL) per scene 1080p.