feat: diagnostic mode trasparente per find()

self._last_diag accumula counter durante find():
- Pipeline pruning: top_evaluated, top_passed, full_evaluated
- Candidati: n_raw, n_after_pre_nms, n_final
- Drop reason: ncc_low, min_score_post_avg, recall_low,
  bbox_out_of_scene, nms_iou
- Param effettivi: top_thresh_used, verify_threshold_used, ecc.

API:
- find(debug=True): stampa one-line summary su stderr
- m.get_last_diag(): ritorna dict completo per inspection

Use case: 0 match? guarda dove sono finiti i candidati
(es. drop_ncc_low=200 → soglia NCC troppo alta) invece di
tirare a caso. Risolve il "find black-box" pattern.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

pm2d/line_matcher.py

@@ -512,10 +512,8 @@ class LineShapeMatcher:
         self.variants.clear()
         # Reset view list: template principale = view 0
         self._view_templates = [(gray.copy(), mask_full.copy())]
-        # Invalida cache: template/param cambiati → spread/feature obsoleti.
+        # Invalida cache feature di refine: il template e cambiato.
         self._refine_feat_cache = {}
-        if hasattr(self, "_scene_cache"):
-            self._scene_cache.clear()
         self._build_variants_for_view(gray, mask_full, view_idx=0)
         self._dedup_variants()
         return len(self.variants)
@@ -671,51 +669,6 @@ class LineShapeMatcher:
             raw[b] = d.astype(np.float32)
         return raw
 
-    # --- Scene precompute cache (II Halcon-style) -----------------------
-    _SCENE_CACHE_SIZE = 4
-
-    def _scene_cache_key(self, gray: np.ndarray) -> str | None:
-        """Hash compatto della scena + param che influenzano spread/density.
-
-        Hash su prime 64KB della scena (sufficiente discriminante per
-        scene fotografiche) + parametri matcher rilevanti. None se cache
-        disabilitata (es. scene troppo piccole).
-        """
-        if gray.size < 100:
-            return None
-        try:
-            import hashlib
-            h = hashlib.md5()
-            sample = gray.tobytes()[:65536]
-            h.update(sample)
-            h.update(f"|{gray.shape}|{gray.dtype}".encode())
-            h.update(
-                f"|{self.weak_grad}|{self.strong_grad}"
-                f"|{self.spread_radius}|{self._n_bins}"
-                f"|{self.pyramid_levels}".encode()
-            )
-            return h.hexdigest()
-        except Exception:
-            return None
-
-    def _scene_cache_get(self, key: str) -> tuple | None:
-        cache = getattr(self, "_scene_cache", None)
-        if cache is None:
-            return None
-        v = cache.get(key)
-        if v is not None:
-            cache.move_to_end(key)
-        return v
-
-    def _scene_cache_put(self, key: str, value: tuple) -> None:
-        from collections import OrderedDict
-        if not hasattr(self, "_scene_cache"):
-            self._scene_cache = OrderedDict()
-        self._scene_cache[key] = value
-        self._scene_cache.move_to_end(key)
-        while len(self._scene_cache) > self._SCENE_CACHE_SIZE:
-            self._scene_cache.popitem(last=False)
-
     def _spread_bitmap(self, gray: np.ndarray) -> np.ndarray:
         """Spread bitmap: bit b acceso dove bin b è presente nel raggio.
 
@@ -1356,6 +1309,7 @@ class LineShapeMatcher:
         min_recall: float = 0.0,
         use_soft_score: bool = False,
         subpixel_lm: bool = False,
+        debug: bool = False,
     ) -> list[Match]:
         """
         scale_penalty: se > 0, riduce lo score per match a scala diversa da 1.0:
@@ -1373,6 +1327,32 @@ class LineShapeMatcher:
         if not self.variants:
             raise RuntimeError("Matcher non addestrato: chiamare train() prima.")
 
