fix: robustezza web/gui/legacy (lock matcher, LRU cache, clamp ROI, overlay)

- server: lock globale matcher (race nel threadpool FastAPI), LRU su
  _IMG_CACHE e _RECIPE_MATCHERS (leak), clamp ROI in tutti gli endpoint
  (400/422 invece di crash 500, check train senza varianti),
  filtro_fp=off disabilita davvero il verify NCC, fallback FILTRO_FP_MAP
  = medio, verify_threshold ricetta allineato a 0.4, _draw_matches su
  crop locale (era warp+Sobel full-frame per ogni match), spread_radius
  default 5->4
- gui: centro overlay edge (W-1)/2 -> W/2 (coerenza col train),
  spread_radius 5->4
- matcher legacy: _angle_list include estremo, cap candidati top-level,
  save/load persiste template_gray
- auto_tune: ref centrato fuori dal loop angoli
- test_suite: check imread con errore chiaro

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

pm2d/matcher.py

@@ -91,8 +91,16 @@ class EdgeShapeMatcher:
         a0, a1 = self.angle_range_deg
         if self.angle_step_deg <= 0 or a0 >= a1:
             return [float(a0)]
-        n = int(np.floor((a1 - a0) / self.angle_step_deg))
-        return [float(a0 + i * self.angle_step_deg) for i in range(n)]
+        # n+1 valori per includere l'estremo superiore del range: con il
+        # solo floor un range [0, 90] step 5 si fermava a 85° (off-by-one).
+        n = int(np.floor((a1 - a0) / self.angle_step_deg)) + 1
+        angles = [float(a0 + i * self.angle_step_deg) for i in range(n)]
+        if a1 - a0 >= 360.0:
+            # Range che copre il giro completo: a0+360° è la stessa pose di
+            # a0, escludi il duplicato (variante inutile in train/find).
+            eps = 1e-6
+            angles = [a for a in angles if a < a0 + 360.0 - eps]
+        return angles
 
     def train(self, template_bgr: np.ndarray) -> int:
         """Genera varianti per tutte le combinazioni (angolo, scala)."""
@@ -222,6 +230,14 @@ class EdgeShapeMatcher:
             for y, x in zip(ys, xs):
                 candidates.append((float(res[y, x]), int(x), int(y), ti))
 
+        # Cap candidati top-level: senza limite np.where con soglia bassa
+        # può generare migliaia di candidati, ognuno con un matchTemplate
+        # full-res nel refinement. Tieni solo i migliori per score.
+        max_candidates = max(1, max_matches * 10)
+        if len(candidates) > max_candidates:
+            candidates.sort(key=lambda c: -c[0])
+            candidates = candidates[:max_candidates]
+
         # Refinement a risoluzione piena: per ogni candidato top, finestra locale
         refined: list[tuple[float, int, int, int]] = []
         margin = sf + 4
@@ -294,6 +310,10 @@ class EdgeShapeMatcher:
         )
         arrays = {f"edge_{i}": t.edge for i, t in enumerate(self.templates)}
         arrays.update({f"mask_{i}": t.mask for i, t in enumerate(self.templates)})
+        # Persisti anche il grayscale originale: senza, l'overlay edge
+        # spariva dopo load() (template_gray restava None).
+        if self.template_gray is not None:
+            arrays["template_gray"] = self.template_gray
         np.savez_compressed(path, params=params, meta=meta, **arrays)
 
     @classmethod
@@ -312,6 +332,10 @@ class EdgeShapeMatcher:
             top_score_factor=float(p[12]) if len(p) > 12 else 0.6,
         )
         m.template_size = (int(p[8]), int(p[9]))
+        # Retrocompatibilità: modelli salvati prima non hanno template_gray
+        # (resta None: overlay edge non disponibile ma find() funziona).
+        if "template_gray" in z.files:
+            m.template_gray = z["template_gray"]
         meta = z["meta"]
         for i in range(len(meta)):
             m.templates.append(