feat: add_template_view - multi-template ensemble (Halcon-style)

Aggiunge una view extra al matcher gia addestrato. Le varianti
della nuova view vengono APPENDATE a self.variants col tag view_idx
e partecipano al pruning/matching come le altre.

NCC verify usa il template della view che ha matchato (via
_get_view_template + parametro view_idx propagato a _verify_ncc).

Halcon-equivalent: create_aniso_shape_model con fusione N viste.
Use case: pezzo che cambia aspetto (chiaro/scuro, prima/dopo
trattamento, illuminazioni diverse) → un solo matcher robusto
invece di N matcher distinti.

API:
    m.train(template_chiaro)
    m.add_template_view(template_scuro)
    m.find(scene)  # match su entrambi gli aspetti

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

pm2d/line_matcher.py

@@ -125,6 +125,11 @@ class _Variant:
     kw: int
     cx_local: float   # centro-modello dentro al bbox kernel
     cy_local: float
+    # Indice template view (X feature - multi-template ensemble).
+    # 0 = template principale del train(); 1+ = view aggiunte via
+    # add_template_view(). Usato in _verify_ncc/_compute_recall per
+    # scegliere il template gray corretto per match.
+    view_idx: int = 0
 
 
 class LineShapeMatcher:
@@ -170,6 +175,11 @@ class LineShapeMatcher:
         self.template_gray: np.ndarray | None = None
         # Maschera usata in training (propagata al refine per coerenza).
         self._train_mask: np.ndarray | None = None
+        # Multi-template ensemble (X feature): N view dello stesso pezzo
+        # (chiari/scuri, condizioni diverse). Template principale e' [0],
+        # view aggiunte via add_template_view() sono [1+]. Match restituisce
+        # la view che ha matchato meglio.
+        self._view_templates: list[tuple[np.ndarray, np.ndarray | None]] = []
 
     # --- Helpers -------------------------------------------------------
 
@@ -314,8 +324,60 @@ class LineShapeMatcher:
         self._train_mask = mask_full.copy()
 
         self.variants.clear()
+        # Reset view list: template principale = view 0
+        self._view_templates = [(gray.copy(), mask_full.copy())]
         # Invalida cache feature di refine: il template e cambiato.
         self._refine_feat_cache = {}
+        self._build_variants_for_view(gray, mask_full, view_idx=0)
+        self._dedup_variants()
+        return len(self.variants)
+
+    def add_template_view(
+        self, template_bgr: np.ndarray, mask: np.ndarray | None = None,
+    ) -> int:
+        """Aggiunge una view template extra all'ensemble (Halcon-style
+        create_aniso_shape_model con fusione N viste).
+
+        Genera varianti del nuovo template con stessi parametri (range
+        angle/scale) e le APPENDE a self.variants. NCC/recall usano
+        automaticamente il template della view che ha matchato.
+
+        Use case: pezzo che cambia aspetto (chiaro/scuro, prima/dopo
+        trattamento, illuminazioni diverse) → un solo matcher resistente.
+
+        Ritorna numero TOTALE varianti dopo l'aggiunta. Le view sono
+        indicizzate da 1 in poi (0 e' il template del train).
+        """
+        if not self.variants:
+            raise RuntimeError(
+                "Chiamare train(template_principale) prima di add_template_view")
+        gray = self._to_gray(template_bgr)
+        h, w = gray.shape
+        if (w, h) != self.template_size:
+            # Resize per coerenza con bbox/poly
+            gray = cv2.resize(gray, self.template_size, interpolation=cv2.INTER_LINEAR)
+            if mask is not None:
+                mask = cv2.resize(mask, self.template_size, interpolation=cv2.INTER_NEAREST)
+        if mask is None:
+            mask_full = np.full(gray.shape, 255, dtype=np.uint8)
+        else:
+            mask_full = (mask > 0).astype(np.uint8) * 255
+        view_idx = len(self._view_templates)
+        self._view_templates.append((gray.copy(), mask_full.copy()))
+        n_before = len(self.variants)
+        self._build_variants_for_view(gray, mask_full, view_idx=view_idx)
+        self._dedup_variants()
+        return len(self.variants) - n_before
+
+    def _build_variants_for_view(
+        self, gray: np.ndarray, mask_full: np.ndarray, view_idx: int,
+    ) -> None:
+        """Estrae varianti rotate+scalate per UNA view template.
+
+        Estrazione algorithm identica al train() originale, separato per
+        riuso da add_template_view (multi-template ensemble).
+        """
+        h, w = gray.shape
         for s in self._scale_list():
             sw = max(16, int(round(w * s)))
             sh = max(16, int(round(h * s)))
@@ -369,9 +431,8 @@ class LineShapeMatcher:
                     levels=levels,
                     kh=kh, kw=kw,
                     cx_local=float(cx_local), cy_local=float(cy_local),
+                    view_idx=view_idx,
                 ))
