merge: AA eval CLI

merge: II scene cache
merge: CC diagnostic mode
2026-05-05 10:10:00 +02:00 · 2026-05-05 10:09:56 +02:00 · 2026-05-05 10:09:56 +02:00 · 2026-05-05 10:09:45 +02:00 · 2026-05-05 10:07:27 +02:00 · 2026-05-05 10:05:20 +02:00
10 changed files with 2398 additions and 110 deletions
@@ -8,3 +8,5 @@ __pycache__/
 .DS_Store
 *.log
 models/
+# Ricette pre-trained (generate da utente, non versionare)
+recipes/*.npz
@@ -110,6 +110,118 @@ if HAS_NUMBA:
                    acc[y, x] *= inv
        return acc

+    @nb.njit(cache=True, parallel=True, fastmath=True, boundscheck=False)
+    def _jit_score_bitmap_rescored_strided(
+        spread: np.ndarray,
+        dx: np.ndarray, dy: np.ndarray, bins: np.ndarray,
+        bit_active: np.uint8,
+        bg: np.ndarray,
+        stride: nb.int32,
+    ) -> np.ndarray:
+        """Variante con sub-sampling: valuta solo pixel su griglia stride×stride.
+        Score restituito ha stessa shape (H, W); celle non valutate = 0.
+
+        4× speed-up con stride=2 (NMS recupera precisione in full-res).
+        Numba prange richiede step costante: itero su indici griglia e
+        moltiplico per stride dentro il body.
+        """
+        H, W = spread.shape
+        N = dx.shape[0]
+        acc = np.zeros((H, W), dtype=np.float32)
+        ny = (H + stride - 1) // stride
+        nx = (W + stride - 1) // stride
+        for yi in nb.prange(ny):
+            y = yi * stride
+            for i in range(N):
+                b = bins[i]
+                mask = np.uint8(1) << b
+                if (bit_active & mask) == 0:
+                    continue
+                ddy = dy[i]
+                yy = y + ddy
+                if yy < 0 or yy >= H:
+                    continue
+                ddx = dx[i]
+                x_lo = 0 if ddx >= 0 else -ddx
+                x_hi = W if ddx <= 0 else W - ddx
+                rem = x_lo % stride
+                if rem != 0:
+                    x_lo += stride - rem
+                x = x_lo
+                while x < x_hi:
+                    if spread[yy, x + ddx] & mask:
+                        acc[y, x] += 1.0
+                    x += stride
+        if N > 0:
+            inv = 1.0 / N
+            for yi in nb.prange(ny):
+                y = yi * stride
+                for xi in range(nx):
+                    x = xi * stride
+                    v = acc[y, x] * inv
+                    bgv = bg[y, x]
+                    if bgv < 1.0:
+                        r = (v - bgv) / (1.0 - bgv + 1e-6)
+                        acc[y, x] = r if r > 0.0 else 0.0
+                    else:
+                        acc[y, x] = 0.0
+        return acc
+
+    @nb.njit(cache=True, parallel=True, fastmath=True, boundscheck=False)
+    def _jit_score_bitmap_greedy(
+        spread: np.ndarray,
+        dx: np.ndarray, dy: np.ndarray, bins: np.ndarray,
+        bit_active: np.uint8,
+        min_score: nb.float32,
+        greediness: nb.float32,
+    ) -> np.ndarray:
+        """Score bitmap con early-exit greedy (no rescore background).
+
+        Per ogni pixel iteriamo le N feature; abortiamo non appena diventa
+        impossibile raggiungere `min_required` count anche aggiungendo
+        tutte le feature rimanenti. min_required = greediness * min_score * N.
+
+        greediness=0 → nessun early-exit (equivalente a kernel base).
+        greediness=1 → exit non appena hits + remaining < min_score * N.
+        Tipico: 0.7-0.9 → 2-4x speed-up senza perdere match.
+        """
+        H, W = spread.shape
+        N = dx.shape[0]
+        acc = np.zeros((H, W), dtype=np.float32)
+        if N == 0:
+            return acc
+        min_req = greediness * min_score * N
+        inv_N = nb.float32(1.0 / N)
+        for y in nb.prange(H):
+            for x in range(W):
+                hits = 0
+                for i in range(N):
+                    b = bins[i]
+                    mask = np.uint8(1) << b
+                    if (bit_active & mask) == 0:
+                        if hits + (N - i - 1) < min_req:
+                            break
+                        continue
+                    ddy = dy[i]
+                    yy = y + ddy
+                    if yy < 0 or yy >= H:
+                        if hits + (N - i - 1) < min_req:
+                            break
+                        continue
+                    ddx = dx[i]
+                    xx = x + ddx
+                    if xx < 0 or xx >= W:
+                        if hits + (N - i - 1) < min_req:
+                            break
+                        continue
+                    if spread[yy, xx] & mask:
+                        hits += 1
+                    else:
+                        if hits + (N - i - 1) < min_req:
+                            break
+                acc[y, x] = nb.float32(hits) * inv_N
+        return acc
+
    @nb.njit(cache=True, parallel=True, fastmath=True, boundscheck=False)
    def _jit_score_bitmap_rescored(
        spread: np.ndarray,      # uint8 (H, W)
@@ -159,6 +271,122 @@ if HAS_NUMBA:
                        acc[y, x] = 0.0
        return acc

+    @nb.njit(cache=True, parallel=True, fastmath=True, boundscheck=False)
+    def _jit_top_max_per_variant(
+        spread: np.ndarray,            # uint8 (H, W)
+        dx_flat: np.ndarray,           # int32 (sum_N,)
+        dy_flat: np.ndarray,           # int32 (sum_N,)
+        bins_flat: np.ndarray,         # int8 (sum_N,)
+        offsets: np.ndarray,           # int32 (n_vars+1,) prefix sum
+        bit_active: np.uint8,
+        bg_per_variant: np.ndarray,    # float32 (n_vars, H, W) - 1 per scala
+        scale_idx: np.ndarray,         # int32 (n_vars,) idx in bg_per_variant
+    ) -> np.ndarray:
+        """Batch: per ogni variante calcola max score (rescored bg), ritorna
+        array float32 (n_vars,). Parallelismo prange ESTERNO sulle varianti
+        elimina overhead di n_vars chiamate JIT separate (avg ~20us per
+        chiamata su template piccoli) + pool thread Python.
+
+        Pensato per fase TOP del pruning quando n_vars >> n_threads.
+        """
+        n_vars = offsets.shape[0] - 1
+        H, W = spread.shape
+        out = np.zeros(n_vars, dtype=np.float32)
+        for vi in nb.prange(n_vars):
+            i0 = offsets[vi]; i1 = offsets[vi + 1]
+            N = i1 - i0
+            if N == 0:
+                out[vi] = -1.0
+                continue
+            si = scale_idx[vi]
+            inv = nb.float32(1.0 / N)
+            best = nb.float32(-1.0)
+            for y in range(H):
+                for x in range(W):
+                    s = nb.float32(0.0)
+                    for k in range(N):
+                        b = bins_flat[i0 + k]
+                        mask = np.uint8(1) << b
+                        if (bit_active & mask) == 0:
+                            continue
+                        ddy = dy_flat[i0 + k]
+                        yy = y + ddy
+                        if yy < 0 or yy >= H:
+                            continue
+                        ddx = dx_flat[i0 + k]
+                        xx = x + ddx
+                        if xx < 0 or xx >= W:
+                            continue
+                        if spread[yy, xx] & mask:
+                            s += nb.float32(1.0)
+                    s *= inv
+                    bgv = bg_per_variant[si, y, x]
+                    if bgv < 1.0:
+                        r = (s - bgv) / (1.0 - bgv + 1e-6)
+                        if r > best:
+                            best = r
+            out[vi] = best if best > 0.0 else 0.0
+        return out
+
+    @nb.njit(cache=True, parallel=True, fastmath=True, boundscheck=False)
+    def _jit_score_bitmap_rescored_u16(
+        spread: np.ndarray,      # uint16 (H, W) - 16 bit di polarity-aware
+        dx: np.ndarray, dy: np.ndarray, bins: np.ndarray,
+        bit_active: np.uint16,
+        bg: np.ndarray,
+    ) -> np.ndarray:
+        """Versione uint16 di _jit_score_bitmap_rescored per polarity 16-bin.
+
+        Identica logica ma mask = uint16(1) << b dove b in [0..15]
+        (orientamento mod 2π invece di mod π).
+        """
+        H, W = spread.shape
+        N = dx.shape[0]
+        acc = np.zeros((H, W), dtype=np.float32)
+        for y in nb.prange(H):
+            for i in range(N):
+                b = bins[i]
+                mask = np.uint16(1) << b
+                if (bit_active & mask) == 0:
+                    continue
+                ddy = dy[i]
+                yy = y + ddy
+                if yy < 0 or yy >= H:
+                    continue
+                ddx = dx[i]
+                x_lo = 0 if ddx >= 0 else -ddx
+                x_hi = W if ddx <= 0 else W - ddx
+                for x in range(x_lo, x_hi):
+                    if spread[yy, x + ddx] & mask:
+                        acc[y, x] += 1.0
+        if N > 0:
+            inv = 1.0 / N
+            for y in nb.prange(H):
+                for x in range(W):
+                    v = acc[y, x] * inv
+                    bgv = bg[y, x]
+                    if bgv < 1.0:
+                        r = (v - bgv) / (1.0 - bgv + 1e-6)
+                        acc[y, x] = r if r > 0.0 else 0.0
+                    else:
+                        acc[y, x] = 0.0
+        return acc
+
+    @nb.njit(cache=True, parallel=True, fastmath=True, boundscheck=False)
+    def _jit_popcount_density_u16(spread: np.ndarray) -> np.ndarray:
+        """Popcount per uint16 (16 bin polarity)."""
+        H, W = spread.shape
+        out = np.zeros((H, W), dtype=np.float32)
+        for y in nb.prange(H):
+            for x in range(W):
+                v = spread[y, x]
+                cnt = 0
+                for b in range(16):
+                    if v & (np.uint16(1) << b):
+                        cnt += 1
+                out[y, x] = float(cnt)
+        return out
+
    @nb.njit(cache=True, parallel=True, fastmath=True, boundscheck=False)
    def _jit_popcount_density(spread: np.ndarray) -> np.ndarray:
        """Conta bit set per pixel: ritorna (H, W) float32 in [0..8]."""
@@ -185,7 +413,25 @@ if HAS_NUMBA:
        _jit_score_bitmap(spread, dx, dy, b, np.uint8(0xFF))
        bg = np.zeros((32, 32), dtype=np.float32)
        _jit_score_bitmap_rescored(spread, dx, dy, b, np.uint8(0xFF), bg)
+        _jit_score_bitmap_rescored_strided(
+            spread, dx, dy, b, np.uint8(0xFF), bg, np.int32(2),
+        )
+        _jit_score_bitmap_greedy(
+            spread, dx, dy, b, np.uint8(0xFF),
+            np.float32(0.5), np.float32(0.8),
+        )
+        offsets = np.array([0, 1], dtype=np.int32)
+        scale_idx = np.zeros(1, dtype=np.int32)
+        bg_pv = np.zeros((1, 32, 32), dtype=np.float32)
+        _jit_top_max_per_variant(
+            spread, dx, dy, b, offsets, np.uint8(0xFF), bg_pv, scale_idx,
+        )
        _jit_popcount_density(spread)
+        spread16 = np.zeros((32, 32), dtype=np.uint16)
+        _jit_score_bitmap_rescored_u16(
+            spread16, dx, dy, b, np.uint16(0xFFFF), bg,
+        )
+        _jit_popcount_density_u16(spread16)

 else:  # pragma: no cover

@@ -198,6 +444,24 @@ else:  # pragma: no cover
    def _jit_score_bitmap_rescored(spread, dx, dy, bins, bit_active, bg):
        raise RuntimeError("numba non disponibile")

+    def _jit_score_bitmap_rescored_strided(spread, dx, dy, bins, bit_active, bg, stride):
+        raise RuntimeError("numba non disponibile")
+
+    def _jit_score_bitmap_greedy(spread, dx, dy, bins, bit_active, min_score, greediness):
+        raise RuntimeError("numba non disponibile")
+
+    def _jit_top_max_per_variant(
+        spread, dx_flat, dy_flat, bins_flat, offsets, bit_active,
+        bg_per_variant, scale_idx,
+    ):
+        raise RuntimeError("numba non disponibile")
+
+    def _jit_score_bitmap_rescored_u16(spread, dx, dy, bins, bit_active, bg):
+        raise RuntimeError("numba non disponibile")
+
+    def _jit_popcount_density_u16(spread):
+        raise RuntimeError("numba non disponibile")
+
    def _jit_popcount_density(spread):
        raise RuntimeError("numba non disponibile")

@@ -228,28 +492,132 @@ def score_bitmap(

 def score_bitmap_rescored(
    spread: np.ndarray, dx: np.ndarray, dy: np.ndarray, bins: np.ndarray,
-    bit_active: int, bg: np.ndarray,
+    bit_active: int, bg: np.ndarray, stride: int = 1,
 ) -> np.ndarray:
-    """Score bitmap + rescore fusi in un solo pass (JIT)."""
+    """Score bitmap + rescore fusi in un solo pass (JIT).
+
+    Dispatch per dtype: uint16 → kernel polarity 16-bin, uint8 → kernel
+    standard 8-bin (con eventuale stride > 1 per coarse top-level).
+    """
    if HAS_NUMBA and len(dx) > 0:
-        return _jit_score_bitmap_rescored(
-            np.ascontiguousarray(spread, dtype=np.uint8),
-            np.ascontiguousarray(dx, dtype=np.int32),
-            np.ascontiguousarray(dy, dtype=np.int32),
-            np.ascontiguousarray(bins, dtype=np.int8),
-            np.uint8(bit_active),
-            np.ascontiguousarray(bg, dtype=np.float32),
+        dx_c = np.ascontiguousarray(dx, dtype=np.int32)
+        dy_c = np.ascontiguousarray(dy, dtype=np.int32)
+        bins_c = np.ascontiguousarray(bins, dtype=np.int8)
+        bg_c = np.ascontiguousarray(bg, dtype=np.float32)
+        if spread.dtype == np.uint16:
+            spread_c = np.ascontiguousarray(spread, dtype=np.uint16)
+            return _jit_score_bitmap_rescored_u16(
+                spread_c, dx_c, dy_c, bins_c, np.uint16(bit_active), bg_c,
            )
-    # Fallback: chiamate separate
+        spread_c = np.ascontiguousarray(spread, dtype=np.uint8)
+        if stride > 1:
+            return _jit_score_bitmap_rescored_strided(
+                spread_c, dx_c, dy_c, bins_c, np.uint8(bit_active), bg_c,
+                np.int32(stride),
+            )
+        return _jit_score_bitmap_rescored(
+            spread_c, dx_c, dy_c, bins_c, np.uint8(bit_active), bg_c,
+        )
+    # Fallback: chiamate separate (stride ignorato in fallback)
    score = score_bitmap(spread, dx, dy, bins, bit_active)
    out = (score - bg) / (1.0 - bg + 1e-6)
    return np.maximum(0.0, out).astype(np.float32)


+def score_bitmap_greedy(
+    spread: np.ndarray, dx: np.ndarray, dy: np.ndarray, bins: np.ndarray,
+    bit_active: int, min_score: float, greediness: float,
+) -> np.ndarray:
+    """Score bitmap con early-exit greedy. Per coarse-pass aggressivo.
+
+    Non applica rescore background: usare quando la scena ha basso clutter
+    o quando si vuole mass-prune varianti via top-level rapidamente.
+    """
+    if HAS_NUMBA and len(dx) > 0:
+        return _jit_score_bitmap_greedy(
+            np.ascontiguousarray(spread, dtype=np.uint8),
+            np.ascontiguousarray(dx, dtype=np.int32),
+            np.ascontiguousarray(dy, dtype=np.int32),
+            np.ascontiguousarray(bins, dtype=np.int8),
+            np.uint8(bit_active),
+            np.float32(min_score), np.float32(greediness),
+        )
+    # Fallback: kernel base senza early-exit
+    return score_bitmap(spread, dx, dy, bins, bit_active)
+
+
+def top_max_per_variant(
+    spread: np.ndarray,
+    dx_list: list, dy_list: list, bin_list: list,
+    bg_per_scale: dict,
+    variant_scales: list,
+    bit_active: int,
+) -> np.ndarray:
+    """Wrapper: prepara buffer flat e chiama kernel batch su tutte le varianti.
+
+    Parallelismo Numba prange-esterno sulle varianti (n_vars >> n_threads
+    tipicamente per top-pruning) → meglio del thread-pool Python che paga
+    overhead di n_vars chiamate JIT separate.
+    """
+    if not HAS_NUMBA or len(dx_list) == 0:
+        return np.array([], dtype=np.float32)
+    n_vars = len(dx_list)
+    sizes = [len(d) for d in dx_list]
+    offsets = np.zeros(n_vars + 1, dtype=np.int32)
+    offsets[1:] = np.cumsum(sizes)
+    total = int(offsets[-1])
+    dx_flat = np.empty(total, dtype=np.int32)
+    dy_flat = np.empty(total, dtype=np.int32)
+    bins_flat = np.empty(total, dtype=np.int8)
+    for vi, (dx, dy, bn) in enumerate(zip(dx_list, dy_list, bin_list)):
+        i0 = int(offsets[vi]); i1 = int(offsets[vi + 1])
+        dx_flat[i0:i1] = dx
+        dy_flat[i0:i1] = dy
+        bins_flat[i0:i1] = bn
+    # bg per variante: indicizzato per scala
+    scales_unique = sorted(bg_per_scale.keys())
+    scale_to_idx = {s: i for i, s in enumerate(scales_unique)}
+    H, W = spread.shape
+    bg_pv = np.empty((len(scales_unique), H, W), dtype=np.float32)
+    for s, idx in scale_to_idx.items():
+        bg_pv[idx] = bg_per_scale[s]
+    scale_idx = np.array(
+        [scale_to_idx[s] for s in variant_scales], dtype=np.int32,
+    )
+    return _jit_top_max_per_variant(
+        np.ascontiguousarray(spread, dtype=np.uint8),
+        dx_flat, dy_flat, bins_flat, offsets, np.uint8(bit_active),
+        bg_pv, scale_idx,
+    )
+
+
+_HAS_NP_BITCOUNT = hasattr(np, "bitwise_count")
+
+
 def popcount_density(spread: np.ndarray) -> np.ndarray:
+    """Conta bit set per pixel.
+
+    Order:
+    1) Numba JIT parallel (preferito: piu veloce su 1080p, 0.5ms vs 1.6ms)
+    2) numpy.bitwise_count (NumPy 2.0+, SIMD ma single-thread)
+    3) Fallback numpy bit-shift puro
+    """
+    if spread.dtype == np.uint16:
+        spread_c = np.ascontiguousarray(spread, dtype=np.uint16)
        if HAS_NUMBA:
-        return _jit_popcount_density(np.ascontiguousarray(spread, dtype=np.uint8))
-    # Fallback
+            return _jit_popcount_density_u16(spread_c)
+        if _HAS_NP_BITCOUNT:
+            return np.bitwise_count(spread_c).astype(np.float32, copy=False)
+        H, W = spread_c.shape
+        out = np.zeros((H, W), dtype=np.float32)
+        for b in range(16):
+            out += ((spread_c >> b) & 1).astype(np.float32)
+        return out
+    spread_c = np.ascontiguousarray(spread, dtype=np.uint8)
+    if HAS_NUMBA:
+        return _jit_popcount_density(spread_c)
+    if _HAS_NP_BITCOUNT:
+        return np.bitwise_count(spread_c).astype(np.float32, copy=False)
    H, W = spread.shape
    out = np.zeros((H, W), dtype=np.float32)
    for b in range(8):
@@ -152,14 +152,124 @@ def _cache_key(template_bgr: np.ndarray, mask: np.ndarray | None) -> str:
    return h.hexdigest()


-def auto_tune(template_bgr: np.ndarray, mask: np.ndarray | None = None) -> dict:
+def _self_validate(template_bgr: np.ndarray, params: dict,
+                   mask: np.ndarray | None = None) -> dict:
+    """Halcon-style self-validation: train il matcher coi parametri tentativi
+    e verifica che il template stesso sia trovato con recall ≥ 1.0.
+
+    Se recall < target o score basso, regola i parametri:
+    - alza weak_grad se troppi edge spuri (recall solido ma molti picchi falsi)
+    - abbassa strong_grad se troppe feature scartate (low feature count)
+    - riduce pyramid_levels se variants[0].levels[top] ha <8 feature
+
+    Halcon usa internamente questo loop in inspect_shape_model. Costo: 1
+    train + 1 find sul template (~50ms su template 100x100). Ne vale la
+    pena se evita match-time errors su scene reali.
+
+    Mutates `params` in place e ritorna lo stesso dict per chaining.
+    """
+    # Import lazy: evita ciclo (line_matcher importa nulla da auto_tune)
+    from pm2d.line_matcher import LineShapeMatcher
+
+    # Caso degenerato: troppe poche feature pre-validation → riduci soglia
+    if params.get("_n_strong_pixels", 0) < 30:
+        params["weak_grad"] = max(15.0, params["weak_grad"] * 0.6)
+        params["strong_grad"] = max(30.0, params["strong_grad"] * 0.6)
+
+    # Train minimale: 1 sola pose orientazione 0 (range degenerato che
+    # produce comunque 1 variante via fallback in _angle_list).
+    m = LineShapeMatcher(
+        num_features=params["num_features"],
+        weak_grad=params["weak_grad"],
+        strong_grad=params["strong_grad"],
+        angle_range_deg=(0.0, 0.0),  # fallback _angle_list = [0.0]
+        angle_step_deg=10.0,
+        scale_range=(1.0, 1.0),
+        spread_radius=params["spread_radius"],
+        pyramid_levels=params["pyramid_levels"],
+    )
+    n_var = m.train(template_bgr, mask=mask)
+    if n_var == 0:
+        # Soglie troppo alte: nessuna variante generata → dimezza
+        params["weak_grad"] = max(15.0, params["weak_grad"] * 0.5)
+        params["strong_grad"] = max(30.0, params["strong_grad"] * 0.5)
+        params["_validation"] = "fallback: soglie dimezzate (no variants)"
+        return params
+
+    # Verifica densita' feature al top-level (rischio collasso)
+    top_lvl = m.variants[0].levels[-1]
+    if top_lvl.n < 8 and params["pyramid_levels"] > 1:
+        params["pyramid_levels"] = max(1, params["pyramid_levels"] - 1)
+        params["_validation"] = (
+            f"pyramid_levels ridotto a {params['pyramid_levels']} "
+            f"(top aveva {top_lvl.n} feature)"
+        )
+        return params
+
+    # Self-find: cerca il template stesso nella propria immagine
+    h, w = template_bgr.shape[:2]
+    # Embed template in scena leggermente più grande per evitare bordo
+    pad = 20
+    canvas = np.full(
+        (h + 2 * pad, w + 2 * pad, 3 if template_bgr.ndim == 3 else 1),
+        128, dtype=np.uint8,
+    )
+    canvas[pad:pad + h, pad:pad + w] = template_bgr
+    matches = m.find(
+        canvas, min_score=0.3, max_matches=5,
+        verify_ncc=False,  # template stesso → NCC = 1 sempre, skip per velocita'
+        refine_angle=False, subpixel=False,
+        nms_iou_threshold=0.3,
+    )
+    if not matches:
+        # Nessun match sul proprio template: parametri troppo restrittivi
+        params["weak_grad"] = max(15.0, params["weak_grad"] * 0.7)
+        params["strong_grad"] = max(30.0, params["strong_grad"] * 0.7)
+        params["num_features"] = max(48, int(params["num_features"] * 0.8))
+        params["_validation"] = "soglie/feature ridotte (no self-match)"
+        return params
+
+    # Misura score top match
+    top_score = float(matches[0].score)
+    params["_self_score"] = round(top_score, 3)
+    if top_score < 0.7:
+        # Score basso sul template stesso = parametri davvero subottimali
+        params["weak_grad"] = max(15.0, params["weak_grad"] * 0.85)
+        params["_validation"] = (
+            f"weak_grad ridotto (self-score era {top_score:.2f})"
+        )
+    else:
+        params["_validation"] = f"OK (self-score {top_score:.2f})"
+    return params
+
+
+def auto_tune(
+    template_bgr: np.ndarray,
+    mask: np.ndarray | None = None,
+    angle_tolerance_deg: float | None = None,
+    angle_center_deg: float = 0.0,
+    self_validate: bool = True,
+) -> dict:
    """Analizza template e ritorna dict parametri suggeriti.

    Chiavi compatibili con edit_params PARAM_SCHEMA.

+    angle_tolerance_deg: se != None, restringe angle_range a
+    (center - tol, center + tol). Usare quando l'orientamento del
+    pezzo e' noto a priori (feeder con guida, posizionamento
+    meccanico): training molto piu rapido (24x meno varianti per
+    tol=15° vs 360° pieno).
+
+    self_validate: se True (default), dopo la stima dei parametri
+    esegue un dry-run del matching sul template stesso e regola
+    weak_grad/strong_grad/pyramid_levels se i parametri tentativi
+    non garantiscono auto-match (Halcon-style inspect_shape_model).
+
    Risultato cachato in-memory (LRU): ri-chiamare con stessa ROI è O(1).
    """
    ck = _cache_key(template_bgr, mask)
+    if angle_tolerance_deg is not None:
+        ck = f"{ck}|tol={angle_tolerance_deg}|c={angle_center_deg}"
    cached = _TUNE_CACHE.get(ck)
    if cached is not None:
        _TUNE_CACHE.move_to_end(ck)
@@ -208,7 +318,12 @@ def auto_tune(template_bgr: np.ndarray, mask: np.ndarray | None = None) -> dict:
    # spread_radius proporzionale a risoluzione + pyramid (tolleranza ~1% dim)
    spread_radius = int(np.clip(max(3, min_side * 0.02), 3, 8))

-    # angle range ridotto se simmetria rotazionale
+    # angle range: priorita' a tolerance hint utente, poi simmetria rotazionale.
+    if angle_tolerance_deg is not None:
+        angle_min = float(angle_center_deg - angle_tolerance_deg)
+        angle_max = float(angle_center_deg + angle_tolerance_deg)
+    else:
+        angle_min = 0.0
        angle_max = 360.0 / sym["order"] if sym["order"] > 1 else 360.0

    # min_score: se entropia orient alta → template distintivo → soglia alta ok
@@ -220,12 +335,15 @@ def auto_tune(template_bgr: np.ndarray, mask: np.ndarray | None = None) -> dict:
    else:
        min_score = 0.45

-    # angle step: 5° default; se simmetria, mantengo step ma range ridotto
-    angle_step = 5.0
+    # angle step adattivo (Halcon-style): atan(2/max_side) deg, clampato.
+    # Template grande → step fine (rotazione minima visibile su perimetro).
+    # Template piccolo → step grosso (over-sampling = sprecato).
+    max_side = max(h, w)
+    angle_step = float(np.clip(np.degrees(np.arctan2(2.0, max_side)), 1.0, 8.0))

    result = {
        "backend": "line",
-        "angle_min": 0.0,
+        "angle_min": angle_min,
        "angle_max": angle_max,
        "angle_step": angle_step,
        "scale_min": 1.0,
@@ -244,7 +362,15 @@ def auto_tune(template_bgr: np.ndarray, mask: np.ndarray | None = None) -> dict:
        "_symmetry_order": sym["order"],
        "_symmetry_conf": round(sym["confidence"], 2),
        "_orient_entropy": round(stats["orient_entropy"], 2),
+        "_n_strong_pixels": stats["n_strong"],
    }
+    # Halcon-style self-validation: dry-run training+find sul template per
+    # auto-correggere parametri tentativi che non garantirebbero match.
+    if self_validate:
+        result = _self_validate(template_bgr, result, mask=mask)
+        # Round numerici dopo eventuali aggiustamenti
+        result["weak_grad"] = round(result["weak_grad"], 1)
+        result["strong_grad"] = round(result["strong_grad"], 1)
    # Store in LRU cache
    _TUNE_CACHE[ck] = dict(result)
    _TUNE_CACHE.move_to_end(ck)
@@ -0,0 +1,217 @@
+"""CLI validation harness per LineShapeMatcher.
+
+Usage:
+    python -m pm2d.eval dataset.json [opzioni]
+
+Formato dataset (JSON):
+    {
+      "template": "path/to/template.png",
+      "mask": "path/to/mask.png",  # opzionale
+      "params": {                   # opzionali, override su matcher init
+        "use_polarity": true,
+        "angle_step_deg": 5,
+        ...
+      },
+      "find_params": {              # opzionali, passati a find()
+        "min_score": 0.6,
+        "use_soft_score": true,
+        ...
+      },
+      "scenes": [
+        {
+          "image": "path/to/scene1.png",
+          "ground_truth": [
+            {"cx": 320.0, "cy": 240.0, "angle_deg": 12.0,
+             "scale": 1.0, "tolerance_px": 5.0,
+             "tolerance_deg": 3.0}
+          ]
+        }
+      ]
+    }
+
+Output: report precision/recall/IoU/timing per ogni scena + aggregati.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import sys
+import time
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+from pm2d.line_matcher import LineShapeMatcher, _poly_iou, _oriented_bbox_polygon
+
+
+def _load_image(path: str | Path) -> np.ndarray:
+    img = cv2.imread(str(path), cv2.IMREAD_UNCHANGED)
+    if img is None:
+        raise FileNotFoundError(f"Immagine non trovata: {path}")
+    if img.ndim == 2:
+        img = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
+    return img
+
+
+def _gt_to_poly(gt: dict, tw: int, th: int) -> np.ndarray:
+    """Costruisce bbox poligonale per un ground truth."""
+    s = float(gt.get("scale", 1.0))
+    return _oriented_bbox_polygon(
+        float(gt["cx"]), float(gt["cy"]),
+        tw * s, th * s, float(gt["angle_deg"]),
+    )
+
+
+def _match_to_gt(match, gt: dict, tw: int, th: int,
+                 iou_thr: float = 0.3) -> bool:
+    """True se il match corrisponde al ground truth.
+
+    Criterio: distanza centro <= tolerance_px AND |angle_deg - gt| <= tolerance_deg
+    OR IoU bbox >= iou_thr (fallback per pose con tolerance ampie).
+    """
+    tol_px = float(gt.get("tolerance_px", 5.0))
+    tol_deg = float(gt.get("tolerance_deg", 3.0))
+    dx = match.cx - float(gt["cx"])
+    dy = match.cy - float(gt["cy"])
+    dist = math.hypot(dx, dy)
+    da = abs((match.angle_deg - float(gt["angle_deg"]) + 180) % 360 - 180)
+    if dist <= tol_px and da <= tol_deg:
+        return True
+    # Fallback IoU
+    poly_gt = _gt_to_poly(gt, tw, th)
+    poly_m = match.bbox_poly
+    if _poly_iou(poly_m, poly_gt) >= iou_thr:
+        return True
+    return False
+
+
+def evaluate_scene(matcher: LineShapeMatcher, scene_bgr: np.ndarray,
+                   gt_list: list[dict], find_params: dict,
+                   tw: int, th: int) -> dict:
+    """Esegue match e calcola TP/FP/FN per una scena."""
+    t0 = time.time()
+    matches = matcher.find(scene_bgr, **find_params)
+    elapsed = time.time() - t0
+
+    gt_matched = [False] * len(gt_list)
+    match_is_tp = [False] * len(matches)
+    iou_per_match = [0.0] * len(matches)
+    for i, m in enumerate(matches):
+        for j, gt in enumerate(gt_list):
+            if gt_matched[j]:
+                continue
+            if _match_to_gt(m, gt, tw, th):
+                gt_matched[j] = True
+                match_is_tp[i] = True
+                # Calcolo IoU per metrica
+                poly_gt = _gt_to_poly(gt, tw, th)
+                iou_per_match[i] = _poly_iou(m.bbox_poly, poly_gt)
+                break
+    tp = sum(match_is_tp)
+    fp = len(matches) - tp
+    fn = len(gt_list) - sum(gt_matched)
+    return {
+        "n_matches": len(matches),
+        "n_gt": len(gt_list),
+        "tp": tp, "fp": fp, "fn": fn,
+        "find_time_s": elapsed,
+        "iou_mean": float(np.mean([i for i, t in zip(iou_per_match, match_is_tp) if t])
+                          if tp > 0 else 0.0),
+        "diag": (matcher.get_last_diag()
+                 if hasattr(matcher, "get_last_diag") else None),
+    }
+
+
+def run(dataset_path: str, scene_filter: str | None = None,
+        verbose: bool = False) -> dict:
+    """Esegue eval su dataset, ritorna report aggregato."""
+    dataset_path = Path(dataset_path)
+    base = dataset_path.parent
+    with open(dataset_path) as f:
+        ds = json.load(f)
+
+    template = _load_image(base / ds["template"])
+    mask = None
+    if ds.get("mask"):
+        mask_img = cv2.imread(str(base / ds["mask"]), cv2.IMREAD_GRAYSCALE)
+        if mask_img is not None:
+            mask = (mask_img > 128).astype(np.uint8) * 255
+    init_params = ds.get("params", {})
+    find_params = ds.get("find_params", {})
+
+    matcher = LineShapeMatcher(**init_params)
+    n_var = matcher.train(template, mask=mask)
+    tw, th = matcher.template_size
+    print(f"Template: {ds['template']} ({tw}x{th}), {n_var} varianti")
+    print(f"Param matcher: {init_params}")
+    print(f"Param find:    {find_params}")
+    print()
+
+    scenes = ds["scenes"]
+    if scene_filter:
+        scenes = [s for s in scenes if scene_filter in s["image"]]
+
+    rows = []
+    tot_tp = tot_fp = tot_fn = 0
+    tot_time = 0.0
+    for sc in scenes:
+        scene = _load_image(base / sc["image"])
+        gt = sc.get("ground_truth", [])
+        result = evaluate_scene(matcher, scene, gt, find_params, tw, th)
+        rows.append({"scene": sc["image"], **result})
+        tot_tp += result["tp"]; tot_fp += result["fp"]; tot_fn += result["fn"]
+        tot_time += result["find_time_s"]
+        prec = result["tp"] / max(1, result["tp"] + result["fp"])
+        rec = result["tp"] / max(1, result["tp"] + result["fn"])
+        line = (f"  {sc['image']:30s}  "
+                f"TP={result['tp']} FP={result['fp']} FN={result['fn']}  "
+                f"P={prec:.2f} R={rec:.2f}  "
+                f"IoU={result['iou_mean']:.2f}  "
+                f"t={result['find_time_s']*1000:.0f}ms")
+        print(line)
+        if verbose and result["diag"] and hasattr(matcher, "_format_diag"):
+            print(f"     diag: {matcher._format_diag(result['diag'])}")
+
+    # Aggregati
+    precision = tot_tp / max(1, tot_tp + tot_fp)
+    recall = tot_tp / max(1, tot_tp + tot_fn)
+    f1 = 2 * precision * recall / max(1e-9, precision + recall)
+    print()
+    print(f"AGGREGATO: precision={precision:.3f} recall={recall:.3f} "
+          f"F1={f1:.3f}  TP={tot_tp} FP={tot_fp} FN={tot_fn}")
+    print(f"TIME: total={tot_time:.2f}s avg={tot_time / max(1, len(scenes)) * 1000:.0f}ms/scene")
+
+    return {
+        "precision": precision, "recall": recall, "f1": f1,
+        "tp": tot_tp, "fp": tot_fp, "fn": tot_fn,
+        "total_time_s": tot_time, "n_scenes": len(scenes),
+        "per_scene": rows,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        description="pm2d-eval: validation harness per LineShapeMatcher"
+    )
+    p.add_argument("dataset", help="JSON dataset (template + scenes + GT)")
+    p.add_argument("--scene-filter", default=None,
+                   help="Filtro substring sui nomi scena (debug)")
+    p.add_argument("--verbose", "-v", action="store_true",
+                   help="Stampa diag dict per ogni scena")
+    p.add_argument("--out", default=None,
+                   help="Salva report JSON su file")
+    args = p.parse_args(argv)
+    report = run(args.dataset, scene_filter=args.scene_filter,
+                 verbose=args.verbose)
+    if args.out:
+        with open(args.out, "w") as f:
+            json.dump(report, f, indent=2)
+        print(f"Report salvato: {args.out}")
+    return 0 if report["f1"] > 0.5 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -48,6 +48,10 @@ IMAGES_DIR = Path(_images_dir_raw)
 if not IMAGES_DIR.is_absolute():
    IMAGES_DIR = PROJECT_ROOT / IMAGES_DIR

+# Cartella ricette pre-trained (V feature: save/load matcher)
+RECIPES_DIR = PROJECT_ROOT / "recipes"
+RECIPES_DIR.mkdir(exist_ok=True)
+
 from pm2d.line_matcher import LineShapeMatcher, Match
 from pm2d.auto_tune import auto_tune

@@ -249,9 +253,9 @@ PRECISION_ANGLE_STEP = {
 # Un operatore sceglie il livello di rigore, non un numero astratto.
 FILTRO_FP_MAP = {
    "off":      0.0,   # disabilitato: mantieni tutti i match shape-based
-    "leggero":  0.20,  # tollera variazioni intensità/illuminazione forti
-    "medio":    0.35,  # default bilanciato (consigliato)
-    "forte":    0.50,  # scarta match con intensità molto diversa dal template
+    "leggero":  0.30,  # tollera variazioni intensità/illuminazione forti
+    "medio":    0.50,  # default bilanciato (consigliato)
+    "forte":    0.70,  # scarta match con intensità molto diversa dal template
 }


@@ -267,6 +271,20 @@ class SimpleMatchParams(BaseModel):
    penalita_scala: float = 0.0       # 0 = score shape invariante, >0 = penalizza scala != 1
    min_score: float = 0.65
    max_matches: int = 25
+    # --- Halcon-mode flags (default off = backward compat) ---
+    # Init-time (richiede ri-train se cambiato)
+    use_polarity: bool = False        # F: 16 bin orientation mod 2pi
+    use_gpu: bool = False             # R: OpenCL UMat (silent fallback)
+    # Find-time (no retrain)
+    min_recall: float = 0.0           # M: filtra match con poche feature combaciate
+    use_soft_score: bool = False      # Y: cosine sim continua dei gradients
+    subpixel_lm: bool = False         # Z: precisione 0.05 px
+    nms_iou_threshold: float = 0.3    # A: IoU bbox poligonale
+    coarse_stride: int = 1            # sub-sampling top-level (>=1)
+    pyramid_propagate: bool = False   # propagazione candidati top->full
+    greediness: float = 0.0           # early-exit kernel (0..1)
+    refine_pose_joint: bool = False   # Nelder-Mead 3D (cx, cy, angle)
+    search_roi: list[int] | None = None  # [x, y, w, h] limita area


 def _simple_to_technical(
@@ -526,6 +544,9 @@ def match_simple(p: SimpleMatchParams):
    tech = _simple_to_technical(p, roi_img)

    key = _matcher_cache_key(roi_img, tech)
+    # Halcon-mode init params: incidono sul training, includere in cache key
+    halcon_init_key = f"|pol={p.use_polarity}|gpu={p.use_gpu}"
+    key = key + halcon_init_key
    m = _cache_get_matcher(key)
    if m is None:
        m = LineShapeMatcher(
@@ -537,17 +558,30 @@ def match_simple(p: SimpleMatchParams):
            scale_step=tech["scale_step"],
            spread_radius=tech["spread_radius"],
            pyramid_levels=tech["pyramid_levels"],
+            use_polarity=p.use_polarity,
+            use_gpu=p.use_gpu,
        )
        t0 = time.time(); n = m.train(roi_img); t_train = time.time() - t0
        _cache_put_matcher(key, m)
    else:
        n = len(m.variants); t_train = 0.0
    nms = tech["nms_radius"] if tech["nms_radius"] > 0 else None
+    search_roi_t = tuple(p.search_roi) if p.search_roi else None
    t0 = time.time()
    matches = m.find(
        scene, min_score=tech["min_score"], max_matches=tech["max_matches"],
        nms_radius=nms, verify_threshold=tech["verify_threshold"],
        scale_penalty=tech.get("scale_penalty", 0.0),
+        # Halcon-mode flags
+        min_recall=p.min_recall,
+        use_soft_score=p.use_soft_score,
+        subpixel_lm=p.subpixel_lm,
+        nms_iou_threshold=p.nms_iou_threshold,
+        coarse_stride=p.coarse_stride,
+        pyramid_propagate=p.pyramid_propagate,
+        greediness=p.greediness,
+        refine_pose_joint=p.refine_pose_joint,
+        search_roi=search_roi_t,
    )
    t_find = time.time() - t0

@@ -573,7 +607,169 @@ def tune(p: TuneParams):
    x, y, w, h = p.roi
    roi_img = model[y:y + h, x:x + w]
    t = auto_tune(roi_img)
-    return {k: v for k, v in t.items() if not k.startswith("_")}
+    # Esponi parametri tecnici + meta diagnostica (_self_score, _validation,
+    # _symmetry_order, _orient_entropy) per feedback UI.
+    return t
+
+
+# --- V: Save/Load ricette pre-trained ---
+
+class SaveRecipeParams(BaseModel):
+    model_id: str
+    scene_id: str | None = None
+    roi: list[int]
+    # Riusa stessi param simple per training equivalente
+    tipo: str = "intero"
+    simmetria: str = "nessuna"
+    scala: str = "fissa"
+    precisione: str = "normale"
+    use_polarity: bool = False
+    use_gpu: bool = False
+    name: str  # nome file ricetta (no path)
+
+
+@app.post("/recipes")
+def save_recipe(p: SaveRecipeParams):
+    """Allena matcher e salva su disco come ricetta riutilizzabile."""
+    model = _load_image(p.model_id)
+    if model is None:
+        raise HTTPException(404, "Modello non trovato")
+    x, y, w, h = p.roi
+    roi_img = model[y:y + h, x:x + w]
+    sp = SimpleMatchParams(
+        model_id=p.model_id, scene_id=p.scene_id or p.model_id, roi=p.roi,
+        tipo=p.tipo, simmetria=p.simmetria, scala=p.scala,
+        precisione=p.precisione,
+        use_polarity=p.use_polarity, use_gpu=p.use_gpu,
+    )
+    tech = _simple_to_technical(sp, roi_img)
+    m = LineShapeMatcher(
+        num_features=tech["num_features"],
+        weak_grad=tech["weak_grad"], strong_grad=tech["strong_grad"],
+        angle_range_deg=(tech["angle_min"], tech["angle_max"]),
+        angle_step_deg=tech["angle_step"],
+        scale_range=(tech["scale_min"], tech["scale_max"]),
+        scale_step=tech["scale_step"],
+        spread_radius=tech["spread_radius"],
+        pyramid_levels=tech["pyramid_levels"],
+        use_polarity=p.use_polarity,
+        use_gpu=p.use_gpu,
+    )
+    m.train(roi_img)
+    safe_name = "".join(c for c in p.name if c.isalnum() or c in "._-")
+    if not safe_name:
+        raise HTTPException(400, "Nome ricetta non valido")
+    if not safe_name.endswith(".npz"):
+        safe_name += ".npz"
+    target = RECIPES_DIR / safe_name
+    m.save_model(str(target))
+    return {"name": safe_name, "size": target.stat().st_size,
+            "n_variants": len(m.variants)}
+
+
+@app.get("/recipes")
+def list_recipes():
+    files = []
+    if RECIPES_DIR.is_dir():
+        for f in sorted(RECIPES_DIR.glob("*.npz")):
+            files.append({"name": f.name, "size": f.stat().st_size})
+    return {"files": files, "dir": str(RECIPES_DIR)}
+
+
+# Cache di matcher caricati da .npz (V feature). Key: nome ricetta.
+_RECIPE_MATCHERS: OrderedDict = OrderedDict()
+_RECIPE_MATCHERS_SIZE = 4
+
+
+@app.post("/recipes/{name}/load")
+def load_recipe(name: str):
+    """Carica ricetta .npz e popola cache matcher in memoria.
+
+    Una volta caricata, /match_recipe la usa direttamente senza
+    re-train. Halcon-equivalent read_shape_model + handle.
+    """
+    safe_name = "".join(c for c in name if c.isalnum() or c in "._-")
+    if not safe_name.endswith(".npz"):
+        safe_name += ".npz"
+    path = RECIPES_DIR / safe_name
+    if not path.is_file():
+        raise HTTPException(404, f"Ricetta non trovata: {safe_name}")
+    m = LineShapeMatcher.load_model(str(path))
+    _RECIPE_MATCHERS[safe_name] = m
+    _RECIPE_MATCHERS.move_to_end(safe_name)
+    while len(_RECIPE_MATCHERS) > _RECIPE_MATCHERS_SIZE:
+        _RECIPE_MATCHERS.popitem(last=False)
+    return {
+        "name": safe_name,
+        "n_variants": len(m.variants),
+        "template_size": list(m.template_size),
+        "use_polarity": m.use_polarity,
+    }
+
+
+class RecipeMatchParams(BaseModel):
+    recipe: str
+    scene_id: str
+    # Solo find-time params (training gia' fatto offline)
+    min_score: float = 0.65
+    max_matches: int = 25
+    min_recall: float = 0.0
+    use_soft_score: bool = False
+    subpixel_lm: bool = False
+    nms_iou_threshold: float = 0.3
+    coarse_stride: int = 1
+    pyramid_propagate: bool = False
+    greediness: float = 0.0
+    refine_pose_joint: bool = False
+    search_roi: list[int] | None = None
+    verify_threshold: float = 0.5
+    scale_penalty: float = 0.0
+
+
+@app.post("/match_recipe", response_model=MatchResp)
+def match_recipe(p: RecipeMatchParams):
+    """Match con ricetta pre-trained: zero training, solo find."""
+    safe_name = p.recipe if p.recipe.endswith(".npz") else f"{p.recipe}.npz"
+    m = _RECIPE_MATCHERS.get(safe_name)
+    if m is None:
+        # Auto-load on demand
+        path = RECIPES_DIR / safe_name
+        if not path.is_file():
+            raise HTTPException(404, f"Ricetta non trovata: {safe_name}")
+        m = LineShapeMatcher.load_model(str(path))
+        _RECIPE_MATCHERS[safe_name] = m
+    scene = _load_image(p.scene_id)
+    if scene is None:
+        raise HTTPException(404, "Scena non trovata")
+    search_roi_t = tuple(p.search_roi) if p.search_roi else None
+    t0 = time.time()
+    matches = m.find(
+        scene,
+        min_score=p.min_score, max_matches=p.max_matches,
+        verify_threshold=p.verify_threshold,
+        scale_penalty=p.scale_penalty,
+        min_recall=p.min_recall,
+        use_soft_score=p.use_soft_score,
+        subpixel_lm=p.subpixel_lm,
+        nms_iou_threshold=p.nms_iou_threshold,
+        coarse_stride=p.coarse_stride,
+        pyramid_propagate=p.pyramid_propagate,
+        greediness=p.greediness,
+        refine_pose_joint=p.refine_pose_joint,
+        search_roi=search_roi_t,
+    )
+    t_find = time.time() - t0
+    tg = m.template_gray if m.template_gray is not None else np.zeros((1, 1), np.uint8)
+    annotated = _draw_matches(scene, matches, tg)
+    ann_id = _store_image(annotated)
+    return MatchResp(
+        matches=[MatchResult(
+            cx=mt.cx, cy=mt.cy, angle_deg=mt.angle_deg, scale=mt.scale,
+            score=mt.score, bbox_poly=mt.bbox_poly.tolist(),
+        ) for mt in matches],
+        train_time=0.0, find_time=t_find,
+        num_variants=len(m.variants), annotated_id=ann_id,
+    )


 # Mount static
@@ -19,6 +19,7 @@ const PALETTE = [
 const state = {
  model: null, scene: null, roi: null, drag: null,
  matches: [], annotatedImg: null,
+  active_recipe: null,  // V: ricetta caricata (string nome) o null
 };

 // ---------- Forms ----------
@@ -52,6 +53,39 @@ function readUserParams() {
      document.getElementById("p-penalita-scala").value),
    min_score: parseFloat(document.getElementById("p-min-score").value),
    max_matches: parseInt(document.getElementById("p-max-matches").value, 10),
+    ...readHalconFlags(),
+  };
+}
+
+function readHalconFlags() {
+  // Halcon-mode toggle: tutti i flag default-off, esposti via "Modalità Halcon"
+  const $cb = (id) => document.getElementById(id)?.checked ?? false;
+  const $num = (id, def) => {
+    const v = parseFloat(document.getElementById(id)?.value);
+    return Number.isFinite(v) ? v : def;
+  };
+  const $int = (id, def) => {
+    const v = parseInt(document.getElementById(id)?.value, 10);
+    return Number.isFinite(v) ? v : def;
+  };
+  const roiStr = document.getElementById("hc-search-roi")?.value.trim() ?? "";
+  let search_roi = null;
+  if (roiStr) {
+    const p = roiStr.split(/[ ,;]+/).map((x) => parseInt(x, 10));
+    if (p.length === 4 && p.every((v) => Number.isFinite(v))) search_roi = p;
+  }
+  return {
+    use_polarity: $cb("hc-use-polarity"),
+    use_gpu: $cb("hc-use-gpu"),
+    use_soft_score: $cb("hc-soft-score"),
+    subpixel_lm: $cb("hc-subpixel-lm"),
+    refine_pose_joint: $cb("hc-refine-joint"),
+    pyramid_propagate: $cb("hc-pyr-propagate"),
+    min_recall: $num("hc-min-recall", 0),
+    nms_iou_threshold: $num("hc-nms-iou", 0.3),
+    greediness: $num("hc-greediness", 0),
+    coarse_stride: $int("hc-coarse-stride", 1),
+    search_roi: search_roi,
  };
 }

@@ -274,7 +308,42 @@ function setupROI() {
 }

 // ---------- Match action ----------
+async function doMatchRecipe() {
+  if (!state.scene) { setStatus("Carica scena"); return; }
+  setStatus(`Match ricetta ${state.active_recipe}...`);
+  const hc = readHalconFlags();
+  const body = {
+    recipe: state.active_recipe,
+    scene_id: state.scene.id,
+    min_score: parseFloat(document.getElementById("p-min-score").value),
+    max_matches: parseInt(document.getElementById("p-max-matches").value, 10),
+    verify_threshold: 0.50,
+    ...hc,
+  };
+  const r = await fetch("/match_recipe", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!r.ok) { setStatus(`Errore: ${await r.text()}`); return; }
+  const data = await r.json();
+  state.matches = data.matches;
+  state.annotatedImg = await loadImage(
+    `/image/${data.annotated_id}/raw?t=${Date.now()}`);
+  renderScene();
+  renderLegend();
+  document.getElementById("t-train").textContent = "—";
+  document.getElementById("t-find").textContent = `${data.find_time.toFixed(2)}s`;
+  document.getElementById("t-var").textContent = data.num_variants;
+  document.getElementById("t-match").textContent = data.matches.length;
+  setStatus(`${data.matches.length} match trovati (ricetta ${state.active_recipe})`);
+}
+
 async function doMatch() {
+  // Path V: ricetta caricata → bypass training, solo find su scena
+  if (state.active_recipe) {
+    return doMatchRecipe();
+  }
  if (!state.model) { setStatus("Carica modello"); return; }
  if (!state.scene) { setStatus("Carica scena"); return; }
  if (!state.roi) { setStatus("Seleziona ROI sul modello"); return; }
@@ -294,12 +363,17 @@ async function doMatch() {
    const SCALE_MAP = {fissa:[1,1,0.1], mini:[0.9,1.1,0.05],
                       medio:[0.75,1.25,0.05], max:[0.5,1.5,0.05]};
    const PREC_MAP = {veloce:10, normale:5, preciso:2};
-    const FP_MAP = {off:0, leggero:0.20, medio:0.35, forte:0.50};
+    // Allineato a FILTRO_FP_MAP server-side (server.py)
+    const FP_MAP = {off:0, leggero:0.30, medio:0.50, forte:0.70};
    const [smin, smax, sstep] = SCALE_MAP[user.scala];
+    // NB: SYM_MAP[invariante]=0 e' valido (zero rotazioni). Uso ?? per
+    // distinguere "chiave mancante" da "valore zero": altrimenti 0 || 360
+    // collassa invariante a 360 = bug "simmetria non ha effetto".
+    const angMax = SYM_MAP[user.simmetria] ?? 360;
    body = {
      model_id: state.model.id, scene_id: state.scene.id, roi: state.roi,
-      angle_min: 0, angle_max: SYM_MAP[user.simmetria] || 360,
-      angle_step: PREC_MAP[user.precisione] || 5,
+      angle_min: 0, angle_max: angMax,
+      angle_step: PREC_MAP[user.precisione] ?? 5,
      scale_min: smin, scale_max: smax, scale_step: sstep,
      min_score: user.min_score, max_matches: user.max_matches,
      num_features: adv.num_features ?? 96,
@@ -307,7 +381,7 @@ async function doMatch() {
      strong_grad: adv.strong_grad ?? 60,
      spread_radius: adv.spread_radius ?? 5,
      pyramid_levels: adv.pyramid_levels ?? 3,
-      verify_threshold: adv.verify_threshold ?? (FP_MAP[user.filtro_fp] ?? 0.35),
+      verify_threshold: adv.verify_threshold ?? (FP_MAP[user.filtro_fp] ?? 0.50),
      nms_radius: adv.nms_radius ?? 0,
    };
  } else {
@@ -362,6 +436,143 @@ function setStatus(s) {
 }

 // ---------- Init ----------
+// ---------- Auto-tune (Halcon-style) ----------
+async function doAutoTune() {
+  if (!state.model || !state.roi) {
+    alert("Seleziona modello e disegna ROI prima di Auto-tune.");
+    return;
+  }
+  const status = document.getElementById("status");
+  status.textContent = "Analisi ROI in corso...";
+  try {
+    const r = await fetch("/auto_tune", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model_id: state.model.id,
+        roi: state.roi,
+      }),
+    });
+    if (!r.ok) throw new Error(await r.text());
+    const t = await r.json();
+    // Applica ai campi avanzati (override automatico)
+    for (const [key] of ADV_PARAMS) {
+      const el = document.getElementById(`adv-${key}`);
+      if (el && t[key] !== undefined) el.value = String(t[key]);
+    }
+    // Espandi la sezione Avanzate per mostrare i valori applicati
+    const advDetails = document.querySelector("#col-params details:last-of-type");
+    if (advDetails) advDetails.open = true;
+    // Feedback diagnostico
+    const lines = [
+      `weak/strong: ${t.weak_grad} / ${t.strong_grad}`,
+      `feature: ${t.num_features}, piramide: ${t.pyramid_levels}`,
+      `angle: [${t.angle_min}..${t.angle_max}]@${t.angle_step}°`,
+    ];
+    if (t._symmetry_order > 1) {
+      lines.push(`simmetria rotaz. ${t._symmetry_order}x (conf ${t._symmetry_conf})`);
+    }
+    if (t._self_score !== undefined) {
+      lines.push(`self-validation: ${t._validation}`);
+    }
+    status.textContent = `Auto-tune OK — ${lines[0]}`;
+    alert("Auto-tune completato:\n\n" + lines.join("\n"));
+  } catch (e) {
+    status.textContent = `Auto-tune errore: ${e.message}`;
+    alert(`Errore auto-tune: ${e.message}`);
+  }
+}
+
+// ---------- V: Recipe load/list/unload ----------
+async function refreshRecipeList() {
+  try {
+    const r = await fetch("/recipes");
+    if (!r.ok) return;
+    const j = await r.json();
+    const sel = document.getElementById("hc-recipe-list");
+    const cur = sel.value;
+    sel.innerHTML = '<option value="">— ricette disponibili —</option>';
+    for (const f of j.files) {
+      const o = document.createElement("option");
+      o.value = f.name;
+      o.textContent = `${f.name}  (${(f.size / 1024).toFixed(1)} KB)`;
+      sel.appendChild(o);
+    }
+    if (cur) sel.value = cur;
+  } catch (e) { /* silent */ }
+}
+
+async function loadRecipe() {
+  const sel = document.getElementById("hc-recipe-list");
+  const name = sel.value;
+  if (!name) {
+    alert("Seleziona una ricetta dalla lista.");
+    return;
+  }
+  try {
+    const r = await fetch(`/recipes/${encodeURIComponent(name)}/load`, {
+      method: "POST",
+    });
+    if (!r.ok) throw new Error(await r.text());
+    const j = await r.json();
+    state.active_recipe = j.name;
+    document.getElementById("recipe-status").textContent =
+      `Caricata: ${j.name} — ${j.n_variants} varianti, ` +
+      `${j.template_size[0]}x${j.template_size[1]} px` +
+      (j.use_polarity ? " (polarity)" : "");
+    document.getElementById("recipe-status").style.color = "#0c0";
+    document.getElementById("btn-unload-recipe").disabled = false;
+  } catch (e) {
+    alert(`Errore caricamento: ${e.message}`);
+  }
+}
+
+function unloadRecipe() {
+  state.active_recipe = null;
+  document.getElementById("recipe-status").textContent = "Nessuna ricetta caricata";
+  document.getElementById("recipe-status").style.color = "#888";
+  document.getElementById("btn-unload-recipe").disabled = true;
+}
+
+// ---------- V: Save recipe ----------
+async function saveRecipe() {
+  if (!state.model || !state.roi) {
+    alert("Seleziona modello e disegna ROI prima di salvare la ricetta.");
+    return;
+  }
+  const name = document.getElementById("hc-recipe-name").value.trim();
+  if (!name) {
+    alert("Inserisci un nome per la ricetta.");
+    return;
+  }
+  const user = readUserParams();
+  const body = {
+    model_id: state.model.id,
+    scene_id: state.scene?.id || state.model.id,
+    roi: state.roi,
+    tipo: user.tipo,
+    simmetria: user.simmetria,
+    scala: user.scala,
+    precisione: user.precisione,
+    use_polarity: user.use_polarity,
+    use_gpu: user.use_gpu,
+    name: name,
+  };
+  try {
+    const r = await fetch("/recipes", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!r.ok) throw new Error(await r.text());
+    const j = await r.json();
+    alert(`Ricetta salvata: ${j.name}\n${j.n_variants} varianti, ${j.size} bytes`);
+    refreshRecipeList();
+  } catch (e) {
+    alert(`Errore salvataggio: ${e.message}`);
+  }
+}
+
 window.addEventListener("DOMContentLoaded", async () => {
  buildAdvancedForm();
  setupROI();
@@ -389,6 +600,14 @@ window.addEventListener("DOMContentLoaded", async () => {
    e.target.value = "";  // consente re-upload stesso file
  });
  document.getElementById("btn-match").addEventListener("click", doMatch);
+  document.getElementById("btn-autotune").addEventListener("click", doAutoTune);
+  document.getElementById("btn-save-recipe").addEventListener("click",
+    saveRecipe);
+  document.getElementById("btn-load-recipe").addEventListener("click",
+    loadRecipe);
+  document.getElementById("btn-unload-recipe").addEventListener("click",
+    unloadRecipe);
+  refreshRecipeList();
  const slider = document.getElementById("p-min-score");
  slider.addEventListener("input", (e) => {
    document.getElementById("v-score").textContent =
@@ -26,6 +26,10 @@
      <div class="picker-list"></div>
    </div>
    <button class="btn btn-go" id="btn-match">▶ MATCH</button>
+    <button class="btn" id="btn-autotune"
+            title="Analizza ROI e derivata parametri ottimali (Halcon-style)">
+      ⚙ Auto-tune
+    </button>
    <label class="btn" title="Carica nuovo file nella cartella immagini">
      ⬆ Carica file
      <input type="file" id="file-upload" accept="image/*" hidden>
@@ -129,6 +133,77 @@
      <input type="number" id="p-max-matches" value="25" min="1" max="200">
    </div>

+    <details>
+      <summary>Modalità Halcon</summary>
+      <div class="halcon-grid">
+        <label class="hc-row" title="16-bin orientation polarity-aware (mod 2π)">
+          <input type="checkbox" id="hc-use-polarity">
+          <span>Polarity 16-bin (F)</span>
+        </label>
+        <label class="hc-row" title="Score continuo cos(θ_t-θ_s) invece di bin">
+          <input type="checkbox" id="hc-soft-score">
+          <span>Soft-margin score (Y)</span>
+        </label>
+        <label class="hc-row" title="Sub-pixel refinement gradient field LM">
+          <input type="checkbox" id="hc-subpixel-lm">
+          <span>Sub-pixel LM 0.05 px (Z)</span>
+        </label>
+        <label class="hc-row" title="Refine congiunto Nelder-Mead (cx,cy,θ)">
+          <input type="checkbox" id="hc-refine-joint">
+          <span>Refine pose joint</span>
+        </label>
+        <label class="hc-row" title="Pyramid candidates propagation">
+          <input type="checkbox" id="hc-pyr-propagate">
+          <span>Pyramid propagate</span>
+        </label>
+        <label class="hc-row" title="OpenCL GPU offload (silent fallback CPU)">
+          <input type="checkbox" id="hc-use-gpu">
+          <span>GPU OpenCL (R)</span>
+        </label>
+
+        <div class="hc-row hc-num">
+          <label>Min recall (M)</label>
+          <input type="number" id="hc-min-recall" value="0.0" min="0" max="1" step="0.05">
+        </div>
+        <div class="hc-row hc-num">
+          <label>NMS IoU thr (A)</label>
+          <input type="number" id="hc-nms-iou" value="0.3" min="0" max="1" step="0.05">
+        </div>
+        <div class="hc-row hc-num">
+          <label>Greediness</label>
+          <input type="number" id="hc-greediness" value="0.0" min="0" max="1" step="0.1">
+        </div>
+        <div class="hc-row hc-num">
+          <label>Coarse stride</label>
+          <input type="number" id="hc-coarse-stride" value="1" min="1" max="4" step="1">
+        </div>
+        <div class="hc-row hc-num" style="grid-column:1/-1">
+          <label title="Limita area di ricerca scena: x,y,w,h (vuoto = tutta scena)">
+            Search ROI (x,y,w,h)
+          </label>
+          <input type="text" id="hc-search-roi" placeholder="es. 100,50,800,400">
+        </div>
+
+        <div class="hc-row" style="grid-column:1/-1; border-top:1px solid #444; padding-top:8px">
+          <label>Ricetta pre-trained (V)</label>
+          <div style="display:flex; gap:6px; margin-top:4px">
+            <input type="text" id="hc-recipe-name" placeholder="nome_ricetta" style="flex:1">
+            <button class="btn" id="btn-save-recipe" type="button">💾 Salva</button>
+          </div>
+          <div style="display:flex; gap:6px; margin-top:6px; align-items:center">
+            <select id="hc-recipe-list" style="flex:1">
+              <option value="">— ricette disponibili —</option>
+            </select>
+            <button class="btn" id="btn-load-recipe" type="button">📂 Carica</button>
+            <button class="btn" id="btn-unload-recipe" type="button" disabled>✖ Stacca</button>
+          </div>
+          <div id="recipe-status" style="margin-top:4px; font-size:11px; color:#888">
+            Nessuna ricetta caricata
+          </div>
+        </div>
+      </div>
+    </details>
+
    <details>
      <summary>Avanzate</summary>
      <div id="adv-form"></div>
@@ -156,3 +156,20 @@ footer h2 {
 }

 #col-model, #col-scene { min-width: 0; }
+
+/* Halcon-mode panel */
+.halcon-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 6px 12px;
+  margin-top: 6px;
+  font-size: 12px;
+}
+.hc-row {
+  display: flex; align-items: center; gap: 6px;
+}
+.hc-row.hc-num {
+  flex-direction: column; align-items: flex-start;
+}
+.hc-row.hc-num label { font-size: 11px; color: #aaa; }
+.hc-row.hc-num input { width: 100%; }
@@ -12,6 +12,9 @@ dependencies = [
    "uvicorn[standard]>=0.34",
 ]

+[project.scripts]
+pm2d-eval = "pm2d.eval:main"
+
 [dependency-groups]
 dev = [
    "httpx>=0.28.1",