feat: min_recall - Halcon-style feature recall check post-refine

_compute_recall calcola hits/N feature template alla pose finale
(post sub-pixel refine). Equivalente Halcon MinScore originale:
quante feature shape effettivamente combaciano sul match accettato.

Param min_recall (default 0 = off, backward compat). Util quando
NCC e' alto ma poche feature reali matchano (es. match parziale
su zona di simil-tessitura). Soglia 0.7-0.9 raccomandata per
filtri stringenti.

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

pm2d/line_matcher.py

@@ -740,26 +740,19 @@ class LineShapeMatcher:
                 s2, cx2, cy2 = _score_at_angle(x2)
         return best
 
-    def _compute_soft_score(
+    def _compute_recall(
-        self, scene_gray: np.ndarray, variant: _Variant,
+        self, spread0: np.ndarray, variant: _Variant,
         cx: float, cy: float, angle_deg: float,
     ) -> float:
-        """Soft-margin gradient similarity (Halcon Metric='use_polarity').
+        """Frazione di feature template che combaciano nello spread scena
+        alla pose (cx, cy, angle, variant.scale).
 
-        Score = mean(max(0, cos(theta_template - theta_scene))) sulle
+        Riusa template_gray + warp per estrarre features alla pose esatta
-        feature template alla pose, pesato per magnitude scena. Continuo
+        (vs feature pre-computate alla pose della variante grezza). Ritorna
-        in [0, 1], piu discriminante della metric a bin (Y di "Halcon
+        hits/N in [0, 1]. Halcon-equivalent: questo e' il "MinScore" originale.
-        improvements"): match a leggera rotazione = penalita' graduale
-        invece di on/off bin.
-
-        Polarity:
-        - use_polarity=True: cos(theta_t - theta_s) considera direzione
-          completa (mod 2pi)
-        - use_polarity=False: |cos(theta_t - theta_s)| considera solo
-          orientazione (mod pi)
         """
         if self.template_gray is None:
-            return 0.0
+            return 1.0
         h, w = self.template_gray.shape
         scale = variant.scale
         sw = max(16, int(round(w * scale)))
@@ -786,47 +779,23 @@ class LineShapeMatcher:
                                  borderMode=cv2.BORDER_REPLICATE)
         mask_r = cv2.warpAffine(mask_p, M, (diag, diag),
                                  flags=cv2.INTER_NEAREST, borderValue=0)
-        # Gradient template (continuo, non quantizzato)
+        mag, bins = self._gradient(gray_r)
-        gx_t = cv2.Sobel(gray_r, cv2.CV_32F, 1, 0, ksize=3)
+        fx, fy, fb = self._extract_features(mag, bins, mask_r)
-        gy_t = cv2.Sobel(gray_r, cv2.CV_32F, 0, 1, ksize=3)
+        n_feat = len(fx)
-        mag_t = cv2.magnitude(gx_t, gy_t)
+        if n_feat < 4:
-        # Estrai posizioni feature alla pose
-        _, bins_t = self._gradient(gray_r)
-        fx, fy, _ = self._extract_features(mag_t, bins_t, mask_r)
-        if len(fx) < 4:
             return 0.0
-        # Gradient scena (continuo)
+        H, W = spread0.shape
-        gx_s = cv2.Sobel(scene_gray, cv2.CV_32F, 1, 0, ksize=3)
+        spread_dtype = spread0.dtype.type
-        gy_s = cv2.Sobel(scene_gray, cv2.CV_32F, 0, 1, ksize=3)
-        H, W = scene_gray.shape
         ix = int(round(cx)); iy = int(round(cy))
-        sims = []
+        hits = 0
-        weights = []
+        for i in range(n_feat):
-        for i in range(len(fx)):
             xs = ix + int(fx[i] - center[0])
             ys = iy + int(fy[i] - center[1])
-            if not (0 <= xs < W and 0 <= ys < H):
+            if 0 <= xs < W and 0 <= ys < H:
-                continue
+                bit = spread_dtype(1 << int(fb[i]))
-            tx = float(gx_t[int(fy[i]), int(fx[i])])
+                if spread0[ys, xs] & bit:
-            ty = float(gy_t[int(fy[i]), int(fx[i])])
+                    hits += 1
-            sx = float(gx_s[ys, xs]); sy = float(gy_s[ys, xs])
+        return hits / n_feat
-            tm = math.hypot(tx, ty); sm = math.hypot(sx, sy)
-            if tm < 1e-3 or sm < 1e-3:
-                continue
-            # cos(theta_t - theta_s) = (tx*sx + ty*sy) / (tm*sm)
-            cos_sim = (tx * sx + ty * sy) / (tm * sm)
-            if not self.use_polarity:
-                # Mod pi: |cos| considera solo orientazione (no polarity)
-                cos_sim = abs(cos_sim)
-            else:
-                cos_sim = max(0.0, cos_sim)
-            sims.append(cos_sim)
-            weights.append(min(sm, 255.0))
-        if not sims:
-            return 0.0
-        sims_arr = np.asarray(sims, dtype=np.float32)
-        w_arr = np.asarray(weights, dtype=np.float32)
-        return float((sims_arr * w_arr).sum() / (w_arr.sum() + 1e-9))
 
     def _verify_ncc(
         self, scene_gray: np.ndarray, cx: float, cy: float,
@@ -916,7 +885,7 @@ class LineShapeMatcher:
         greediness: float = 0.0,
         batch_top: bool = False,
         nms_iou_threshold: float = 0.3,
-        use_soft_score: bool = False,
+        min_recall: float = 0.0,
     ) -> list[Match]:
         """
         scale_penalty: se > 0, riduce lo score per match a scala diversa da 1.0:
@@ -1278,20 +1247,23 @@ class LineShapeMatcher:
                 if ncc < verify_threshold:
                     continue
                 score_f = (float(score_f) + max(0.0, ncc)) * 0.5
-            # Soft-margin gradient similarity: sostituisce o integra lo
-            # score con metric continua (cos sim gradients) invece di
-            # bin discreto. Halcon-style: piu robusto a piccole rotazioni.
-            if use_soft_score:
-                soft = self._compute_soft_score(
-                    gray0, var, cx_f, cy_f, ang_f,
-                )
-                score_f = (float(score_f) + soft) * 0.5
             # Re-check min_score sullo score finale: NCC averaging puo
             # 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:
                 continue
 
+            # Feature recall (Halcon MinScore-style): conta quante feature
+            # template effettivamente combaciano nello spread scena alla
+            # pose finale. Scarta se sotto min_recall (default 0 = off).
+            # Util contro match parziali ad alto NCC ma poche feature reali.
+            if min_recall > 0.0:
+                recall = self._compute_recall(
+                    spread0, var, cx_f, cy_f, ang_f,
+                )
+                if recall < min_recall:
+                    continue
+
             # Ri-traslo coord da spazio crop ROI a spazio scena originale.
             cx_out = cx_f + roi_offset[0]
             cy_out = cy_f + roi_offset[1]