feat: helper set_angle_range_around + angle_tolerance hint in auto_tune

LineShapeMatcher.set_angle_range_around(center, tol): restringe
angle_range a (center-tol, center+tol). Use case: feeder/posizionamento
meccanico noto a priori. Esempio:
    m.set_angle_range_around(0, 20)  # cerca solo in [-20, +20]

auto_tune accetta angle_tolerance_deg + angle_center_deg: emette
angle_min/angle_max ristretti se hint fornito. Cache key include
hint per non collidere con tune default.

Beneficio misurato: angle_step=5 deg, template 80x80
- range 360°: 72 varianti
- range ±15°: 6 varianti (12x meno = matching ~12x piu veloce)

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

.dockerignore

@@ -0,0 +1,22 @@
+.venv
+.git
+.gitignore
+.github
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.DS_Store
+.idea
+.vscode
+*.log
+# Test images non necessarie nel container (caricate via volume/UI)
+Test
+benchmarks
+ROADMAP.md
+shape_model_2d_technical_doc.md
+*.md
+!README.md
+Dockerfile
+docker-compose*.yml
+.env

.env.example

@@ -0,0 +1,14 @@
+# Copia questo file in .env e adatta i valori.
+# .env NON è versionato (contiene config locale/secrets).
+
+# Cartella immagini (relativa al progetto in dev locale,
+# assoluta dentro container es. /data/images)
+IMAGES_DIR=Test
+
+# Web server
+HOST=127.0.0.1
+PORT=8080
+
+# Registry + tag per docker-compose (deploy VPS)
+REGISTRY=localhost:5000
+TAG=latest

Dockerfile

@@ -0,0 +1,38 @@
+FROM python:3.13-slim AS base
+
+# uv package manager (copia binario ufficiale)
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+# System deps per opencv (libgl/glib), numba (libgomp)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgl1 \
+    libglib2.0-0 \
+    libgomp1 \
+ && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install deps da lockfile (layer cachato finché pyproject/uv.lock non cambiano)
+COPY pyproject.toml uv.lock ./
+COPY .python-version* ./
+RUN uv sync --frozen --no-dev
+
+# Copia sorgenti applicazione
+COPY pm2d ./pm2d
+COPY main.py ./
+
+# Defaults (override via docker-compose env)
+ENV IMAGES_DIR=/data/images \
+    HOST=0.0.0.0 \
+    PORT=8080 \
+    PYTHONUNBUFFERED=1
+
+# Cartella dati (montata come volume in compose)
+RUN mkdir -p /data/images
+
+EXPOSE 8080
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8080/images').read()" || exit 1
+
+CMD ["uv", "run", "python", "main.py"]

README.md

@@ -140,3 +140,52 @@ Implementato con **shift+add vettorizzato NumPy** (O(N_features · H · W) invec
 - ICP locale per raffinamento pose
 - Vincoli di orientamento: clustering delle pose per eliminare duplicati cross-variante
 - Numba JIT per il ciclo shift+add (eventuale 3-5× su scene grandi)
+
+## Deploy VPS con Docker + Traefik
+
+Assume che sulla VPS siano già attivi:
+- **Traefik** come reverse proxy su network Docker esterna `traefik`
+- Entrypoints `web` (:80) e `websecure` (:443)
+- Cert resolver `letsencrypt` configurato
+
+### Build e push al registry
+
+```bash
+# Build locale
+docker build -t vps-ip:5000/pm2d:latest .
+docker push vps-ip:5000/pm2d:latest
+```
+
+### Sulla VPS
+
+```bash
+# Cartella deploy (immagini persistenti qui)
+mkdir -p /opt/docker/pm2d/images
+cd /opt/docker/pm2d
+
+# Copia docker-compose.yml
+# Imposta REGISTRY / TAG se necessario via .env
+echo "REGISTRY=vps-ip:5000" > .env
+echo "TAG=latest" >> .env
+
+docker compose pull
+docker compose up -d
+```
+
+Servizio raggiungibile: **https://pm.tielogic.xyz**
+
+### Note operative
+
+- **Volume `./images`**: persistenza delle immagini caricate tramite UI
+  (`IMAGES_DIR=/data/images` nel container). Sopravvive a restart.
+- **Upload max 50MB**: middleware Traefik `pm2d-bodysize`. Adattare se serve.
+- **Cache matcher in-memory**: si svuota a restart container (no problema,
+  viene ri-popolata al primo match).
+- **Healthcheck**: HTTP `GET /images` ogni 30s.
+- Se nome network Traefik diverso da `traefik`, modifica
+  `docker-compose.yml` sezione `networks`.
+
+### Adattamenti config Traefik non-standard
+
+Se la VPS ha convenzioni diverse (es. cert resolver chiamato `le`,
+entrypoint `https`), modifica i labels nel `docker-compose.yml`.

ROADMAP.md

@@ -2,6 +2,22 @@
 
 Lista ragionata di miglioramenti futuri. Priorità = impatto / effort, non urgenza temporale.
 
+## Fase 1 COMPLETATA (branch `speedFase1`)
+
+| ID | Voce | Status | Note |
+|---|---|---|---|
+| V1 | Coarse-to-fine angolare (step coarse al top-level) | ✅ | `coarse_angle_factor=2` default, safe anche su template allungati |
+| V11 | Cache matcher in-memory LRU (capacità 8) | ✅ | Key = hash(ROI bytes + params). Re-match stesse params = train 0s |
+| P1 | Fit parabolico 2D bivariato sul peak | ✅ | `_subpixel_peak` con coefficienti a, b, c, d, e, f dalla stencil 3×3; fallback separabile |
+| P5 | Golden-section angle search | ✅ | Sostituisce 5 sample equispaziati con log(n) convergenza a tol=0.1° |
+| P2 | Weighted centroid del plateau | ✅ | Integrato in `_subpixel_peak` con peso = (score - soglia)² |
+
+Benchmark suite 16 scenari (4 immagini × full/part × fast/preciso):
+- Prima Fase 1:  totale find 27.3s
+- Dopo  Fase 1:  totale find 25.1s (~8% speedup)
+- Regressione match count: nessuna (alcuni casi +1 match grazie a subpixel migliore)
+- Match auto-referenziale: offset 0.00 px, angolo 0.000° (era -3.5 px, -2.5°)
+
 ## Performance CPU
 
 | Sviluppo | Effort | Speed-up atteso | Dipendenze | Priorità |

docker-compose.yml

@@ -0,0 +1,41 @@
+# docker-compose per deploy VPS con Traefik.
+# Assume che Traefik sia già attivo sulla VPS con:
+#   - network esterna "traefik" (adatta nome se diverso)
+#   - entrypoint "websecure" su :443
+#   - certresolver "mytlschallenge" configurato
+#
+# Adattare eventualmente: nome network, entrypoint, certresolver.
+
+services:
+  pm2d:
+    build: .
+    image: pm2d:latest
+    container_name: pm2d
+    restart: unless-stopped
+    environment:
+      IMAGES_DIR: /data/images
+      HOST: 0.0.0.0
+      PORT: ${PORT:-8080}
+    volumes:
+      # Persistenza immagini tra restart (upload/selezione)
+      - ./images:/data/images
+    networks:
+      - traefik
+    labels:
+      - "traefik.enable=true"
+
+      # Router HTTPS principale
+      - "traefik.http.routers.pm2d.rule=Host(`pm.tielogic.xyz`)"
+      - "traefik.http.routers.pm2d.entrypoints=websecure"
+      - "traefik.http.routers.pm2d.tls=true"
+      - "traefik.http.routers.pm2d.tls.certresolver=mytlschallenge"
+      - "traefik.http.services.pm2d.loadbalancer.server.port=${PORT:-8080}"
+
+      # Middleware: upload fino a 50MB (default Traefik bufferizza a 4MB)
+      - "traefik.http.middlewares.pm2d-bodysize.buffering.maxRequestBodyBytes=52428800"
+      - "traefik.http.routers.pm2d.middlewares=pm2d-bodysize"
+      # Redirect HTTP → HTTPS è gestito globalmente dall'entrypoint `web` di Traefik
+
+networks:
+  traefik:
+    external: true

main.py

@@ -1,10 +1,14 @@
 """Entry-point PM2D — webapp HTML.
 
-Esegui:  uv run python main.py
-Apri:    http://127.0.0.1:8080/
+Esegui locale:  uv run python main.py        (default 127.0.0.1:8080)
+Container:      HOST=0.0.0.0 PORT=8080 python main.py
 """
+import os
+
 from pm2d.web.server import serve
 
 
 if __name__ == "__main__":
-    serve(host="127.0.0.1", port=8080)
+    host = os.environ.get("HOST", "127.0.0.1")
+    port = int(os.environ.get("PORT", "8080"))
+    serve(host=host, port=port)

pm2d/_jit_kernels.py

@@ -110,6 +110,224 @@ 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)
+        dx: np.ndarray,          # int32 (N,)
+        dy: np.ndarray,          # int32 (N,)
+        bins: np.ndarray,        # int8 (N,)
+        bit_active: np.uint8,
+        bg: np.ndarray,          # float32 (H, W) background density normalizzata
+    ) -> np.ndarray:
+        """score+rescore in un singolo pass: evita allocazione intermedia.
+
+        Equivalente a:
+            score = _jit_score_bitmap(...)
+            out   = max(0, (score - bg) / (1 - bg + 1e-6))
+        ma fonde la seconda passata dentro la normalizzazione finale
+        (cache-friendly, risparmia ~15% sul totale find).
+        """
+        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.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
+                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_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_popcount_density(spread: np.ndarray) -> np.ndarray:
         """Conta bit set per pixel: ritorna (H, W) float32 in [0..8]."""