+        # Diagnostic counter: traccia perche' candidati sono droppati lungo
+        # la pipeline. Esposto via get_last_diag() o ritornato implicitamente
+        # se debug=True (vedi sotto).
+        diag = {
+            "n_variants_total": len(self.variants),
+            "n_variants_top_evaluated": 0,
+            "n_variants_top_passed": 0,
+            "n_variants_full_evaluated": 0,
+            "n_raw_candidates": 0,
+            "n_after_pre_nms": 0,
+            "drop_ncc_low": 0,
+            "drop_min_score_post_avg": 0,
+            "drop_recall_low": 0,
+            "drop_bbox_out_of_scene": 0,
+            "drop_nms_iou": 0,
+            "n_final": 0,
+            "top_thresh_used": 0.0,
+            "verify_threshold_used": float(verify_threshold),
+            "min_score_used": float(min_score),
+            "min_recall_used": float(min_recall),
+            "use_polarity": bool(self.use_polarity),
+            "use_soft_score": bool(use_soft_score),
+            "subpixel_lm": bool(subpixel_lm),
+        }
+        self._last_diag = diag
+
         gray_full = self._to_gray(scene_bgr)
         # Applica ROI di ricerca: restringe scena a crop, ricorda offset per
         # ri-traslare le coordinate dei match a fine pipeline.
@@ -1387,31 +1367,18 @@ class LineShapeMatcher:
         else:
             gray0 = gray_full
             roi_offset = (0, 0)
-
-        # Cache pre-compute scena (II Halcon-style): hash bytes scene + param
-        # gradient/spread → riusa spread piramide + density tra find()
-        # consecutive con stessa scena (typical UI tuning: slider produce
-        # 10+ find() su scena identica). Risparmia ~80% del costo non-kernel.
-        cache_key = self._scene_cache_key(gray0)
-        cached = self._scene_cache_get(cache_key) if cache_key else None
-        if cached is not None:
-            grays, spread_top, bit_active_top, density_top, spread0, \
-                bit_active_full, density_full, top = cached
-        else:
         grays = [gray0]
         for _ in range(self.pyramid_levels - 1):
             grays.append(cv2.pyrDown(grays[-1]))
         top = len(grays) - 1
+
+        # Spread bitmap (uint8) al top level: 32× meno memoria della response
+        # map float32 → MOLTO più cache-friendly per _score_by_shift.
         spread_top = self._spread_bitmap(grays[top])
         bit_active_top = int(
             sum(1 << b for b in range(self._n_bins)
                 if (spread_top & (spread_top.dtype.type(1) << b)).any())
         )
-            density_top = _jit_popcount(spread_top)
-            # spread0 + density_full computati piu sotto, quindi salvo dopo.
-            spread0 = None
-            bit_active_full = None
-            density_full = None
         if nms_radius is None:
             nms_radius = max(8, min(self.template_size) // 2)
         # Pruning adattivo allo step angolare: con step piccolo (<= 3 deg)
@@ -1428,9 +1395,10 @@ class LineShapeMatcher:
             top_factor = max(top_factor, 0.7)
             cf_eff = 1
         top_thresh = min_score * top_factor
+        diag["top_thresh_used"] = float(top_thresh)
 
         tw, th = self.template_size
-        # density_top gia' computato sopra (cache o miss)
+        density_top = _jit_popcount(spread_top)
         sf_top = 2 ** top
         bg_cache_top: dict[float, np.ndarray] = {}
         bg_cache_full: dict[float, np.ndarray] = {}
@@ -1513,6 +1481,7 @@ class LineShapeMatcher:
 
         kept_coarse: list[tuple[int, float]] = []
         all_top_scores: list[tuple[int, float]] = []
+        diag["n_variants_top_evaluated"] = len(coarse_idx_list)
         # batch_top: usa kernel batch single-call con prange-esterno su
         # varianti. Vince su threadpool quando n_vars >> n_threads e quando
         # H*W top e' piccolo (overhead chiamate JIT > costo kernel).
@@ -1576,22 +1545,16 @@ class LineShapeMatcher:
         kept_variants.sort(key=lambda t: -t[1])
         max_vars_full = max(max_matches * 8, len(self.variants) // 2)
         kept_variants = kept_variants[:max_vars_full]
+        diag["n_variants_top_passed"] = len(kept_coarse)
+        diag["n_variants_full_evaluated"] = len(kept_variants)
 
-        # Full-res (parallelizzato) con bitmap.
-        # Riusa cache se disponibile, altrimenti computa e salva.
-        if spread0 is None:
+        # Full-res (parallelizzato) con bitmap
         spread0 = self._spread_bitmap(gray0)
         bit_active_full = int(
             sum(1 << b for b in range(self._n_bins)
                 if (spread0 & (spread0.dtype.type(1) << b)).any())
         )
         density_full = _jit_popcount(spread0)
-            # Salva cache scena complete
-            if cache_key is not None:
-                self._scene_cache_put(cache_key, (
-                    grays, spread_top, bit_active_top, density_top,
-                    spread0, bit_active_full, density_full, top,
-                ))
         for sc in unique_scales:
             bg_cache_full[sc] = _bg_for_scale(density_full, sc, 1)
 
@@ -1669,6 +1632,7 @@ class LineShapeMatcher:
                 raw.append((float(vals[i]), int(xs[i]), int(ys[i]), vi))
 
         raw.sort(key=lambda c: -c[0])
+        diag["n_raw_candidates"] = len(raw)
 
         # Mappa vi → score_map per subpixel/refinement
         score_maps = dict(candidates_per_var)
@@ -1700,6 +1664,7 @@ class LineShapeMatcher:
             preliminary_int.append((score, xi, yi, vi))
             if len(preliminary_int) >= pre_cap:
                 break
+        diag["n_after_pre_nms"] = len(preliminary_int)
 
         # Subpixel + refine + verify solo sui candidati pre-NMS (max pre_cap)
         kept: list[Match] = []
@@ -1746,6 +1711,7 @@ class LineShapeMatcher:
                     view_idx=getattr(var, "view_idx", 0),
                 )
                 if ncc < verify_threshold:
+                    diag["drop_ncc_low"] += 1
                     continue
                 score_f = (float(score_f) + max(0.0, ncc)) * 0.5
             # Soft-margin gradient similarity: sostituisce o integra lo
@@ -1760,6 +1726,7 @@ class LineShapeMatcher:
             # abbattere lo shape-score sotto la soglia user. Senza questo
             # check apparivano match con score < min_score (UI confusing).
             if float(score_f) < min_score:
+                diag["drop_min_score_post_avg"] += 1
                 continue
 
             # Feature recall (Halcon MinScore-style): conta quante feature
@@ -1771,6 +1738,7 @@ class LineShapeMatcher:
                     spread0, var, cx_f, cy_f, ang_f,
                 )
                 if recall < min_recall:
