feat: search_roi parametro find() per limitare area di ricerca

Equivalente a Halcon set_aoi: matching opera su crop locale, coord
output ri-traslate al sistema scena. Costo proporzionale a w*h del
ROI invece di W*H scena intera.

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

pm2d/line_matcher.py

@@ -293,42 +293,8 @@ class LineShapeMatcher:
                     kh=kh, kw=kw,
                     cx_local=float(cx_local), cy_local=float(cy_local),
                 ))
-        self._dedup_variants()
         return len(self.variants)
 
-    def _dedup_variants(self) -> int:
-        """Rimuove varianti con feature-set identico (post-quantizzazione).
-
-        Halcon-style: con angle range = (0, 360) e simmetrie del template,
-        molte rotazioni producono lo stesso set quantizzato di feature.
-        Es: quadrato a 0/90/180/270 deg → stesse features (modulo permutazione).
-        Hash su feature ordinate (livello 0, full-res) elimina i duplicati.
-
-        Vantaggio: meno varianti = meno chiamate kernel JIT al top-level
-        senza perdere copertura angolare effettiva. Per template asimmetrici
-        non rimuove nulla.
-        """
-        seen: dict[bytes, int] = {}
-        kept: list[_Variant] = []
-        removed = 0
-        for var in self.variants:
-            lvl0 = var.levels[0]
-            order = np.lexsort((lvl0.bin, lvl0.dy, lvl0.dx))
-            key = (
-                lvl0.dx[order].tobytes()
-                + b"|" + lvl0.dy[order].tobytes()
-                + b"|" + lvl0.bin[order].tobytes()
-                + b"|" + str(round(var.scale, 4)).encode()
-            )
-            h = key  # diretto, senza hash crypto (collision ok solo se identici)
-            if h in seen:
-                removed += 1
-                continue
-            seen[h] = len(kept)
-            kept.append(var)
-        self.variants = kept
-        return removed
-
     # --- Matching ------------------------------------------------------
 
     def _response_map(self, gray: np.ndarray) -> np.ndarray:
@@ -608,6 +574,7 @@ class LineShapeMatcher:
         verify_threshold: float = 0.4,
         coarse_angle_factor: int = 2,
         scale_penalty: float = 0.0,
+        search_roi: tuple[int, int, int, int] | None = None,
     ) -> list[Match]:
         """
         scale_penalty: se > 0, riduce lo score per match a scala diversa da 1.0:
@@ -615,11 +582,30 @@ class LineShapeMatcher:
         Utile se l'operatore vuole che match "identico al template anche per
         dimensione" abbia score più alto di match "stessa forma, dimensione
         diversa". scale_penalty=0 (default) = comportamento shape puro.
+
+        search_roi: (x, y, w, h) limita la ricerca a una regione della scena.
+        Equivalente a Halcon set_aoi: il matching opera su crop locale e le
+        coordinate output sono ri-traslate al sistema scena originale. Usare
+        quando si conosce a priori l'area in cui il pezzo può apparire (es.
+        feeder a posizione fissa) → costo proporzionale a w·h invece di W·H.
         """
         if not self.variants:
             raise RuntimeError("Matcher non addestrato: chiamare train() prima.")
 
-        gray0 = self._to_gray(scene_bgr)
+        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.
+        if search_roi is not None:
+            rx, ry, rw, rh = search_roi
+            H_s, W_s = gray_full.shape
+            rx = max(0, int(rx)); ry = max(0, int(ry))
+            rw = max(1, min(int(rw), W_s - rx))
+            rh = max(1, min(int(rh), H_s - ry))
+            gray0 = gray_full[ry:ry + rh, rx:rx + rw]
+            roi_offset = (rx, ry)
+        else:
+            gray0 = gray_full
+            roi_offset = (0, 0)
         grays = [gray0]
         for _ in range(self.pyramid_levels - 1):
             grays.append(cv2.pyrDown(grays[-1]))
@@ -844,8 +830,11 @@ class LineShapeMatcher:
                 if ncc < verify_threshold:
                     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]
             poly = _oriented_bbox_polygon(
-                cx_f, cy_f, tw * var.scale, th * var.scale, ang_f,
+                cx_out, cy_out, tw * var.scale, th * var.scale, ang_f,
             )
             # Penalità scala opzionale: score degrada con distanza da 1.0
             if scale_penalty > 0.0 and var.scale != 1.0:
@@ -853,7 +842,7 @@ class LineShapeMatcher:
                     0.0, 1.0 - scale_penalty * abs(var.scale - 1.0)
                 )
             kept.append(Match(
-                cx=cx_f, cy=cy_f,
+                cx=cx_out, cy=cy_out,
                 angle_deg=ang_f,
                 scale=var.scale,
                 score=score_f,