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,22 +740,19 @@ class LineShapeMatcher:
                 s2, cx2, cy2 = _score_at_angle(x2)
         return best
 
-    def _subpixel_refine_lm(
-        self, scene_gray: np.ndarray, variant: _Variant,
+    def _compute_recall(
+        self, spread0: np.ndarray, variant: _Variant,
         cx: float, cy: float, angle_deg: float,
-        n_iters: int = 2,
-    ) -> tuple[float, float]:
-        """Sub-pixel refinement iterativo via gradient-field least-squares.
+    ) -> float:
+        """Frazione di feature template che combaciano nello spread scena
+        alla pose (cx, cy, angle, variant.scale).
 
-        Halcon-equivalent SubPixel='least_squares_high'. Per ogni feature
-        template, calcola residuo = projection lungo gradient direction
-        sull'edge subpixel scena. Ottimizza traslazione (dx, dy) che
-        minimizza sum dei residui pesati, in iterazione.
-
-        Precisione attesa ±0.05 px (vs ±0.5 di quadratic fit 2D semplice).
+        Riusa template_gray + warp per estrarre features alla pose esatta
+        (vs feature pre-computate alla pose della variante grezza). Ritorna
+        hits/N in [0, 1]. Halcon-equivalent: questo e' il "MinScore" originale.
         """
         if self.template_gray is None:
-            return cx, cy
+            return 1.0
         h, w = self.template_gray.shape
         scale = variant.scale
         sw = max(16, int(round(w * scale)))
@@ -782,69 +779,23 @@ class LineShapeMatcher:
                                  borderMode=cv2.BORDER_REPLICATE)
         mask_r = cv2.warpAffine(mask_p, M, (diag, diag),
                                  flags=cv2.INTER_NEAREST, borderValue=0)
-        gx_t = cv2.Sobel(gray_r, cv2.CV_32F, 1, 0, ksize=3)
-        gy_t = cv2.Sobel(gray_r, cv2.CV_32F, 0, 1, ksize=3)
-        mag_t = cv2.magnitude(gx_t, gy_t)
-        _, bins_t = self._gradient(gray_r)
-        fx, fy, _ = self._extract_features(mag_t, bins_t, mask_r)
-        if len(fx) < 4:
-            return cx, cy
-        # Pre-compute template offsets e gradient direction
-        n = len(fx)
-        ddx_t = (fx - center[0]).astype(np.float32)
-        ddy_t = (fy - center[1]).astype(np.float32)
-        gx_tf = np.array([gx_t[int(fy[i]), int(fx[i])] for i in range(n)], dtype=np.float32)
-        gy_tf = np.array([gy_t[int(fy[i]), int(fx[i])] for i in range(n)], dtype=np.float32)
-        mag_tf = np.hypot(gx_tf, gy_tf) + 1e-6
-        nx_t = gx_tf / mag_tf
-        ny_t = gy_tf / mag_tf
-
-        # Gradient scena (continuo)
-        gx_s = cv2.Sobel(scene_gray, cv2.CV_32F, 1, 0, ksize=3)
-        gy_s = cv2.Sobel(scene_gray, cv2.CV_32F, 0, 1, ksize=3)
-        H, W = scene_gray.shape
-        cur_cx, cur_cy = float(cx), float(cy)
-        for _ in range(n_iters):
-            # Sample bilineare gx_s, gy_s ai punti proiettati
-            xs = cur_cx + ddx_t
-            ys = cur_cy + ddy_t
-            # Clamp
-            xs_c = np.clip(xs, 0, W - 1.001)
-            ys_c = np.clip(ys, 0, H - 1.001)
-            x0 = xs_c.astype(np.int32); y0 = ys_c.astype(np.int32)
-            ax = xs_c - x0; ay = ys_c - y0
-            def _bilin(g):
-                v00 = g[y0, x0]; v10 = g[y0, x0 + 1]
-                v01 = g[y0 + 1, x0]; v11 = g[y0 + 1, x0 + 1]
-                return ((1 - ax) * (1 - ay) * v00
-                        + ax * (1 - ay) * v10
-                        + (1 - ax) * ay * v01
-                        + ax * ay * v11)
-            sx_v = _bilin(gx_s)
-            sy_v = _bilin(gy_s)
-            mag_s = np.hypot(sx_v, sy_v) + 1e-6
-            nx_s = sx_v / mag_s
-            ny_s = sy_v / mag_s
-            # Residuo lungo direzione gradient template:
-            # discordance(theta) misurata via prodotto vettoriale (sin(delta))
-            # Valori weight: feature con scarsa magnitude scena hanno peso basso
-            w = np.minimum(mag_s, 255.0).astype(np.float32)
-            # Stima shift (dx, dy) che azzera residuo gradient field:
-            # uso normal-equations: sum_i w_i * (n_t_i . shift) * n_t_i = sum_i w_i * (n_s_i - n_t_i) ?
-            # Approccio piu' diretto: shift verso centroide gradient differences
-            err_x = (nx_s - nx_t) * w
-            err_y = (ny_s - ny_t) * w
-            # Step proporzionale a -mean(err) (gradient descent damped)
-            step_x = -float(err_x.sum()) / (w.sum() + 1e-6)
-            step_y = -float(err_y.sum()) / (w.sum() + 1e-6)
-            # Damping: limita step a 1px per iter per stabilita'
-            step_x = max(-1.0, min(1.0, step_x))
-            step_y = max(-1.0, min(1.0, step_y))
-            cur_cx += step_x
-            cur_cy += step_y
-            if abs(step_x) < 0.02 and abs(step_y) < 0.02:
-                break
-        return cur_cx, cur_cy
+        mag, bins = self._gradient(gray_r)
+        fx, fy, fb = self._extract_features(mag, bins, mask_r)
+        n_feat = len(fx)
+        if n_feat < 4:
+            return 0.0
+        H, W = spread0.shape
+        spread_dtype = spread0.dtype.type
+        ix = int(round(cx)); iy = int(round(cy))
+        hits = 0
+        for i in range(n_feat):
+            xs = ix + int(fx[i] - center[0])
+            ys = iy + int(fy[i] - center[1])
+            if 0 <= xs < W and 0 <= ys < H:
+                bit = spread_dtype(1 << int(fb[i]))
+                if spread0[ys, xs] & bit:
+                    hits += 1
+        return hits / n_feat
 
     def _verify_ncc(
         self, scene_gray: np.ndarray, cx: float, cy: float,
@@ -934,7 +885,7 @@ class LineShapeMatcher:
         greediness: float = 0.0,
         batch_top: bool = False,
         nms_iou_threshold: float = 0.3,
-        subpixel_lm: bool = False,
+        min_recall: float = 0.0,
     ) -> list[Match]:
         """
         scale_penalty: se > 0, riduce lo score per match a scala diversa da 1.0:
@@ -1284,13 +1235,6 @@ class LineShapeMatcher:
                     search_radius=self._effective_angle_step() / 2.0,
                     original_score=score,
                 )
-            # Halcon SubPixel='least_squares_high': refinement iterativo
-            # gradient-field per precisione 0.05 px (vs 0.5 quadratic 2D).
-            if subpixel_lm and self.template_gray is not None:
-                cx_lm, cy_lm = self._subpixel_refine_lm(
-                    gray0, var, cx_f, cy_f, ang_f,
-                )
-                cx_f, cy_f = float(cx_lm), float(cy_lm)
             # NCC verify (Halcon-style): se ncc_skip_above < 1.0 salta
             # il calcolo per shape-score gia alti. Default 1.01 = NCC sempre,
             # piu sicuro contro falsi positivi (lo shape-score satura facile).
@@ -1309,6 +1253,17 @@ class LineShapeMatcher:
             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]