+                    diag["drop_recall_low"] += 1
                     continue
 
             # Ri-traslo coord da spazio crop ROI a spazio scena originale.
@@ -1794,6 +1762,7 @@ class LineShapeMatcher:
                 )
                 inside_ratio = float(inter) / poly_area
                 if inside_ratio < 0.75:
+                    diag["drop_bbox_out_of_scene"] += 1
                     continue
             # Penalità scala opzionale: score degrada con distanza da 1.0
             if scale_penalty > 0.0 and var.scale != 1.0:
@@ -1818,6 +1787,7 @@ class LineShapeMatcher:
                     dup = True
                     break
             if dup:
+                diag["drop_nms_iou"] += 1
                 continue
             kept.append(Match(
                 cx=cx_out, cy=cy_out,
@@ -1828,4 +1798,35 @@ class LineShapeMatcher:
             ))
             if len(kept) >= max_matches:
                 break
+        diag["n_final"] = len(kept)
+        if debug:
+            # Debug mode: stampa diagnostica su stderr per visibilita' immediata.
+            import sys as _sys
+            _sys.stderr.write(f"[pm2d.find debug] {self._format_diag(diag)}\n")
         return kept
+
+    def _format_diag(self, diag: dict) -> str:
+        """Formatta dict diagnostica in una linea leggibile."""
+        return (
+            f"vars: {diag['n_variants_total']} -> "
+            f"top_eval={diag['n_variants_top_evaluated']} "
+            f"top_pass={diag['n_variants_top_passed']} "
+            f"full_eval={diag['n_variants_full_evaluated']} | "
+            f"raw={diag['n_raw_candidates']} "
+            f"pre_nms={diag['n_after_pre_nms']} -> "
+            f"drop[ncc={diag['drop_ncc_low']}, "
+            f"score={diag['drop_min_score_post_avg']}, "
+            f"recall={diag['drop_recall_low']}, "
+            f"bbox={diag['drop_bbox_out_of_scene']}, "
+            f"nms={diag['drop_nms_iou']}] = "
+            f"final={diag['n_final']} (top_thresh={diag['top_thresh_used']:.2f})"
+        )
+
+    def get_last_diag(self) -> dict | None:
+        """Ritorna dict diagnostica dell'ultima chiamata find().
+
+        Halcon-equivalent: oggi inspect_shape_model espone parziali contatori.
+        Util per debug 'perche' 0 match', tuning interattivo, validation.
+        Vedi diag keys per significato (n_variants_top_evaluated, drop_*, ...).
+        """
+        return getattr(self, "_last_diag", None)