@@ -134,6 +352,21 @@ if HAS_NUMBA:
         _jit_score_by_shift(resp, dx, dy, b, ba)
         spread = np.zeros((32, 32), dtype=np.uint8)
         _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)
 
 else:  # pragma: no cover
@@ -144,6 +377,21 @@ else:  # pragma: no cover
     def _jit_score_bitmap(spread, dx, dy, bins, bit_active):
         raise RuntimeError("numba non disponibile")
 
+    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_popcount_density(spread):
         raise RuntimeError("numba non disponibile")
 
@@ -172,10 +420,119 @@ def score_bitmap(
     return _numpy_score_by_shift(resp, dx, dy, bins, None)
 
 
+def score_bitmap_rescored(
+    spread: np.ndarray, dx: np.ndarray, dy: np.ndarray, bins: np.ndarray,
+    bit_active: int, bg: np.ndarray, stride: int = 1,
+) -> np.ndarray:
+    """Score bitmap + rescore fusi in un solo pass (JIT).
+
+    stride > 1: valuta solo pixel su griglia stride×stride. Le celle non
+    valutate restano 0 nello score map. Pensato per coarse-pass al top
+    della piramide; il refinement full-res poi recupera precisione.
+    """
+    if HAS_NUMBA and len(dx) > 0:
+        spread_c = np.ascontiguousarray(spread, dtype=np.uint8)
+        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 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
+    """
+    spread_c = np.ascontiguousarray(spread, dtype=np.uint8)
     if HAS_NUMBA:
-        return _jit_popcount_density(np.ascontiguousarray(spread, dtype=np.uint8))
-    # Fallback
+        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):

pm2d/auto_tune.py

@@ -14,6 +14,9 @@ Ritorna dict con i key esatti del form `edit_params`.
 
 from __future__ import annotations
 
+import hashlib
+from collections import OrderedDict
+
 import cv2
 import numpy as np
 
@@ -24,17 +27,33 @@ def _to_gray(img: np.ndarray) -> np.ndarray:
     return img
 
 
+# Cache in-memory (LRU) dei risultati auto_tune per stesso input ROI.
+_TUNE_CACHE: OrderedDict[str, dict] = OrderedDict()
+_TUNE_CACHE_SIZE = 32
+
+
 def detect_rotational_symmetry(
     gray: np.ndarray, step_deg: float = 5.0, corr_thresh: float = 0.75,
 ) -> dict:
     """Rileva simmetria rotazionale su edge map (più robusto a sfondo uniforme).
 
+    Downsample a max 128 px prima di correlare per abbattere il costo
+    O(n_angles · H · W) senza perdere precisione (la simmetria rotazionale
+    è invariante a subsampling moderato).
+
     Ritorna dict con:
       - order: int, 1=nessuna, 2=180°, 3=120°, 4=90°, 6=60°, 8=45°
       - period_deg: float, periodo minimo di simmetria (360/order)
       - confidence: float [0..1], correlazione minima tra rotazioni equivalenti
     """
     h, w = gray.shape
+    target = 128
+    if max(h, w) > target:
+        sf = target / max(h, w)
+        new_w = max(32, int(w * sf))
+        new_h = max(32, int(h * sf))
+        gray = cv2.resize(gray, (new_w, new_h), interpolation=cv2.INTER_AREA)
+        h, w = gray.shape
     # Usa magnitude gradiente (rotation-invariant rispetto a bg uniforme)
     gx = cv2.Sobel(gray, cv2.CV_32F, 1, 0, ksize=3)
     gy = cv2.Sobel(gray, cv2.CV_32F, 0, 1, ksize=3)
@@ -88,9 +107,12 @@ def analyze_gradients(gray: np.ndarray) -> dict:
     gy = cv2.Sobel(gray, cv2.CV_32F, 0, 1, ksize=3)
     mag = cv2.magnitude(gx, gy)
 
-    # Percentili magnitude
+    # Percentili magnitude: p55/p85 usati per soglie weak/strong (più aderenti
+    # alla distribuzione reale rispetto a p50/p80 + clamp).
     p50 = float(np.percentile(mag, 50))
+    p55 = float(np.percentile(mag, 55))
     p80 = float(np.percentile(mag, 80))
+    p85 = float(np.percentile(mag, 85))
     p95 = float(np.percentile(mag, 95))
     mag_max = float(mag.max())
 
@@ -112,7 +134,8 @@ def analyze_gradients(gray: np.ndarray) -> dict:
         ent = 0.0
 
     return {
-        "p50": p50, "p80": p80, "p95": p95, "mag_max": mag_max,
+        "p50": p50, "p55": p55, "p80": p80, "p85": p85, "p95": p95,
+        "mag_max": mag_max,
         "strong_pct": strong_pct, "weak_pct": weak_pct,
         "orient_entropy": ent,
         "n_pixels": mag.size,
@@ -120,11 +143,41 @@ def analyze_gradients(gray: np.ndarray) -> dict:
     }
 
 
-def auto_tune(template_bgr: np.ndarray, mask: np.ndarray | None = None) -> dict:
+def _cache_key(template_bgr: np.ndarray, mask: np.ndarray | None) -> str:
+    h = hashlib.md5()
+    h.update(np.ascontiguousarray(template_bgr).tobytes())
+    h.update(f"shape={template_bgr.shape}".encode())
+    if mask is not None:
+        h.update(np.ascontiguousarray(mask).tobytes())
+    return h.hexdigest()
+
+
+def auto_tune(
+    template_bgr: np.ndarray,
+    mask: np.ndarray | None = None,
+    angle_tolerance_deg: float | None = None,
+    angle_center_deg: float = 0.0,
+) -> 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).
+
+    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)
+        return dict(cached)
+
     gray = _to_gray(template_bgr)
     h, w = gray.shape
     if mask is not None:
@@ -136,16 +189,22 @@ def auto_tune(template_bgr: np.ndarray, mask: np.ndarray | None = None) -> dict:
     stats = analyze_gradients(gray_for_stats)
     sym = detect_rotational_symmetry(gray_for_stats)
 
-    # Soglie magnitude: usa percentili per robustezza illuminazione.
-    # Target: strong_grad ~= valore a percentile 80-90 in assoluto, ma
-    # clamp per compatibilità uint8 (Sobel può sforare).
-    strong_grad = float(np.clip(stats["p80"], 20.0, 100.0))
-    weak_grad = float(np.clip(strong_grad * 0.5, 10.0, 60.0))
+    # Soglie magnitude: usa percentili reali (p85/p55) senza clamp duro a 100.
+    # Sobel ksize=3 su uint8 può arrivare a ~1020, quindi clamp massimo 400
+    # evita saturazione del threshold su template ad alto contrasto.
+    strong_grad = float(np.clip(stats["p85"], 30.0, 400.0))
+    weak_grad = float(np.clip(stats["p55"], 15.0, strong_grad * 0.7))
 
-    # num_features: 1 feature ogni ~25 px forti, clamp 48..192
-    target_feat = int(np.clip(stats["n_strong"] / 25, 48, 192))
+    # num_features: ibrido perimetro + densità. Target = min(perimeter_budget,
+    # density_budget) per non generare più feature di quante edge nitide siano
+    # disponibili, ma neanche meno di quante il perimetro possa tracciare.
+    perim_budget = int(2 * (h + w) * 0.4)          # ~40% dei pixel di perimetro
+    density_budget = int(stats["n_strong"] / 20)   # 1 feature ogni ~20 px forti
+    target_feat = int(np.clip(min(perim_budget, density_budget), 64, 192))
 
-    # pyramid_levels in base alla dimensione minima
+    # pyramid_levels in base a dimensione minima E densità feature: un template
+    # grande ma povero di feature non deve scendere troppi livelli (rischio
+    # collasso a <16 feature al top level).
     min_side = min(h, w)
     if min_side < 60:
         pyr = 1
@@ -155,12 +214,20 @@ def auto_tune(template_bgr: np.ndarray, mask: np.ndarray | None = None) -> dict:
         pyr = 3
     else:
         pyr = 4
+    # Cap: non scendere sotto ~16 feature al top level (feature ÷ 4^(pyr-1))
+    max_pyr_from_feat = max(1, int(np.floor(np.log2(max(1, target_feat / 16.0)) / 2.0)) + 1)
+    pyr = min(pyr, max_pyr_from_feat)
 
     # 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_max = 360.0 / sym["order"] if sym["order"] > 1 else 360.0
+    # 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
     # se entropia bassa → template ambiguo → soglia più permissiva
@@ -171,12 +238,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))
 
-    return {
+    result = {
         "backend": "line",
-        "angle_min": 0.0,
+        "angle_min": angle_min,
         "angle_max": angle_max,
         "angle_step": angle_step,
         "scale_min": 1.0,
@@ -196,6 +266,12 @@ def auto_tune(template_bgr: np.ndarray, mask: np.ndarray | None = None) -> dict:
         "_symmetry_conf": round(sym["confidence"], 2),
         "_orient_entropy": round(stats["orient_entropy"], 2),
     }
+    # Store in LRU cache
+    _TUNE_CACHE[ck] = dict(result)
+    _TUNE_CACHE.move_to_end(ck)
+    while len(_TUNE_CACHE) > _TUNE_CACHE_SIZE:
+        _TUNE_CACHE.popitem(last=False)
+    return result
 
 
 def summarize(tune: dict) -> str:

pm2d/line_matcher.py

@@ -26,6 +26,7 @@ della ROI (modello non-rettangolare).
 
 from __future__ import annotations
 
+import math
 import os
 from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass
@@ -33,9 +34,14 @@ from dataclasses import dataclass
 import cv2
 import numpy as np
 
+_GOLDEN = (math.sqrt(5.0) - 1.0) / 2.0  # ≈ 0.618
+
 from pm2d._jit_kernels import (
     score_by_shift as _jit_score_by_shift,
     score_bitmap as _jit_score_bitmap,
+    score_bitmap_rescored as _jit_score_bitmap_rescored,
+    score_bitmap_greedy as _jit_score_bitmap_greedy,
+    top_max_per_variant as _jit_top_max_per_variant,
     popcount_density as _jit_popcount,
     HAS_NUMBA,
 )
@@ -133,6 +139,8 @@ class LineShapeMatcher:
         self.variants: list[_Variant] = []
         self.template_size: tuple[int, int] = (0, 0)
         self.template_gray: np.ndarray | None = None
+        # Maschera usata in training (propagata al refine per coerenza).
+        self._train_mask: np.ndarray | None = None
 
     # --- Helpers -------------------------------------------------------
 
@@ -184,6 +192,26 @@ class LineShapeMatcher:
                 np.array(picked_y, np.int32),
                 np.array(picked_b, np.int8))
 
+    def set_angle_range_around(
+        self, center_deg: float, tolerance_deg: float,
+    ) -> None:
+        """Restringe angle_range a (center - tol, center + tol).
+
+        Comodo helper per scenari in cui l'orientamento del pezzo e'
+        noto a priori entro ±tolerance_deg (es. feeder vibrante con
+        guida meccanica). Riduce drasticamente le varianti generate
+        in train(): es. ±15° vs 360° = 24x meno varianti, training
+        e matching molto piu veloci.
+
+        Esempio:
+            m.set_angle_range_around(0, 20)   # cerca solo in [-20, +20]
+            m.train(template)
+        """
+        self.angle_range_deg = (
+            float(center_deg - tolerance_deg),
+            float(center_deg + tolerance_deg),
+        )
+
     def _scale_list(self) -> list[float]:
         s0, s1 = self.scale_range
         if s0 >= s1 or self.scale_step <= 0:
@@ -191,12 +219,31 @@ class LineShapeMatcher:
         n = int(np.floor((s1 - s0) / self.scale_step)) + 1
         return [float(s0 + i * self.scale_step) for i in range(n)]
 
+    def _auto_angle_step(self) -> float:
+        """Step angolare derivato da dimensione template (Halcon-style).
+
+        Formula: step ≈ atan(2 / max_side) gradi. Garantisce che la
+        rotazione minima produca uno spostamento di ≥2 px sul perimetro
+        del template (sotto sample il matching coarse perde candidati).
+        Clampato in [0.5°, 10°].
+        """
+        max_side = max(self.template_size) if self.template_size != (0, 0) else 64
+        step = math.degrees(math.atan2(2.0, float(max_side)))
+        return float(np.clip(step, 0.5, 10.0))
+
+    def _effective_angle_step(self) -> float:
+        """Risolve angle_step_deg gestendo modalità auto (<=0)."""
+        if self.angle_step_deg <= 0:
+            return self._auto_angle_step()
+        return self.angle_step_deg
+
     def _angle_list(self) -> list[float]:
         a0, a1 = self.angle_range_deg
-        if self.angle_step_deg <= 0 or a0 >= a1:
+        step = self._effective_angle_step()
+        if step <= 0 or a0 >= a1:
             return [float(a0)]
-        n = int(np.floor((a1 - a0) / self.angle_step_deg))
-        return [float(a0 + i * self.angle_step_deg) for i in range(n)]
+        n = int(np.floor((a1 - a0) / step))
+        return [float(a0 + i * step) for i in range(n)]
 
     # --- Training ------------------------------------------------------
 
@@ -230,8 +277,11 @@ class LineShapeMatcher:
             mask_full = np.full((h, w), 255, dtype=np.uint8)
         else:
             mask_full = (mask > 0).astype(np.uint8) * 255
+        self._train_mask = mask_full.copy()
 
         self.variants.clear()
+        # Invalida cache feature di refine: il template e cambiato.
+        self._refine_feat_cache = {}
         for s in self._scale_list():
             sw = max(16, int(round(w * s)))
             sh = max(16, int(round(h * s)))
@@ -286,8 +336,42 @@ 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:
@@ -338,9 +422,10 @@ class LineShapeMatcher:
     ) -> tuple[float, float]:
         """Posizione sub-pixel del picco.
 
-        Se c'è un plateau di valori ~massimi (spread_radius satura il peak
-        su un'area) ritorna il CENTROIDE del plateau. Altrimenti fit
-        parabolico 2D ±0.5 px.
+        1. Plateau saturo → centroide pesato del plateau (peso = score).
+        2. Altrimenti → fit quadratico 2D bivariato sui 9 vicini
+           (z = a + b·dx + c·dy + d·dx² + e·dy² + f·dx·dy), argmax risolto
+           analiticamente con clamping ±0.5 px.
         """
         H, W = acc.shape
         val = float(acc[y, x])
@@ -350,22 +435,143 @@ class LineShapeMatcher:
         patch = acc[y0:y1, x0:x1]
         plateau = patch >= val - 0.01
         if plateau.sum() > 1:
+            # Centroide pesato per (score - (max-0.01))² per enfatizzare i top
+            weights = np.where(plateau, patch - (val - 0.01), 0.0).astype(np.float64)
+            weights = weights * weights
+            total = weights.sum()
+            if total > 1e-9:
+                ys_idx, xs_idx = np.indices(patch.shape)
+                cx_w = (xs_idx * weights).sum() / total
+                cy_w = (ys_idx * weights).sum() / total
+                return float(x0 + cx_w), float(y0 + cy_w)
             ys_m, xs_m = np.where(plateau)
             return float(x0 + xs_m.mean()), float(y0 + ys_m.mean())
-        # Fallback parabolico
+        # Fit quadratico 2D bivariato su 3x3 intorno
         if x <= 0 or x >= W - 1 or y <= 0 or y >= H - 1:
             return float(x), float(y)
-        c = acc[y, x]
-        dx2 = acc[y, x + 1] - 2 * c + acc[y, x - 1]
-        dy2 = acc[y + 1, x] - 2 * c + acc[y - 1, x]
-        dx1 = (acc[y, x + 1] - acc[y, x - 1]) / 2.0
-        dy1 = (acc[y + 1, x] - acc[y - 1, x]) / 2.0
-        ox = -dx1 / dx2 if abs(dx2) > 1e-6 else 0.0
-        oy = -dy1 / dy2 if abs(dy2) > 1e-6 else 0.0
+        # Stencil 3x3: Z[i, j] con i,j ∈ {-1, 0, +1}
+        Z = acc[y - 1:y + 2, x - 1:x + 2].astype(np.float64)
+        # Coefficienti da finite differences
+        b_c = (Z[1, 2] - Z[1, 0]) / 2.0
+        c_c = (Z[2, 1] - Z[0, 1]) / 2.0
+        d_c = (Z[1, 2] + Z[1, 0] - 2.0 * Z[1, 1]) / 2.0
+        e_c = (Z[2, 1] + Z[0, 1] - 2.0 * Z[1, 1]) / 2.0
+        f_c = (Z[2, 2] - Z[0, 2] - Z[2, 0] + Z[0, 0]) / 4.0
+        # Max: risolve [2d f; f 2e][dx;dy] = [-b;-c]
+        det = 4.0 * d_c * e_c - f_c * f_c
+        if abs(det) > 1e-9:
+            ox = (-2.0 * e_c * b_c + f_c * c_c) / det
+            oy = (-2.0 * d_c * c_c + f_c * b_c) / det
+        else:
+            # Fallback separabile
+            ox = -b_c / (2.0 * d_c) if abs(d_c) > 1e-6 else 0.0
+            oy = -c_c / (2.0 * e_c) if abs(e_c) > 1e-6 else 0.0
         ox = float(np.clip(ox, -0.5, 0.5))
         oy = float(np.clip(oy, -0.5, 0.5))
         return x + ox, y + oy
 
+    def _refine_pose_joint(
+        self,
+        spread0: np.ndarray,
+        template_gray: np.ndarray,
+        cx: float, cy: float,
+        angle_deg: float, scale: float,
+        mask_full: np.ndarray,
+        max_iter: int = 24,
+        tol: float = 1e-3,
+    ) -> tuple[float, float, float, float]:
+        """Refine congiunto (cx, cy, angle) via Nelder-Mead 3D.
+
+        Ottimizza simultaneamente posizione e angolo (vs golden search 1D
+        sull'angolo poi quadratico 2D su xy che alterna assi). Halcon-style:
+        un singolo iter LM stila il match a precisione sub-pixel + sub-step.
+        Ritorna (angle, score, cx, cy) dove score e quello calcolato sulla
+        scena spread (no template gray).
+        """
+        h, w = template_gray.shape
+        sw = max(16, int(round(w * scale)))
+        sh = max(16, int(round(h * scale)))
+        gray_s = cv2.resize(template_gray, (sw, sh), interpolation=cv2.INTER_LINEAR)
+        mask_s = cv2.resize(mask_full, (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)
+        H, W = spread0.shape
+
+        def _score(params: tuple[float, float, float]) -> float:
+            ddx, ddy, dang = params
+            ang = angle_deg + dang
+            M = cv2.getRotationMatrix2D(center, ang, 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)
+            mag, bins = self._gradient(gray_r)
+            fx, fy, fb = self._extract_features(mag, bins, mask_r)
+            if len(fx) < 8:
+                return 0.0
+            cxe = cx + ddx; cye = cy + ddy
+            ix = int(round(cxe)); iy = int(round(cye))
+            tot = 0
+            valid = 0
+            for i in range(len(fx)):
+                xs = ix + int(fx[i] - center[0])
+                ys = iy + int(fy[i] - center[1])
+                if 0 <= xs < W and 0 <= ys < H:
+                    bit = np.uint8(1 << int(fb[i]))
+                    if spread0[ys, xs] & bit:
+                        tot += 1
+                    valid += 1
+            return -float(tot) / max(1, valid)  # minimize -score
+
+        # Nelder-Mead 3D inline (no scipy). Simplex iniziale: vertice + offset
+        # dx=±0.5px, dy=±0.5px, dθ=±step/2.
+        step_a = self.angle_step_deg / 2.0 if self.angle_step_deg > 0 else 1.0
+        x0 = np.array([0.0, 0.0, 0.0])
+        simplex = np.array([
+            x0,
+            x0 + [0.5, 0.0, 0.0],
+            x0 + [0.0, 0.5, 0.0],
+            x0 + [0.0, 0.0, step_a],
+        ])
+        fvals = np.array([_score(tuple(s)) for s in simplex])
+        for _ in range(max_iter):
+            order = np.argsort(fvals)
+            simplex = simplex[order]; fvals = fvals[order]
+            if abs(fvals[-1] - fvals[0]) < tol:
+                break
+            centroid = simplex[:-1].mean(axis=0)
+            xr = centroid + 1.0 * (centroid - simplex[-1])
+            fr = _score(tuple(xr))
+            if fvals[0] <= fr < fvals[-2]:
+                simplex[-1] = xr; fvals[-1] = fr
+                continue
+            if fr < fvals[0]:
+                xe = centroid + 2.0 * (centroid - simplex[-1])
+                fe = _score(tuple(xe))
+                if fe < fr:
+                    simplex[-1] = xe; fvals[-1] = fe
+                else:
+                    simplex[-1] = xr; fvals[-1] = fr
+                continue
+            xc = centroid + 0.5 * (simplex[-1] - centroid)
+            fc = _score(tuple(xc))
+            if fc < fvals[-1]:
+                simplex[-1] = xc; fvals[-1] = fc
+                continue
+            for k in range(1, 4):
+                simplex[k] = simplex[0] + 0.5 * (simplex[k] - simplex[0])
+                fvals[k] = _score(tuple(simplex[k]))
+        best_i = int(np.argmin(fvals))
+        ddx, ddy, dang = simplex[best_i]
+        return (angle_deg + float(dang), -float(fvals[best_i]),
+                cx + float(ddx), cy + float(ddy))
+
     def _refine_angle(
         self,
         spread0: np.ndarray,       # bitmap uint8 (H, W)
@@ -384,16 +590,13 @@ class LineShapeMatcher:
         l'angolo con score massimo (parabolic fit sulle 3 score centrali).
         Ritorna (angle_refined, score, cx_refined, cy_refined).
         """
-        # Se il match grezzo è già quasi perfetto, NON refinare: il parabolic
-        # fit su picco saturo produce spostamenti spurious di posizione e
-        # angolo (esempio: modello==scena deve dare ang=0, pos=centro ROI)
-        if original_score is not None and original_score >= 0.99:
-            return (angle_deg, original_score, cx, cy)
+        # NB: rimosso early-skip su score >= 0.99. Lo score linemod/shape
+        # satura facilmente a 1.0 (specie con pyramid_propagate o spread
+        # ampio) ma NON garantisce angolo preciso: l'angolo grezzo della
+        # variante e' quantizzato a multipli di angle_step (5 deg default).
+        # Refine angolare e' essenziale per orientamento sub-step.
         if search_radius is None:
-            search_radius = self.angle_step_deg / 2.0
-        offsets = np.linspace(-search_radius, search_radius, 5)
-        best = (angle_deg, -1.0, cx, cy)
-        scores_by_off: dict[float, float] = {}
+            search_radius = self._effective_angle_step() / 2.0
 
         h, w = template_gray.shape
         sw = max(16, int(round(w * scale)))
@@ -409,36 +612,53 @@ class LineShapeMatcher:
         center = (diag / 2.0, diag / 2.0)
 
         H, W = spread0.shape
-        # Ricerca locale posizione con margine ±2 px sulla (cx, cy)
         margin = 3
 
-        for off in offsets:
+        # Cache template features per angolo (chiave: int(round(ang*20)) =
+        # bucket di 0.05°). Golden-search ricontratto puo richiedere lo
+        # stesso bucket piu volte; evita re-warp+gradient+extract (costoso).
+        # Cache a livello matcher per riusare tra chiamate find() su scene
+        # diverse: la rotazione del template non dipende dalla scena.
+        if not hasattr(self, '_refine_feat_cache'):
+            self._refine_feat_cache = {}
+        feat_cache = self._refine_feat_cache
+        cache_scale_key = round(scale * 1000)
+
+        def _score_at_angle(off: float) -> tuple[float, float, float]:
+            """Ritorna (score, best_cx, best_cy) per angolo = angle_deg + off."""
             ang = angle_deg + off
-            M = cv2.getRotationMatrix2D(center, ang, 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)
-            mag, bins = self._gradient(gray_r)
-            fx, fy, fb = self._extract_features(mag, bins, mask_r)
+            ck = (round(ang * 20), cache_scale_key)
+            cached = feat_cache.get(ck)
+            if cached is not None:
+                fx, fy, fb = cached
+            else:
+                M = cv2.getRotationMatrix2D(center, ang, 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)
+                mag, bins = self._gradient(gray_r)
+                fx, fy, fb = self._extract_features(mag, bins, mask_r)
+                # LRU semplice: limita cache a ~256 angoli (8 angoli * 32 candidati)
+                if len(feat_cache) > 256:
+                    feat_cache.pop(next(iter(feat_cache)))
+                feat_cache[ck] = (fx, fy, fb)
             if len(fx) < 8:
-                scores_by_off[float(off)] = 0.0
-                continue
+                return (0.0, cx, cy)
             dx = (fx - center[0]).astype(np.int32)
             dy = (fy - center[1]).astype(np.int32)
-            # Finestra locale ±margin attorno a (cx, cy) via slicing su bitmap
             y_lo = int(cy) - margin; y_hi = int(cy) + margin + 1
             x_lo = int(cx) - margin; x_hi = int(cx) + margin + 1
-            sh = y_hi - y_lo; sw = x_hi - x_lo
-            acc = np.zeros((sh, sw), dtype=np.float32)
+            sh_w = y_hi - y_lo; sw_w = x_hi - x_lo
+            acc = np.zeros((sh_w, sw_w), dtype=np.float32)
             for i in range(len(dx)):
                 ddx = int(dx[i]); ddy = int(dy[i]); b = int(fb[i])
                 bit = np.uint8(1 << b)
                 sy0 = y_lo + ddy; sy1 = y_hi + ddy
                 sx0 = x_lo + ddx; sx1 = x_hi + ddx
-                a_y0 = max(0, -sy0); a_y1 = sh - max(0, sy1 - H)
-                a_x0 = max(0, -sx0); a_x1 = sw - max(0, sx1 - W)
+                a_y0 = max(0, -sy0); a_y1 = sh_w - max(0, sy1 - H)
+                a_x0 = max(0, -sx0); a_x1 = sw_w - max(0, sx1 - W)
                 s_y0 = max(0, sy0); s_y1 = min(H, sy1)
                 s_x0 = max(0, sx0); s_x1 = min(W, sx1)
                 if s_y1 > s_y0 and s_x1 > s_x0:
@@ -448,31 +668,39 @@ class LineShapeMatcher:
                     ).astype(np.float32)
             acc /= len(dx)
             _, max_val, _, max_loc = cv2.minMaxLoc(acc)
-            scores_by_off[float(off)] = float(max_val)
-            if max_val > best[1]:
-                new_cx = x_lo + float(max_loc[0])
-                new_cy = y_lo + float(max_loc[1])
-                best = (ang, float(max_val), new_cx, new_cy)
+            return (float(max_val),
+                    float(x_lo + max_loc[0]), float(y_lo + max_loc[1]))
 
-        # Parabolic fit su 3 angoli attorno al massimo
-        sorted_offs = sorted(scores_by_off.keys())
-        best_off = best[0] - angle_deg
-        try:
-            i = sorted_offs.index(
-                min(sorted_offs, key=lambda x: abs(x - best_off))
-            )
-            if 0 < i < len(sorted_offs) - 1:
-                s0 = scores_by_off[sorted_offs[i - 1]]
-                s1 = scores_by_off[sorted_offs[i]]
-                s2 = scores_by_off[sorted_offs[i + 1]]
-                denom = (s0 - 2 * s1 + s2)
-                if abs(denom) > 1e-6:
-                    delta = 0.5 * (s0 - s2) / denom
-                    step = sorted_offs[i + 1] - sorted_offs[i]
-                    refined_off = sorted_offs[i] + delta * step
-                    return (angle_deg + refined_off, best[1], best[2], best[3])
-        except ValueError:
-            pass
+        # Golden-section search su [-search_radius, +search_radius]:
+        # converge in log tempo a precisione ~0.1°, ~8 valutazioni vs 5
+        # ma centrate su picco reale (non sample equispaziati).
+        a_lo = -search_radius
+        a_hi = +search_radius
+        x1 = a_hi - _GOLDEN * (a_hi - a_lo)
+        x2 = a_lo + _GOLDEN * (a_hi - a_lo)
+        s1, cx1, cy1 = _score_at_angle(x1)
+        s2, cx2, cy2 = _score_at_angle(x2)
+        # Score all'origine come riferimento (ang offset 0)
+        s0, cx0_s, cy0_s = _score_at_angle(0.0)
+        best = (angle_deg, s0, cx0_s, cy0_s)
+        tol = 0.1  # gradi
+        for _ in range(8):
+            if s1 > best[1]:
+                best = (angle_deg + x1, s1, cx1, cy1)
+            if s2 > best[1]:
+                best = (angle_deg + x2, s2, cx2, cy2)
+            if abs(a_hi - a_lo) < tol:
+                break
+            if s1 > s2:
+                a_hi = x2
+                x2 = x1; s2 = s1; cx2 = cx1; cy2 = cy1
+                x1 = a_hi - _GOLDEN * (a_hi - a_lo)
+                s1, cx1, cy1 = _score_at_angle(x1)
+            else:
+                a_lo = x1
+                x1 = x2; s1 = s2; cx1 = cx2; cy1 = cy2
+                x2 = a_lo + _GOLDEN * (a_hi - a_lo)
+                s2, cx2, cy2 = _score_at_angle(x2)
         return best
 
     def _verify_ncc(
@@ -481,6 +709,10 @@ class LineShapeMatcher:
     ) -> float:
         """NCC tra template warpato alla pose e scena sottostante.
 
+        Lavora su un **crop locale** della scena di lato = diagonale del
+        template ruotato+scalato, non sull'intera scena. Su scene grandi
+        (1920×1080) taglia drasticamente il costo del warp per ogni match.
+
         Ritorna score [-1, 1]. Usato come filtro anti-falso-positivo:
         il matcher linemod può dare score alto su texture generiche ma
         sovrapponendo il template gray i pixel non corrispondono.
@@ -491,23 +723,40 @@ class LineShapeMatcher:
         h, w = t.shape
         cx_t = (w - 1) / 2.0
         cy_t = (h - 1) / 2.0
-        M = cv2.getRotationMatrix2D((cx_t, cy_t), angle_deg, scale)
-        M[0, 2] += cx - cx_t
-        M[1, 2] += cy - cy_t
+
+        # Bounding box del template ruotato/scalato attorno a (cx, cy)
+        diag = int(np.ceil(np.hypot(w, h) * scale)) + 8
         H, W = scene_gray.shape
+        x0 = int(round(cx)) - diag // 2
+        y0 = int(round(cy)) - diag // 2
+        cx0 = max(0, x0); cy0 = max(0, y0)
+        cx1 = min(W, x0 + diag); cy1 = min(H, y0 + diag)
+        if cx1 - cx0 < 10 or cy1 - cy0 < 10:
+            return 0.0
+        scn_crop = scene_gray[cy0:cy1, cx0:cx1]
+        ch, cw = scn_crop.shape
+
+        M = cv2.getRotationMatrix2D((cx_t, cy_t), angle_deg, scale)
+        # Porta il centro del template a (cx - cx0, cy - cy0) del crop
+        M[0, 2] += (cx - cx0) - cx_t
+        M[1, 2] += (cy - cy0) - cy_t
         warped = cv2.warpAffine(
-            t, M, (W, H),
+            t, M, (cw, ch),
             flags=cv2.INTER_LINEAR, borderValue=0,
         )
-        mask = cv2.warpAffine(
-            np.full_like(t, 255), M, (W, H),
+        if self._train_mask is not None:
+            mask_src = self._train_mask
+        else:
+            mask_src = np.full_like(t, 255)
+        mask_w = cv2.warpAffine(
+            mask_src, M, (cw, ch),
             flags=cv2.INTER_NEAREST, borderValue=0,
         )
-        valid = mask > 0
+        valid = mask_w > 0
         if valid.sum() < 20:
             return 0.0
         tpl = warped[valid].astype(np.float32)
-        scn = scene_gray[valid].astype(np.float32)
+        scn = scn_crop[valid].astype(np.float32)
         tm = tpl - tpl.mean()
         sm = scn - scn.mean()
         denom = np.sqrt((tm * tm).sum() * (sm * sm).sum()) + 1e-9
@@ -523,11 +772,47 @@ class LineShapeMatcher:
         subpixel: bool = True,
         verify_ncc: bool = True,
         verify_threshold: float = 0.4,
+        ncc_skip_above: float = 1.01,  # disabilitato di default: NCC sempre
+        coarse_angle_factor: int = 2,
+        coarse_stride: int = 1,
+        scale_penalty: float = 0.0,
+        search_roi: tuple[int, int, int, int] | None = None,
+        pyramid_propagate: bool = False,  # off di default: meno duplicati
+        propagate_topk: int = 4,
+        refine_pose_joint: bool = False,
+        greediness: float = 0.0,
+        batch_top: bool = False,
     ) -> list[Match]:
+        """
+        scale_penalty: se > 0, riduce lo score per match a scala diversa da 1.0:
+          score_final = score_shape * max(0, 1 - scale_penalty * |scale - 1|)
+        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]))
@@ -564,27 +849,123 @@ class LineShapeMatcher:
         def _rescore(score: np.ndarray, bg: np.ndarray) -> np.ndarray:
             return np.maximum(0.0, (score - bg) / (1.0 - bg + 1e-6))
 