-        self._dedup_variants()
-        return len(self.variants)
 
     def _dedup_variants(self) -> int:
         """Rimuove varianti con feature-set identico (post-quantizzazione).
@@ -740,115 +801,23 @@ class LineShapeMatcher:
                 s2, cx2, cy2 = _score_at_angle(x2)
         return best
 
-    def _subpixel_refine_lm(
+    def _get_view_template(
-        self, scene_gray: np.ndarray, variant: _Variant,
+        self, view_idx: int,
-        cx: float, cy: float, angle_deg: float,
+    ) -> tuple[np.ndarray | None, np.ndarray | None]:
-        n_iters: int = 2,
+        """Ritorna (template_gray, mask) per la view specificata.
-    ) -> tuple[float, float]:
-        """Sub-pixel refinement iterativo via gradient-field least-squares.
 
-        Halcon-equivalent SubPixel='least_squares_high'. Per ogni feature
+        view_idx 0 = template principale (train), 1+ = view extra
-        template, calcola residuo = projection lungo gradient direction
+        aggiunte via add_template_view. Usato per scegliere il template
-        sull'edge subpixel scena. Ottimizza traslazione (dx, dy) che
+        corretto in NCC/recall verification quando il matcher e'
-        minimizza sum dei residui pesati, in iterazione.
+        ensemble multi-template.
-
-        Precisione attesa ±0.05 px (vs ±0.5 di quadratic fit 2D semplice).
         """
-        if self.template_gray is None:
+        if 0 <= view_idx < len(self._view_templates):
-            return cx, cy
+            return self._view_templates[view_idx]
-        h, w = self.template_gray.shape
+        return self.template_gray, self._train_mask
-        scale = variant.scale
-        sw = max(16, int(round(w * scale)))
-        sh = max(16, int(round(h * scale)))
-        gray_s = cv2.resize(self.template_gray, (sw, sh), interpolation=cv2.INTER_LINEAR)
-        mask_src = (
-            self._train_mask if self._train_mask is not None
-            else np.full_like(self.template_gray, 255)
-        )
-        mask_s = cv2.resize(mask_src, (sw, sh), interpolation=cv2.INTER_NEAREST)
-        diag = int(np.ceil(np.hypot(sh, sw))) + 6
-        py = (diag - sh) // 2; px = (diag - sw) // 2
-        gray_p = cv2.copyMakeBorder(
-            gray_s, py, diag - sh - py, px, diag - sw - px, cv2.BORDER_REPLICATE,
-        )
-        mask_p = cv2.copyMakeBorder(
-            mask_s, py, diag - sh - py, px, diag - sw - px,
-            cv2.BORDER_CONSTANT, value=0,
-        )
-        center = (diag / 2.0, diag / 2.0)
-        M = cv2.getRotationMatrix2D(center, angle_deg, 1.0)
-        gray_r = cv2.warpAffine(gray_p, M, (diag, diag),
-                                 flags=cv2.INTER_LINEAR,
-                                 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
 
     def _verify_ncc(
         self, scene_gray: np.ndarray, cx: float, cy: float,
-        angle_deg: float, scale: float,
+        angle_deg: float, scale: float, view_idx: int = 0,
     ) -> float:
         """NCC tra template warpato alla pose e scena sottostante.
 
@@ -860,9 +829,9 @@ class LineShapeMatcher:
         il matcher linemod può dare score alto su texture generiche ma
         sovrapponendo il template gray i pixel non corrispondono.
         """
-        if self.template_gray is None:
+        t, train_mask = self._get_view_template(view_idx)
+        if t is None:
             return 1.0
-        t = self.template_gray
         h, w = t.shape
         cx_t = (w - 1) / 2.0
         cy_t = (h - 1) / 2.0
@@ -887,8 +856,8 @@ class LineShapeMatcher:
             t, M, (cw, ch),
             flags=cv2.INTER_LINEAR, borderValue=0,
         )
-        if self._train_mask is not None:
+        if train_mask is not None:
-            mask_src = self._train_mask
+            mask_src = train_mask
         else:
             mask_src = np.full_like(t, 255)
         mask_w = cv2.warpAffine(
@@ -934,7 +903,6 @@ class LineShapeMatcher:
         greediness: float = 0.0,
         batch_top: bool = False,
         nms_iou_threshold: float = 0.3,
-        subpixel_lm: bool = False,
     ) -> list[Match]:
         """
         scale_penalty: se > 0, riduce lo score per match a scala diversa da 1.0:
@@ -1284,13 +1252,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).
@@ -1299,7 +1260,10 @@ class LineShapeMatcher:
             # ranking/visualizzazione (uno score 1.0 vero richiede sia
             # match shape sia template gray identici).
             if verify_ncc and float(score_f) < ncc_skip_above:
-                ncc = self._verify_ncc(gray0, cx_f, cy_f, ang_f, var.scale)
+                ncc = self._verify_ncc(
+                    gray0, cx_f, cy_f, ang_f, var.scale,
+                    view_idx=getattr(var, "view_idx", 0),
+                )
                 if ncc < verify_threshold:
                     continue
                 score_f = (float(score_f) + max(0.0, ncc)) * 0.5