-        # Pruning varianti via top-level (parallelizzato)
+        # Coarse-to-fine angolare:
+        # 1) Raggruppa varianti per scala, ordina per angolo
+        # 2) Top-level: valuta solo 1 ogni coarse_angle_factor varianti
+        # 3) Espandi ai vicini nel full-res
+        variants_by_scale: dict[float, list[int]] = {}
+        for vi, var in enumerate(self.variants):
+            variants_by_scale.setdefault(var.scale, []).append(vi)
+
+        coarse_idx_list: list[int] = []  # varianti da valutare al top
+        neighbor_map: dict[int, list[int]] = {}  # vi_coarse -> indici vicini
+        cf = max(1, coarse_angle_factor)
+        for scale_key, vi_list in variants_by_scale.items():
+            vi_sorted = sorted(vi_list, key=lambda i: self.variants[i].angle_deg)
+            n = len(vi_sorted)
+            for i in range(0, n, cf):
+                vi_c = vi_sorted[i]
+                coarse_idx_list.append(vi_c)
+                # Vicini: ±cf/2 attorno a i (stessa scala)
+                half = cf // 2
+                start = max(0, i - half)
+                end = min(n, i + half + 1)
+                neighbor_map[vi_c] = vi_sorted[start:end]
+
+        # Pruning varianti via top-level (parallelizzato).
+        # coarse_stride > 1: 1 pixel ogni stride (~stride^2 speed-up).
+        # pyramid_propagate=True: top-K picchi per restringere full-res.
+        # greediness > 0: kernel greedy con early-exit (alternativo a rescore).
+        cs = max(1, int(coarse_stride))
+        peaks_by_vi: dict[int, list[tuple[int, int, float]]] = {}
+        use_greedy_top = greediness > 0.0
+
         def _top_score(vi: int) -> tuple[int, float]:
             var = self.variants[vi]
             lvl = var.levels[min(top, len(var.levels) - 1)]
-            score = _jit_score_bitmap(
-                spread_top, lvl.dx, lvl.dy, lvl.bin, bit_active_top,
-            )
-            score = _rescore(score, bg_cache_top[var.scale])
-            return vi, float(score.max()) if score.size else -1.0
+            if use_greedy_top:
+                # Greedy non supporta stride né rescore bg
+                score = _jit_score_bitmap_greedy(
+                    spread_top, lvl.dx, lvl.dy, lvl.bin, bit_active_top,
+                    top_thresh, greediness,
+                )
+            else:
+                score = _jit_score_bitmap_rescored(
+                    spread_top, lvl.dx, lvl.dy, lvl.bin, bit_active_top,
+                    bg_cache_top[var.scale], stride=cs,
+                )
+            if score.size == 0:
+                return vi, -1.0
+            best = float(score.max())
+            if pyramid_propagate and best > 0:
+                flat = score.ravel()
+                k = min(propagate_topk, flat.size)
+                idx = np.argpartition(-flat, k - 1)[:k]
+                peaks: list[tuple[int, int, float]] = []
+                for i in idx:
+                    s = float(flat[i])
+                    if s < top_thresh * 0.7:
+                        continue
+                    yt, xt = int(i // score.shape[1]), int(i % score.shape[1])
+                    peaks.append((xt, yt, s))
+                peaks_by_vi[vi] = peaks
+            return vi, best
 
-        kept_variants: list[tuple[int, float]] = []
-        if self.n_threads > 1:
-            with ThreadPoolExecutor(max_workers=self.n_threads) as ex:
-                for vi, best in ex.map(_top_score, range(len(self.variants))):
-                    if best >= top_thresh:
-                        kept_variants.append((vi, best))
-        else:
-            for vi in range(len(self.variants)):
-                vi2, best = _top_score(vi)
+        kept_coarse: list[tuple[int, float]] = []
+        all_top_scores: list[tuple[int, float]] = []
+        # batch_top: usa kernel batch single-call con prange-esterno su
+        # varianti. Vince su threadpool quando n_vars >> n_threads e quando
+        # H*W top e' piccolo (overhead chiamate JIT > costo kernel).
+        if (batch_top and HAS_NUMBA and len(coarse_idx_list) > 4):
+            dx_l = []; dy_l = []; bn_l = []; vs_l = []
+            for vi in coarse_idx_list:
+                var = self.variants[vi]
+                lvl = var.levels[min(top, len(var.levels) - 1)]
+                dx_l.append(lvl.dx); dy_l.append(lvl.dy); bn_l.append(lvl.bin)
+                vs_l.append(var.scale)
+            scores_arr = _jit_top_max_per_variant(
+                spread_top, dx_l, dy_l, bn_l, bg_cache_top, vs_l,
+                bit_active_top,
+            )
+            for vi, best in zip(coarse_idx_list, scores_arr.tolist()):
+                all_top_scores.append((vi, best))
                 if best >= top_thresh:
-                    kept_variants.append((vi2, best))
+                    kept_coarse.append((vi, best))
+        elif self.n_threads > 1 and len(coarse_idx_list) > 1:
+            with ThreadPoolExecutor(max_workers=self.n_threads) as ex:
+                for vi, best in ex.map(_top_score, coarse_idx_list):
+                    all_top_scores.append((vi, best))
+                    if best >= top_thresh:
+                        kept_coarse.append((vi, best))
+        else:
+            for vi in coarse_idx_list:
+                vi2, best = _top_score(vi)
+                all_top_scores.append((vi2, best))
+                if best >= top_thresh:
+                    kept_coarse.append((vi2, best))
+
+        # Fallback adattivo: se il rescore background ha abbattuto tutti
+        # gli score sotto top_thresh (scene texturate pesanti), ripesca
+        # le varianti migliori al top level per dare comunque una chance
+        # alla fase full-res invece di ritornare 0 match.
+        if not kept_coarse and all_top_scores:
+            all_top_scores.sort(key=lambda t: -t[1])
+            n_keep = max(4, len(all_top_scores) // 10)
+            # Limita a varianti con score top > 0 (non completamente a zero)
+            kept_coarse = [(vi, s) for vi, s in all_top_scores[:n_keep] if s > 0]
+
+        # Espandi ogni coarse promosso con i suoi vicini (stessa scala,
+        # angoli intermedi non valutati al top)
+        expanded: set[int] = set()
+        score_by_vi: dict[int, float] = {}
+        for vi_c, s_top in kept_coarse:
+            for vi_n in neighbor_map.get(vi_c, [vi_c]):
+                expanded.add(vi_n)
+                # Usa lo score del coarse come stima per il sort successivo
+                score_by_vi[vi_n] = max(score_by_vi.get(vi_n, 0.0), s_top)
+        kept_variants: list[tuple[int, float]] = [
+            (vi, score_by_vi[vi]) for vi in expanded
+        ]
 
         if not kept_variants:
             return []
@@ -606,14 +987,48 @@ class LineShapeMatcher:
         for sc in unique_scales:
             bg_cache_full[sc] = _bg_for_scale(density_full, sc, 1)
 
+        # Margine in full-res attorno ad ogni peak top: copre incertezza
+        # downsampling (sf_top px) + spread_radius + slack per NMS.
+        propagate_margin = sf_top + self.spread_radius + max(8, nms_radius // 2)
+        H_full, W_full = spread0.shape
+
         def _full_score(vi: int) -> tuple[int, np.ndarray]:
             var = self.variants[vi]
             lvl0 = var.levels[0]
-            score = _jit_score_bitmap(
-                spread0, lvl0.dx, lvl0.dy, lvl0.bin, bit_active_full,
-            )
-            score = _rescore(score, bg_cache_full[var.scale])
-            return vi, score
+            if not pyramid_propagate or vi not in peaks_by_vi or not peaks_by_vi[vi]:
+                # Path legacy: scansiona intera scena
+                return vi, _jit_score_bitmap_rescored(
+                    spread0, lvl0.dx, lvl0.dy, lvl0.bin, bit_active_full,
+                    bg_cache_full[var.scale],
+                )
+            # Path piramide propagata: valuta solo crop locali attorno
+            # alle posizioni dei picchi top-level (riproiettati a full-res).
+            score_full = np.zeros((H_full, W_full), dtype=np.float32)
+            mark = np.zeros((H_full, W_full), dtype=bool)
+            bg = bg_cache_full[var.scale]
+            for xt, yt, _s in peaks_by_vi[vi]:
+                cx0 = xt * sf_top
+                cy0 = yt * sf_top
+                x_lo = max(0, cx0 - propagate_margin)
+                x_hi = min(W_full, cx0 + propagate_margin + 1)
+                y_lo = max(0, cy0 - propagate_margin)
+                y_hi = min(H_full, cy0 + propagate_margin + 1)
+                if x_hi <= x_lo or y_hi <= y_lo:
+                    continue
+                if mark[y_lo:y_hi, x_lo:x_hi].all():
+                    continue
+                # Crop spread + bg, valuta kernel sul crop
+                spread_crop = np.ascontiguousarray(spread0[y_lo:y_hi, x_lo:x_hi])
+                bg_crop = np.ascontiguousarray(bg[y_lo:y_hi, x_lo:x_hi])
+                score_crop = _jit_score_bitmap_rescored(
+                    spread_crop, lvl0.dx, lvl0.dy, lvl0.bin,
+                    bit_active_full, bg_crop,
+                )
+                score_full[y_lo:y_hi, x_lo:x_hi] = np.maximum(
+                    score_full[y_lo:y_hi, x_lo:x_hi], score_crop,
+                )
+                mark[y_lo:y_hi, x_lo:x_hi] = True
+            return vi, score_full
 
         candidates_per_var: list[tuple[int, np.ndarray]] = []
         raw: list[tuple[float, int, int, int]] = []
@@ -624,14 +1039,24 @@ class LineShapeMatcher:
         else:
             results = [_full_score(vi) for vi in var_indices]
 
+        def _scale_factor(s: float) -> float:
+            """Penalità moltiplicativa per scala diversa da 1.0."""
+            if scale_penalty > 0.0 and s != 1.0:
+                return max(0.0, 1.0 - scale_penalty * abs(s - 1.0))
+            return 1.0
+
         for vi, score in results:
-            ys, xs = np.where(score >= min_score)
+            pen = _scale_factor(self.variants[vi].scale)
+            # Ordinare/sogliare su score penalizzato: un match a scala 1.5 con
+            # score 0.8 e penalty=0.3 effettivamente vale 0.56, non 0.8.
+            score_for_sort = score if pen == 1.0 else score * pen
+            ys, xs = np.where(score_for_sort >= min_score)
             if len(ys) == 0:
                 continue
-            vals = score[ys, xs]
+            vals = score_for_sort[ys, xs]
             K = min(len(vals), max_matches * 5)
             ord_idx = np.argpartition(-vals, K - 1)[:K]
-            candidates_per_var.append((vi, score))
+            candidates_per_var.append((vi, score))  # score_map originale
             for i in ord_idx:
                 raw.append((float(vals[i]), int(xs[i]), int(ys[i]), vi))
 
@@ -641,52 +1066,94 @@ class LineShapeMatcher:
         score_maps = dict(candidates_per_var)
 
         # NMS + subpixel + refinement angolare
-        # Mask template per refinement (non disponibile qui: usa full)
+        # Usa mask salvata in train() per coerenza (se ROI poligonale).
         h, w = self.template_gray.shape if self.template_gray is not None else (0, 0)
-        mask_full = np.full((h, w), 255, dtype=np.uint8)
+        mask_full = (
+            self._train_mask if self._train_mask is not None
+            else np.full((h, w), 255, dtype=np.uint8)
+        )
+        # Plateau radius adattivo al template (evita plateau troppo ampi su
+        # template piccoli: 8% del lato minimo, clampato [3, 10]).
+        plateau_r = max(3, min(10, int(min(self.template_size) * 0.08)))
 
-        # Pre-NMS rapido su raw (solo subpixel, no refine/verify): riduce
-        # i candidati a ~max_matches*3 prima di operazioni costose (refine,
-        # verify) che erano chiamate per ogni raw causando lentezze 100x.
+        # Pre-NMS rapido su raw con coordinate intere (nms_radius ≥ 8,
+        # la precisione sub-pixel non cambia la decisione di reject).
+        # Subpixel viene calcolato DOPO il pre-NMS solo sui ~pre_cap
+        # preliminary sopravvissuti: prima era chiamato su ogni raw (~58k
+        # chiamate su clip_preciso) anche se la maggior parte veniva poi
+        # scartata dalla NMS, sprecando la parte più costosa del loop.
         r2 = nms_radius * nms_radius
-        preliminary: list[tuple[float, float, float, int]] = []
         pre_cap = max(max_matches * 3, max_matches + 10)
+        preliminary_int: list[tuple[float, int, int, int]] = []
         for score, xi, yi, vi in raw:
-            if subpixel and vi in score_maps:
-                cx_f, cy_f = self._subpixel_peak(score_maps[vi], xi, yi)
-            else:
-                cx_f, cy_f = float(xi), float(yi)
-            if any((k[1] - cx_f) ** 2 + (k[2] - cy_f) ** 2 < r2
-                   for k in preliminary):
+            if any((k[1] - xi) ** 2 + (k[2] - yi) ** 2 < r2
+                   for k in preliminary_int):
                 continue
-            preliminary.append((score, cx_f, cy_f, vi))
-            if len(preliminary) >= pre_cap:
+            preliminary_int.append((score, xi, yi, vi))
+            if len(preliminary_int) >= pre_cap:
                 break
 
-        # Ora refine + verify solo sui candidati pre-NMS
+        # Subpixel + refine + verify solo sui candidati pre-NMS (max pre_cap)
         kept: list[Match] = []
         tw, th = self.template_size
-        for score, cx_f, cy_f, vi in preliminary:
+        for score, xi, yi, vi in preliminary_int:
+            if subpixel and vi in score_maps:
+                cx_f, cy_f = self._subpixel_peak(
+                    score_maps[vi], xi, yi, plateau_radius=plateau_r,
+                )
+            else:
+                cx_f, cy_f = float(xi), float(yi)
             var = self.variants[vi]
             ang_f = var.angle_deg
             score_f = score
-            if refine_angle and self.template_gray is not None:
+            if refine_pose_joint and self.template_gray is not None:
+                ang_f, score_f, cx_f, cy_f = self._refine_pose_joint(
+                    spread0, self.template_gray, cx_f, cy_f,
+                    var.angle_deg, var.scale, mask_full,
+                )
+            elif refine_angle and self.template_gray is not None:
                 ang_f, score_f, cx_f, cy_f = self._refine_angle(
                     spread0, bit_active_full, self.template_gray, cx_f, cy_f,
                     var.angle_deg, var.scale, mask_full,
-                    search_radius=self.angle_step_deg / 2.0,
+                    search_radius=self._effective_angle_step() / 2.0,
                     original_score=score,
                 )
-            if verify_ncc:
+            # 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).
+            # Quando NCC viene calcolato, lo score finale e' la MEDIA tra
+            # shape-score e NCC: rende lo score piu discriminante per
+            # 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)
                 if ncc < verify_threshold:
                     continue
+                score_f = (float(score_f) + max(0.0, ncc)) * 0.5
 
+            # 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:
+                score_f = float(score_f) * max(
+                    0.0, 1.0 - scale_penalty * abs(var.scale - 1.0)
+                )
+            # NMS post-refine: refine puo spostare il match di nms_radius;
+            # ricontrollo overlap su match gia accettati per evitare
+            # duplicati (stesso oggetto trovato da varianti angolari diverse).
+            dup = False
+            for k in kept:
+                if (k.cx - cx_out) ** 2 + (k.cy - cy_out) ** 2 < r2:
+                    dup = True
+                    break
+            if dup:
+                continue
             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,

pm2d/web/server.py

@@ -9,10 +9,12 @@ Endpoint:
 """
 from __future__ import annotations
 
+import hashlib
 import os
 import tempfile
 import time
 import uuid
+from collections import OrderedDict
 from pathlib import Path
 
 import cv2
@@ -61,6 +63,39 @@ CACHE_DIR.mkdir(exist_ok=True)
 # Cache in-memory (soft, ricaricata da disco se mancante)
 _IMG_CACHE: dict[str, np.ndarray] = {}
 
+# Cache matcher addestrati: (roi_hash, params_hash) -> LineShapeMatcher
+# LRU con capacità limitata
+_MATCHER_CACHE: OrderedDict = OrderedDict()
+_MATCHER_CACHE_SIZE = 8
+
+
+def _matcher_cache_key(roi: np.ndarray, tech: dict) -> str:
+    h = hashlib.md5()
+    h.update(roi.tobytes())
+    # Solo parametri che influenzano il training
+    relevant = ("num_features", "weak_grad", "strong_grad",
+                "angle_min", "angle_max", "angle_step",
+                "scale_min", "scale_max", "scale_step",
+                "spread_radius", "pyramid_levels")
+    for k in relevant:
+        h.update(f"{k}={tech.get(k)}".encode())
+    h.update(f"shape={roi.shape}".encode())
+    return h.hexdigest()
+
+
+def _cache_get_matcher(key: str):
+    m = _MATCHER_CACHE.get(key)
+    if m is not None:
+        _MATCHER_CACHE.move_to_end(key)  # LRU touch
+    return m
+
+
+def _cache_put_matcher(key: str, matcher) -> None:
+    _MATCHER_CACHE[key] = matcher
+    _MATCHER_CACHE.move_to_end(key)
+    while len(_MATCHER_CACHE) > _MATCHER_CACHE_SIZE:
+        _MATCHER_CACHE.popitem(last=False)
+
 
 def _store_image(img: np.ndarray) -> str:
     iid = uuid.uuid4().hex[:12]
@@ -229,6 +264,7 @@ class SimpleMatchParams(BaseModel):
     scala: str = "fissa"              # chiave SCALE_PRESETS
     precisione: str = "normale"       # chiave PRECISION_ANGLE_STEP
     filtro_fp: str = "medio"          # chiave FILTRO_FP_MAP
+    penalita_scala: float = 0.0       # 0 = score shape invariante, >0 = penalizza scala != 1
     min_score: float = 0.65
     max_matches: int = 25
 
@@ -281,6 +317,7 @@ def _simple_to_technical(
         "max_matches": p.max_matches,
         "nms_radius": 0,
         "verify_threshold": FILTRO_FP_MAP.get(p.filtro_fp, 0.35),
+        "scale_penalty": p.penalita_scala,
     }
 
 
@@ -292,6 +329,49 @@ def index():
     return HTMLResponse(html_path.read_text(encoding="utf-8"))
 
 
+@app.post("/upload_to_folder")
+async def upload_to_folder(file: UploadFile = File(...)):
+    """Salva file caricato nella cartella IMAGES_DIR. Ritorna lista aggiornata."""
+    if not IMAGES_DIR.is_dir():
+        raise HTTPException(500, f"IMAGES_DIR non esiste: {IMAGES_DIR}")
+    # Sanitizza nome file (no traversal)
+    name = Path(file.filename or "upload.png").name
+    if not name:
+        raise HTTPException(400, "nome file vuoto")
+    ext = Path(name).suffix.lower()
+    allowed = {".png", ".jpg", ".jpeg", ".bmp", ".tif", ".tiff"}
+    if ext not in allowed:
+        raise HTTPException(400, f"estensione non supportata: {ext}")
+    # Leggi contenuto e valida come immagine
+    data = await file.read()
+    arr = np.frombuffer(data, dtype=np.uint8)
+    img = cv2.imdecode(arr, cv2.IMREAD_COLOR)
+    if img is None:
+        raise HTTPException(400, "file non è un'immagine valida")
+    # Evita overwrite: se esiste, aggiungi suffisso numerico
+    target = IMAGES_DIR / name
+    if target.exists():
+        stem = target.stem; suffix = target.suffix
+        i = 1
+        while True:
+            alt = IMAGES_DIR / f"{stem}_{i}{suffix}"
+            if not alt.exists():
+                target = alt; break
+            i += 1
+    # Scrivi su disco
+    with open(target, "wb") as f:
+        f.write(data)
+    # Ritorna lista aggiornata
+    return {
+        "saved_as": target.name,
+        "dir": str(IMAGES_DIR),
+        "files": sorted(
+            p.name for p in IMAGES_DIR.iterdir()
+            if p.is_file() and p.suffix.lower() in allowed
+        ),
+    }
+
+
 @app.get("/folder_image/{filename}")
 def folder_image(filename: str, w: int = 120):
     """Serve thumbnail PNG dell'immagine IMAGES_DIR (scalata a width w)."""
@@ -375,17 +455,33 @@ def match(p: MatchParams):
     h = max(1, min(h, model.shape[0] - y))
     roi_img = model[y:y + h, x:x + w]
 
-    m = LineShapeMatcher(
-        num_features=p.num_features,
-        weak_grad=p.weak_grad, strong_grad=p.strong_grad,
-        angle_range_deg=(p.angle_min, p.angle_max),
-        angle_step_deg=p.angle_step,
-        scale_range=(p.scale_min, p.scale_max),
-        scale_step=p.scale_step,
-        spread_radius=p.spread_radius,
-        pyramid_levels=p.pyramid_levels,
-    )
-    t0 = time.time(); n = m.train(roi_img); t_train = time.time() - t0
+    tech_for_cache = {
+        "num_features": p.num_features,
+        "weak_grad": p.weak_grad, "strong_grad": p.strong_grad,
+        "angle_min": p.angle_min, "angle_max": p.angle_max,
+        "angle_step": p.angle_step,
+        "scale_min": p.scale_min, "scale_max": p.scale_max,
+        "scale_step": p.scale_step,
+        "spread_radius": p.spread_radius,
+        "pyramid_levels": p.pyramid_levels,
+    }
+    key = _matcher_cache_key(roi_img, tech_for_cache)
+    m = _cache_get_matcher(key)
+    if m is None:
+        m = LineShapeMatcher(
+            num_features=p.num_features,
+            weak_grad=p.weak_grad, strong_grad=p.strong_grad,
+            angle_range_deg=(p.angle_min, p.angle_max),
+            angle_step_deg=p.angle_step,
+            scale_range=(p.scale_min, p.scale_max),
+            scale_step=p.scale_step,
+            spread_radius=p.spread_radius,
+            pyramid_levels=p.pyramid_levels,
+        )
+        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 = p.nms_radius if p.nms_radius > 0 else None
     t0 = time.time()
     matches = m.find(
@@ -429,22 +525,29 @@ def match_simple(p: SimpleMatchParams):
 
     tech = _simple_to_technical(p, 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"],
-    )
-    t0 = time.time(); n = m.train(roi_img); t_train = time.time() - t0
+    key = _matcher_cache_key(roi_img, tech)
+    m = _cache_get_matcher(key)
+    if m is None:
+        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"],
+        )
+        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
     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),
     )
     t_find = time.time() - t0
 

pm2d/web/static/app.js

@@ -48,6 +48,8 @@ function readUserParams() {
     scala: document.getElementById("p-scala").value,
     precisione: document.getElementById("p-precisione").value,
     filtro_fp: document.getElementById("p-filtro-fp").value,
+    penalita_scala: parseFloat(
+      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),
   };
@@ -80,6 +82,21 @@ async function fetchImagesList() {
   return await r.json();
 }
 
+async function uploadToFolder(file) {
+  const fd = new FormData();
+  fd.append("file", file);
+  const r = await fetch("/upload_to_folder", { method: "POST", body: fd });
+  if (!r.ok) throw new Error(await r.text());
+  return await r.json();
+}
+
+async function refreshPickers() {
+  const {files, dir} = await fetchImagesList();
+  buildThumbPicker("picker-model", files, onSelectModel);
+  buildThumbPicker("picker-scene", files, onSelectScene);
+  return {files, dir};
+}
+
 function buildThumbPicker(pickerId, files, onSelect) {
   const picker = document.getElementById(pickerId);
   const current = picker.querySelector(".picker-current");
@@ -349,14 +366,28 @@ window.addEventListener("DOMContentLoaded", async () => {
   buildAdvancedForm();
   setupROI();
   // Popola picker immagini da IMAGES_DIR (con thumbnail)
-  const {files, dir} = await fetchImagesList();
-  buildThumbPicker("picker-model", files, onSelectModel);
-  buildThumbPicker("picker-scene", files, onSelectScene);
+  const {files, dir} = await refreshPickers();
   if (files.length === 0) {
-    setStatus(`Nessuna immagine in ${dir} (configura IMAGES_DIR in .env)`);
+    setStatus(`Nessuna immagine in ${dir} (carica file o configura IMAGES_DIR)`);
   } else {
-    setStatus(`${files.length} immagini disponibili in ${dir}`);
+    setStatus(`${files.length} immagini in ${dir}`);
   }
+
+  // Upload file nella folder
+  const upEl = document.getElementById("file-upload");
+  upEl.addEventListener("change", async (e) => {
+    const f = e.target.files[0];
+    if (!f) return;
+    setStatus(`Caricamento ${f.name} nella cartella...`);
+    try {
+      const res = await uploadToFolder(f);
+      await refreshPickers();
+      setStatus(`Salvato come ${res.saved_as} (${res.files.length} file totali)`);
+    } catch (err) {
+      setStatus(`Errore upload: ${err.message}`);
+    }
+    e.target.value = "";  // consente re-upload stesso file
+  });
   document.getElementById("btn-match").addEventListener("click", doMatch);
   const slider = document.getElementById("p-min-score");
   slider.addEventListener("input", (e) => {

pm2d/web/static/index.html

@@ -26,6 +26,10 @@
       <div class="picker-list"></div>
     </div>
     <button class="btn btn-go" id="btn-match">▶ MATCH</button>
+    <label class="btn" title="Carica nuovo file nella cartella immagini">
+      ⬆ Carica file
+      <input type="file" id="file-upload" accept="image/*" hidden>
+    </label>
     <span id="status">Seleziona modello, disegna ROI, seleziona scena</span>
   </div>
 </header>
@@ -101,6 +105,18 @@
       </select>
     </div>
 
+    <div class="field">
+      <label>Peso dimensione nel score
+        <span class="hint">(penalizza scala ≠ 1.0)</span>
+      </label>
+      <select id="p-penalita-scala">
+        <option value="0" selected>Nessuno (score shape puro)</option>
+        <option value="0.3">Leggero (−30% max)</option>
+        <option value="0.5">Medio (−50% max)</option>
+        <option value="0.8">Forte (−80% max)</option>
+      </select>
+    </div>
+
     <div class="field">
       <label>Score minimo <span id="v-score">0.65</span>
         <span class="hint">(più basso = più match anche incerti)</span>