Chess Vision backend (digitization + move prediction)

.gitattributes

@@ -0,0 +1 @@
+*.onnx filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,14 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+
+# Stockfish binary (installed via apt in Docker / downloaded locally)
+stockfish/stockfish
+stockfish/*.tar
+
+# Local sample images / scratch
+samples/
+/tmp/
+
+# NOTE: models_onnx/ IS committed (the API needs the ONNX weights).

Dockerfile

@@ -0,0 +1,21 @@
+# Hugging Face Space (Docker SDK) listens on 7860.
+FROM python:3.12-slim
+
+# Stockfish (apt build = portable across CPUs) + opencv runtime libs.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        stockfish libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY app ./app
+COPY models_onnx ./models_onnx
+
+ENV STOCKFISH_PATH=/usr/games/stockfish \
+    MODELS_DIR=/app/models_onnx
+
+EXPOSE 7860
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,55 @@
+---
+title: Chess Vision Backend
+emoji: ♟️
+colorFrom: indigo
+colorTo: gray
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# ♟️ Chess Vision — Backend (API)
+
+FastAPI service for my MSc project: **chess board digitization** + **human-like
+move prediction**. Upload a board image to get its FEN, then ask for the moves a
+human would likely play (CNN trained on Lichess games) combined with **Stockfish**.
+
+Models are served as quantized **ONNX** (the original ~444 MB of PyTorch weights →
+~47 MB ONNX), so the image is small and CPU inference is fast.
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET`  | `/health` | Liveness probe |
+| `POST` | `/digitize` | multipart image → FEN board placement |
+| `POST` | `/predict-move` | `{ "fen": "...", "top_n": 3 }` → CNN / Stockfish / hybrid moves |
+| `GET`  | `/docs` | Swagger UI |
+
+```bash
+curl -X POST .../predict-move -H 'Content-Type: application/json' \
+  -d '{"fen":"rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1","top_n":3}'
+# -> {"cnn":["e7e5","g8f6","d7d5"], "stockfish":["e7e5","c7c5","e7e6"], "hybrid":[...]}
+```
+
+## How it works
+- **Digitization** (`app/digitize.py`): fixed crop → Canny → Hough grid (exact MSc
+  pipeline) → 64 square crops → ONNX MobileNetV2 piece classifier → FEN.
+- **Move prediction** (`app/predict.py`): board → 12×8×8 tensor → a piece-type CNN +
+  six destination-square CNNs → legal human-like moves; black is mirrored; Stockfish
+  adds engine moves and a non-blundering hybrid.
+
+## Run locally
+```bash
+python3.12 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+# Stockfish: apt install stockfish (Linux) and set STOCKFISH_PATH, or omit for CNN-only
+uvicorn app.main:app --reload --port 7860
+```
+
+## Models
+`models_onnx/` holds the quantized ONNX weights (digitizer + piece + 6 square
+classifiers). Regenerate from the original `.pth` with `convert_to_onnx.py`.
+
+> The demo backend runs on a free Hugging Face Space that sleeps after inactivity;
+> the first request after that triggers a short cold start.

app/chess_models.py

@@ -0,0 +1,83 @@
+"""Model architectures extracted from the Master's project notebooks.
+
+Used to load the trained .pth weights and export them to ONNX. The backend
+serves the ONNX models, so torch is only needed at conversion time.
+
+  - PieceImageClassifier : MobileNetV2 -> 12 classes (square -> piece, digitization)
+  - PieceClassifier      : CNN, 12x8x8 -> 6  (which piece type to move)
+  - SquareClassifier     : CNN, 12x8x8 -> 64 (destination square; one per piece type)
+"""
+
+from __future__ import annotations
+
+import torch.nn as nn
+import torchvision.models as models
+
+
+class PieceImageClassifier(nn.Module):
+    """Digitization: classify a single board square crop into one of 12 pieces."""
+
+    def __init__(self):
+        super().__init__()
+        # weights=None: we load our own trained state_dict, no ImageNet download.
+        self.model = models.mobilenet_v2(weights=None)
+        self.model.classifier = nn.Sequential(
+            nn.AdaptiveAvgPool2d(1),
+            nn.Flatten(),
+            nn.Linear(1280, 512),
+            nn.ReLU(),
+            nn.Linear(512, 12),
+        )
+
+    def forward(self, x):
+        return self.model.classifier(self.model.features(x))
+
+
+def _conv_block() -> nn.Sequential:
+    return nn.Sequential(
+        nn.Conv2d(12, 32, 3, padding=1), nn.BatchNorm2d(32), nn.ReLU(),
+        nn.Conv2d(32, 64, 3, padding=1), nn.BatchNorm2d(64), nn.ReLU(),
+        nn.MaxPool2d(2, 2),
+        nn.Conv2d(64, 128, 3, padding=1), nn.BatchNorm2d(128), nn.ReLU(),
+        nn.Conv2d(128, 256, 3, padding=1), nn.BatchNorm2d(256), nn.ReLU(),
+        nn.MaxPool2d(2, 2),
+        nn.Conv2d(256, 512, 3, padding=1), nn.BatchNorm2d(512), nn.ReLU(),
+        nn.Conv2d(512, 512, 3, padding=1), nn.BatchNorm2d(512), nn.ReLU(),
+        nn.MaxPool2d(2, 2),
+    )
+
+
+class PieceClassifier(nn.Module):
+    """Move prediction stage 1: which piece type (P,N,B,R,Q,K) is likely to move."""
+
+    def __init__(self):
+        super().__init__()
+        self.conv_layers = _conv_block()
+        self.fc_layers = nn.Sequential(
+            nn.Dropout(0.25), nn.Linear(512, 1024), nn.BatchNorm1d(1024), nn.ReLU(),
+            nn.Dropout(0.25), nn.Linear(1024, 512), nn.BatchNorm1d(512), nn.ReLU(),
+            nn.Linear(512, 6),
+        )
+
+    def forward(self, x):
+        x = self.conv_layers(x)
+        x = x.view(x.size(0), -1)
+        return self.fc_layers(x)
+
+
+class SquareClassifier(nn.Module):
+    """Move prediction stage 2: destination square (0-63) for a given piece type."""
+
+    def __init__(self):
+        super().__init__()
+        self.conv_layers = _conv_block()
+        self.fc_layers = nn.Sequential(
+            nn.Dropout(0.25), nn.Linear(512, 1024), nn.BatchNorm1d(1024), nn.ReLU(),
+            nn.Dropout(0.25), nn.Linear(1024, 512), nn.BatchNorm1d(512), nn.ReLU(),
+            nn.Linear(512, 64),
+        )
+
+    def forward(self, x):
+        x = self.conv_layers(x)
+        x = x.view(x.size(0), -1)
+        return self.fc_layers(x)

app/digitize.py

@@ -0,0 +1,120 @@
+"""Image -> FEN digitization (the exact Preprocess.ipynb pipeline).
+
+Runs on any uploaded image (no corner marking): fixed crop, Canny, Hough,
+group/filter lines, remove the spurious 3rd-from-bottom row, crop each square
+(bbox + 90px), classify with the ONNX piece model, and detect empties by
+model-confidence + edge density.
+"""
+from __future__ import annotations
+
+import cv2 as cv
+import numpy as np
+
+IDX2SYM = {0:"P",1:"N",2:"B",3:"R",4:"Q",5:"K",6:"p",7:"n",8:"b",9:"r",10:"q",11:"k"}
+_MEAN = np.array([0.485, 0.456, 0.406], np.float32)
+_STD = np.array([0.229, 0.224, 0.225], np.float32)
+
+
+# ── exact Preprocess.ipynb grid ──────────────────────────────────────────────
+def _crop_image(im):
+    cx, cy = im.shape[1] // 2, im.shape[0] // 2
+    return im[cy - 520:cy + 450, cx - 550:cx + 550]
+
+def _group(lines):
+    g = []
+    for l in lines:
+        rho, theta = l[0]
+        if not any(abs(rho - a[0][0]) < 30 and abs(theta - a[0][1]) < np.pi / 18 for a in g):
+            g.append(l)
+    return g
+
+def _filter(g):
+    mr = None
+    for l in g:
+        rho, theta = l[0]
+        if 1 < theta < 3 and (mr is None or rho < mr):
+            mr = rho
+    return [l for l in g if l[0][0] != mr]
+
+def _intersections(board_lines):
+    lp = []
+    for l in board_lines:
+        rho, theta = l[0]; a, b = np.cos(theta), np.sin(theta); x0, y0 = a * rho, b * rho
+        lp.append([(int(x0 + 1e4 * -b), int(y0 + 1e4 * a)),
+                   (int(x0 - 1e4 * -b), int(y0 - 1e4 * a)), theta])
+    rows = []
+    for i in range(len(lp)):
+        pts = []
+        for j in range(len(lp)):
+            (x1, y1), (x2, y2) = lp[i][0], lp[i][1]
+            (x3, y3), (x4, y4) = lp[j][0], lp[j][1]
+            det = (x1 - x2) * (y3 - y4) - (y1 - y2) * (x3 - x4)
+            if det:
+                ix = int(((x1 * y2 - y1 * x2) * (x3 - x4) - (x1 - x2) * (x3 * y4 - y3 * x4)) / det)
+                iy = int(((x1 * y2 - y1 * x2) * (y3 - y4) - (y1 - y2) * (x3 * y4 - y3 * x4)) / det)
+                if 0 <= ix <= 1920 and 0 <= iy <= 1080 and 1 < lp[i][2] < 3:
+                    pts.append((ix, iy))
+        if pts:
+            pts.sort(key=lambda p: p[0]); rows.append(pts)
+    rows.sort(key=lambda p: p[0][0])
+    return rows
+
+def _squares(rows):
+    casas = []
+    for i in range(len(rows) - 1):
+        for j in range(len(rows[i]) - 1):
+            casas.append([rows[i][j], rows[i][j + 1], rows[i + 1][j], rows[i + 1][j + 1]])
+    return casas
+
+
+def _preprocess(bgr):
+    rgb = cv.cvtColor(cv.resize(bgr, (224, 224)), cv.COLOR_BGR2RGB).astype(np.float32) / 255.0
+    return ((rgb - _MEAN) / _STD).transpose(2, 0, 1)[None]
+
+
+def _grid_to_fen(grid) -> str:
+    out = []
+    for row in grid:
+        s, e = "", 0
+        for cell in row:
+            if cell == ".":
+                e += 1
+            else:
+                if e:
+                    s += str(e); e = 0
+                s += cell
+        if e:
+            s += str(e)
+        out.append(s)
+    return "/".join(out)
+
+
+def image_to_fen(bgr, session) -> str | None:
+    """Full board state (piece-placement FEN) from a board image, or None if the
+    64-square grid couldn't be detected."""
+    im = _crop_image(bgr)
+    lines = cv.HoughLines(cv.Canny(im, 100, 150, apertureSize=3), 1, np.pi / 180, 160)
+    if lines is None:
+        return None
+    rows = _intersections(_filter(_group(lines)))
+    if len(rows) >= 3:  # drop spurious 3rd-from-bottom horizontal line
+        by_y = sorted(rows, key=lambda r: np.mean([p[1] for p in r]), reverse=True)
+        rows = [r for r in rows if r is not by_y[2]]
+    casas = _squares(rows)
+    if len(casas) != 64:
+        return None
+
+    syms = []
+    for p in casas:
+        xs = [q[0] for q in p]; ys = [q[1] for q in p]
+        crop = im[max(0, min(ys) - 90):max(ys), min(xs):max(xs)]
+        if crop.size == 0:
+            syms.append("."); continue
+        out = session.run(None, {"input": _preprocess(crop)})[0].flatten()
+        sm = np.exp(out) / np.exp(out).sum()
+        edge = cv.Canny(cv.cvtColor(crop, cv.COLOR_BGR2GRAY), 100, 150).mean() / 255
+        occupied = sm.max() >= 0.8 or edge >= 0.03      # confidence + edge density
+        syms.append(IDX2SYM[int(sm.argmax())] if occupied else ".")
+
+    grid = np.flipud(np.array(syms, object).reshape(8, 8))  # flipUD orientation
+    return _grid_to_fen(grid)

app/main.py

@@ -0,0 +1,76 @@
+"""Chess Vision API — board digitization + human-like move prediction.
+
+  GET  /health
+  POST /digitize      multipart image -> FEN (board placement)
+  POST /predict-move  { fen, top_n } -> CNN / Stockfish / hybrid moves
+  GET  /docs          Swagger UI
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import cv2 as cv
+import numpy as np
+import onnxruntime as ort
+from fastapi import FastAPI, File, HTTPException, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+
+from .digitize import image_to_fen
+from .predict import MovePredictor
+
+ROOT = Path(__file__).parent.parent
+MODELS_DIR = os.environ.get("MODELS_DIR", str(ROOT / "models_onnx"))
+STOCKFISH_PATH = os.environ.get("STOCKFISH_PATH", str(ROOT / "stockfish" / "stockfish"))
+
+app = FastAPI(
+    title="Chess Vision API",
+    description="Digitize a chess board photo to a FEN, then predict human-like moves "
+                "(CNN trained on Lichess games) combined with Stockfish.",
+    version="0.1.0",
+)
+app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])
+
+# loaded once at startup
+_digitizer = ort.InferenceSession(str(Path(MODELS_DIR) / "digitizer3d.fp32.onnx"),
+                                  providers=["CPUExecutionProvider"])
+_predictor = MovePredictor(MODELS_DIR, stockfish_path=STOCKFISH_PATH)
+
+
+class PredictRequest(BaseModel):
+    fen: str = Field(..., description="FEN (full or placement-only).",
+                     examples=["rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1"])
+    top_n: int = Field(3, ge=1, le=8)
+
+
+@app.get("/")
+def root():
+    return {"service": "Chess Vision API", "version": app.version,
+            "stockfish": _predictor.stockfish_path is not None, "docs": "/docs"}
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "stockfish": _predictor.stockfish_path is not None}
+
+
+@app.post("/digitize")
+async def digitize(file: UploadFile = File(...)):
+    """Upload a board image (render-style) and get its FEN board placement."""
+    data = await file.read()
+    img = cv.imdecode(np.frombuffer(data, np.uint8), cv.IMREAD_COLOR)
+    if img is None:
+        raise HTTPException(400, "Could not decode the image.")
+    placement = image_to_fen(img, _digitizer)
+    if placement is None:
+        raise HTTPException(422, "Could not detect a full 8x8 board in the image.")
+    return {"placement": placement, "fen": f"{placement} w - - 0 1"}
+
+
+@app.post("/predict-move")
+def predict_move(req: PredictRequest):
+    try:
+        return _predictor.predict(req.fen, top_n=req.top_n)
+    except ValueError as e:
+        raise HTTPException(400, f"Invalid FEN: {e}")

app/predict.py

@@ -0,0 +1,99 @@
+"""Human-like move prediction: CNN (piece + square classifiers) + Stockfish.
+
+The CNN models predict the move a *human* would likely play (trained for white to
+move; black positions are mirrored). Stockfish provides engine-strength moves and
+a hybrid that keeps human-like moves which don't blunder.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import chess
+import numpy as np
+import onnxruntime as ort
+
+PIECE_ORDER = [chess.PAWN, chess.KNIGHT, chess.BISHOP, chess.ROOK, chess.QUEEN, chess.KING]
+SQUARE_NAMES = ["pawn", "knight", "bishop", "rook", "queen", "king"]
+
+
+def _softmax(x):
+    e = np.exp(x - x.max())
+    return e / e.sum()
+
+
+class MovePredictor:
+    def __init__(self, models_dir: str, stockfish_path: str | None = None):
+        d = Path(models_dir)
+        prov = ["CPUExecutionProvider"]
+        self.piece = ort.InferenceSession(str(d / "piece.int8.onnx"), providers=prov)
+        self.squares = [ort.InferenceSession(str(d / f"square_{s}.int8.onnx"), providers=prov)
+                        for s in SQUARE_NAMES]
+        self.stockfish_path = (stockfish_path if stockfish_path and Path(stockfish_path).exists()
+                               else None)
+
+    # ── encoding: 12x8x8, ch 0-5 white P,N,B,R,Q,K; 6-11 black; row0 = rank8 ──
+    def _encode(self, board: chess.Board):
+        enc = np.zeros((12, 8, 8), np.float32)
+        for sq in chess.SQUARES:
+            p = board.piece_at(sq)
+            if p:
+                c = PIECE_ORDER.index(p.piece_type) + (0 if p.color == chess.WHITE else 6)
+                enc[c, 7 - (sq >> 3), sq & 7] = 1.0
+        return enc[None]
+
+    def _cnn_white(self, board: chess.Board) -> dict:
+        enc = self._encode(board)
+        pieces = _softmax(self.piece.run(None, {"input": enc})[0].flatten())
+        legal = set(board.legal_moves)
+        mp: dict[str, float] = {}
+        for i, ptype in enumerate(PIECE_ORDER):
+            sq = (_softmax(self.squares[i].run(None, {"input": enc})[0].flatten()) + pieces[i]) / 2
+            for fsq in board.pieces(ptype, chess.WHITE):
+                fs = chess.square_name(fsq)
+                for j in range(64):
+                    try:
+                        mv = chess.Move.from_uci(fs + chess.square_name(j))
+                    except ValueError:
+                        continue
+                    if mv in legal:
+                        mp[mv.uci()] = float(sq[j])
+        return mp
+
+    def cnn_scores(self, board: chess.Board) -> dict:
+        """Move->score; handles black by mirroring the board and the moves."""
+        if board.turn == chess.WHITE:
+            return self._cnn_white(board)
+        mirrored = self._cnn_white(board.mirror())
+        out = {}
+        for uci, s in mirrored.items():
+            mv = chess.Move.from_uci(uci)
+            real = chess.Move(chess.square_mirror(mv.from_square),
+                              chess.square_mirror(mv.to_square), mv.promotion)
+            out[real.uci()] = s
+        return out
+
+    def predict(self, fen: str, top_n: int = 3) -> dict:
+        board = chess.Board(fen)
+        cnn = [m for m, _ in sorted(self.cnn_scores(board).items(), key=lambda x: -x[1])]
+        out = {"fen": fen, "turn": "white" if board.turn else "black",
+               "cnn": cnn[:top_n], "stockfish": [], "hybrid": cnn[:top_n]}
+
+        if self.stockfish_path:
+            from stockfish import Stockfish
+            sf = Stockfish(path=self.stockfish_path, parameters={"Threads": 1})
+            sf.set_fen_position(fen)
+            sf.update_engine_parameters({"MultiPV": top_n})
+            out["stockfish"] = [t["Move"] for t in sf.get_top_moves(top_n) if t.get("Move")]
+
+            # hybrid: among the top human-like CNN moves, prefer the one Stockfish
+            # rates best (lowest eval for the opponent after the move).
+            scored = []
+            for mv in cnn[:max(6, top_n * 2)]:
+                board.push_uci(mv)
+                sf.set_fen_position(board.fen())
+                ev = sf.get_evaluation()
+                val = ev.get("value", 0) if ev.get("type") == "cp" else (10000 if ev.get("value", 0) > 0 else -10000)
+                board.pop()
+                scored.append((mv, val))      # val = opponent's eval after our move (lower = better for us)
+            out["hybrid"] = [m for m, _ in sorted(scored, key=lambda x: x[1])][:top_n]
+        return out

calibrate.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""Corner-calibration helper for digitization.
+
+    python calibrate.py x1 y1 x2 y2 x3 y3 x4 y4   # TL TR BR BL (8x8 playing area)
+
+Draws the chosen corners on the photo and the perspective-warped board with an
+8x8 grid, so we can eyeball whether the corners are right before classifying.
+"""
+import sys
+import cv2 as cv
+import numpy as np
+
+SIZE = 800  # warped board side (px)
+
+img = cv.imread("samples/board.png")
+H, W = img.shape[:2]
+
+if len(sys.argv) == 9:
+    pts = list(map(float, sys.argv[1:9]))
+    corners = np.array([[pts[0], pts[1]], [pts[2], pts[3]],
+                        [pts[4], pts[5]], [pts[6], pts[7]]], dtype=np.float32)
+else:
+    # first guess (TL, TR, BR, BL) on the 1920x1080 photo
+    corners = np.array([[518, 130], [1210, 115], [1370, 900], [455, 915]], dtype=np.float32)
+
+# --- overlay on the original ---
+ov = img.copy()
+labels = ["TL", "TR", "BR", "BL"]
+for (x, y), lab in zip(corners, labels):
+    cv.circle(ov, (int(x), int(y)), 12, (0, 0, 255), -1)
+    cv.putText(ov, lab, (int(x) + 14, int(y)), cv.FONT_HERSHEY_SIMPLEX, 1.2, (0, 0, 255), 3)
+cv.polylines(ov, [corners.astype(int)], True, (0, 255, 0), 3)
+cv.imwrite("/tmp/overlay.png", ov)
+
+# --- perspective warp to a square, with 8x8 grid ---
+dst = np.array([[0, 0], [SIZE, 0], [SIZE, SIZE], [0, SIZE]], dtype=np.float32)
+M = cv.getPerspectiveTransform(corners, dst)
+warp = cv.warpPerspective(img, M, (SIZE, SIZE))
+grid = warp.copy()
+for i in range(9):
+    p = i * SIZE // 8
+    cv.line(grid, (p, 0), (p, SIZE), (0, 0, 255), 2)
+    cv.line(grid, (0, p), (SIZE, p), (0, 0, 255), 2)
+cv.imwrite("/tmp/warped_grid.png", grid)
+cv.imwrite("/tmp/warped.png", warp)
+print("wrote /tmp/overlay.png and /tmp/warped_grid.png")

convert_to_onnx.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Convert the trained .pth models to quantized ONNX (INT8) for serving.
+
+Reads the weights from the Master's project, exports each model to ONNX and
+applies dynamic INT8 quantization to shrink the ~444 MB of .pth files.
+
+    python convert_to_onnx.py
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import torch
+from onnxruntime.quantization import QuantType, quantize_dynamic
+
+from app.chess_models import PieceClassifier, PieceImageClassifier, SquareClassifier
+
+PTH_DIR = Path("../Master-of-Science-Degree-Project/Models")
+OUT = Path("models_onnx")
+OUT.mkdir(exist_ok=True)
+
+
+def _find_state_dict(obj) -> dict:
+    """Accept a bare state_dict or a checkpoint with an arbitrarily-named
+    sub-dict of tensors (e.g. 'model_state_dict_PC')."""
+    if isinstance(obj, dict) and obj and all(isinstance(v, torch.Tensor) for v in obj.values()):
+        return obj
+    if isinstance(obj, dict):
+        for v in obj.values():
+            if isinstance(v, dict) and v and all(isinstance(t, torch.Tensor) for t in v.values()):
+                return v
+    raise ValueError("no state_dict found in checkpoint")
+
+
+def load(model: torch.nn.Module, pth: str) -> torch.nn.Module:
+    obj = torch.load(PTH_DIR / pth, map_location="cpu", weights_only=False)
+    model.load_state_dict(_find_state_dict(obj))
+    model.eval()
+    return model
+
+
+def export(model: torch.nn.Module, dummy: torch.Tensor, name: str, dyn: dict):
+    fp32 = OUT / f"{name}.onnx"
+    torch.onnx.export(
+        model, dummy, str(fp32),
+        input_names=["input"], output_names=["output"],
+        dynamic_axes=dyn, opset_version=17, dynamo=False,
+    )
+    int8 = OUT / f"{name}.int8.onnx"
+    quantize_dynamic(str(fp32), str(int8), weight_type=QuantType.QInt8)
+    fp32.unlink()  # keep only the quantized one
+    return int8.stat().st_size / 1e6
+
+
+def main() -> None:
+    jobs = [
+        (PieceImageClassifier(), "imageClassifierReal.pth", "digitizer",
+         torch.randn(1, 3, 96, 96), {"input": {0: "b", 2: "h", 3: "w"}}),
+        (PieceClassifier(), "pieceClassifier.pth", "piece",
+         torch.randn(1, 12, 8, 8), {"input": {0: "b"}}),
+    ]
+    for piece in ["Pawn", "Knight", "Bishop", "Rook", "Queen", "King"]:
+        jobs.append((SquareClassifier(), f"square{piece}Classifier.pth",
+                     f"square_{piece.lower()}", torch.randn(1, 12, 8, 8), {"input": {0: "b"}}))
+
+    total = 0.0
+    for model, pth, name, dummy, dyn in jobs:
+        try:
+            load(model, pth)
+            mb = export(model, dummy, name, dyn)
+            total += mb
+            print(f"  ✓ {name:16s} <- {pth:28s} {mb:6.1f} MB (int8)")
+        except Exception as e:
+            print(f"  ✗ {name:16s} <- {pth:28s} FAILED: {type(e).__name__}: {e}")
+
+    print(f"\nTotal ONNX INT8: {total:.1f} MB  (from ~444 MB of .pth)")
+
+
+if __name__ == "__main__":
+    main()

digitize_corners.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Decisive test: 4-corner grid (robust) + EXACT Preprocess crop (bbox + 90px top),
+classify the 64 squares, compare to FEN under all 8 orientations and 3 norms."""
+import cv2 as cv
+import numpy as np
+import onnxruntime as ort
+
+TRUE = "rn1qkb1r/pb2pppp/5n2/1ppp4/8/3P1NP1/PPP1PPBP/RNBQ1RK1"
+IDX2SYM = {0:"K",1:"Q",2:"R",3:"B",4:"N",5:"P",6:"k",7:"q",8:"r",9:"b",10:"n",11:"p"}
+# corners on the FULL photo (TL,TR,BR,BL of the 8x8 area)
+CORNERS_FULL = np.array([[520,140],[1360,150],[1430,915],[452,918]], np.float32)
+
+
+def crop_image(im):
+    cx, cy = im.shape[1]//2, im.shape[0]//2
+    return im[cy-520:cy+450, cx-550:cx+550], (cx-550, cy-520)
+
+
+def true_grid():
+    g=[]
+    for row in TRUE.split("/"):
+        r=[]
+        for ch in row: r += ["."]*int(ch) if ch.isdigit() else [ch]
+        g.append(r)
+    return np.array(g)
+
+
+def main():
+    img = cv.imread("samples/board.png")
+    im, (ox, oy) = crop_image(img)
+    corners = CORNERS_FULL - [ox, oy]                       # into crop space
+    unit = np.array([[0,0],[8,0],[8,8],[0,8]], np.float32)
+    Hmat = cv.getPerspectiveTransform(unit, corners)        # unit grid -> image
+
+    def node(c, r):
+        p = cv.perspectiveTransform(np.array([[[c, r]]], np.float32), Hmat)[0][0]
+        return p
+
+    crops = []
+    for r in range(8):
+        for c in range(8):
+            pts = [node(c, r), node(c+1, r), node(c+1, r+1), node(c, r+1)]
+            xs = [p[0] for p in pts]; ys = [p[1] for p in pts]
+            x1, x2 = int(min(xs)), int(max(xs))
+            y1 = max(0, int(min(ys)) - 90); y2 = int(max(ys))
+            crops.append(im[y1:y2, x1:x2])
+
+    sess = ort.InferenceSession("models_onnx/digitizer.fp32.onnx", providers=["CPUExecutionProvider"])
+    T = true_grid()
+    occ = (T != ".")
+    n_occ = int(occ.sum())
+
+    for nm, fn in [("/255", lambda r: r/255.0),
+                   ("imagenet", lambda r: (r/255.0-[0.485,0.456,0.406])/[0.229,0.224,0.225]),
+                   ("[-1,1]", lambda r: r/127.5-1)]:
+        P = np.empty((8,8), object)
+        for i, crop in enumerate(crops):
+            if crop.size == 0:
+                P[i//8, i%8] = "?"; continue
+            rgb = cv.cvtColor(cv.resize(crop,(96,96)), cv.COLOR_BGR2RGB).astype(np.float32)
+            x = np.asarray(fn(rgb), np.float32).transpose(2,0,1)[None]
+            out = sess.run(None, {"input": x})[0].flatten()
+            P[i//8, i%8] = IDX2SYM[int(out.argmax())]
+        # best over 8 dihedral orientations, counting only TRUE-occupied squares
+        best = 0; bestname = ""
+        for k, Q in [("id",P),("rot90",np.rot90(P)),("rot180",np.rot90(P,2)),("rot270",np.rot90(P,3)),
+                     ("flipUD",np.flipud(P)),("flipLR",np.fliplr(P)),
+                     ("transp",P.T),("anti",np.fliplr(np.rot90(P)))]:
+            if Q.shape!=T.shape: continue
+            m = int(((Q==T)&occ).sum())
+            if m>best: best, bestname = m, k
+        print(f"[{nm:9s}] best occupied-match {best:2d}/{n_occ}  ({bestname})")
+
+
+if __name__ == "__main__":
+    main()

digitize_fen.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""Full image -> FEN: exact grid + crop + transform + empty detection (binarize
+center) + flipUD orientation. Compares to the known FEN for i10."""
+import sys
+import cv2 as cv
+import numpy as np
+import onnxruntime as ort
+from digitize_full import get_casas, crop_square
+
+TRUE = "rn1qkb1r/pb2pppp/5n2/1ppp4/8/3P1NP1/PPP1PPBP/RNBQ1RK1"
+IDX2SYM = {0:"P",1:"N",2:"B",3:"R",4:"Q",5:"K",6:"p",7:"n",8:"b",9:"r",10:"q",11:"k"}
+MEAN, STD = np.array([0.485,0.456,0.406],np.float32), np.array([0.229,0.224,0.225],np.float32)
+
+
+def preprocess(bgr):
+    rgb = cv.cvtColor(cv.resize(bgr,(224,224)),cv.COLOR_BGR2RGB).astype(np.float32)/255.0
+    return ((rgb-MEAN)/STD).transpose(2,0,1)[None]
+
+
+def is_empty(im, quad):
+    cx = int(np.mean([p[0] for p in quad])); cy = int(np.mean([p[1] for p in quad]))
+    w = max(6, int(0.22*(max(p[0] for p in quad)-min(p[0] for p in quad))))
+    patch = im[max(0,cy-w):cy+w, max(0,cx-w):cx+w]
+    if patch.size == 0:
+        return True
+    g = cv.cvtColor(patch, cv.COLOR_BGR2GRAY)
+    return g.std() < 18      # flat colour -> empty
+
+
+def grid_to_fen(grid):
+    out=[]
+    for row in grid:
+        s=""; e=0
+        for cell in row:
+            if cell==".": e+=1
+            else:
+                if e: s+=str(e); e=0
+                s+=cell
+        if e: s+=str(e)
+        out.append(s)
+    return "/".join(out)
+
+
+def main():
+    path = sys.argv[1] if len(sys.argv) > 1 else "samples/board.png"
+    im, casas = get_casas(path)
+    sess = ort.InferenceSession("models_onnx/digitizer3d.fp32.onnx", providers=["CPUExecutionProvider"])
+    syms=[]
+    for p in casas[:64]:
+        if is_empty(im, p):
+            syms.append("."); continue
+        c = crop_square(im, p)
+        out = sess.run(None, {"input": preprocess(c)})[0].flatten()
+        syms.append(IDX2SYM[int(out.argmax())])
+    grid = np.flipud(np.array(syms, object).reshape(8,8))     # flipUD orientation
+    fen = grid_to_fen(grid)
+    print("PRED FEN:", fen)
+    print("TRUE FEN:", TRUE)
+    T = np.array([list(r) for r in
+                  ["".join("." if ch.isdigit() and False else ch for ch in row) for row in TRUE.split("/")]], object)
+    # build true grid properly
+    tg=[]
+    for row in TRUE.split("/"):
+        rr=[]
+        for ch in row: rr += ["."]*int(ch) if ch.isdigit() else [ch]
+        tg.append(rr)
+    T=np.array(tg,object)
+    print(f"exact-cell match: {int((grid==T).sum())}/64")
+
+
+if __name__ == "__main__":
+    main()

digitize_final.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""Digitization with the EXACT transform from Utils/read_imgs.py:
+Resize(224,224) + ToTensor + ImageNet Normalize, and the correct class order."""
+import sys
+import cv2 as cv
+import numpy as np
+import onnxruntime as ort
+from digitize_full import get_casas, crop_square
+
+TRUE = "rn1qkb1r/pb2pppp/5n2/1ppp4/8/3P1NP1/PPP1PPBP/RNBQ1RK1"
+# from read_imgs.py: {'P':0,'N':1,'B':2,'R':3,'Q':4,'K':5,'p':6,'n':7,'b':8,'r':9,'q':10,'k':11}
+IDX2SYM = {0:"P",1:"N",2:"B",3:"R",4:"Q",5:"K",6:"p",7:"n",8:"b",9:"r",10:"q",11:"k"}
+MEAN = np.array([0.485,0.456,0.406], np.float32)
+STD = np.array([0.229,0.224,0.225], np.float32)
+
+
+def preprocess(bgr):
+    rgb = cv.cvtColor(cv.resize(bgr,(224,224)), cv.COLOR_BGR2RGB).astype(np.float32)/255.0
+    return ((rgb-MEAN)/STD).transpose(2,0,1)[None]
+
+
+def true_grid():
+    g=[]
+    for row in TRUE.split("/"):
+        r=[]
+        for ch in row: r += ["."]*int(ch) if ch.isdigit() else [ch]
+        g.append(r)
+    return np.array(g)
+
+
+def main():
+    path = sys.argv[1] if len(sys.argv) > 1 else "samples/board.png"
+    im, casas = get_casas(path)
+    print("squares:", len(casas))
+    crops = [crop_square(im, p) for p in casas[:64]]
+    T = true_grid(); occ = (T!="."); n=int(occ.sum())
+
+    for model in ["digitizer3d.fp32.onnx", "digitizer.fp32.onnx"]:
+        sess = ort.InferenceSession(f"models_onnx/{model}", providers=["CPUExecutionProvider"])
+        syms=[]
+        for c in crops:
+            if c.size==0: syms.append("?"); continue
+            out = sess.run(None, {"input": preprocess(c)})[0].flatten()
+            syms.append(IDX2SYM[int(out.argmax())])
+        P = np.array(syms, object).reshape(8,8)
+        best = max((int(((Q==T)&occ).sum()), k) for k,Q in
+                   [("id",P),("rot90",np.rot90(P)),("rot180",np.rot90(P,2)),("rot270",np.rot90(P,3)),
+                    ("flipUD",np.flipud(P)),("flipLR",np.fliplr(P)),("T",P.T),("anti",np.fliplr(np.rot90(P)))])
+        tag = "3D" if "3d" in model else "REAL"
+        print(f"  {tag:4s}: best occupied-match {best[0]:2d}/{n}  ({best[1]})")
+
+
+if __name__ == "__main__":
+    main()

digitize_full.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Full digitization on samples/board.png (i10): exact Preprocess grid (with the
+3rd-from-bottom line removed) + exact bbox+90 crop + classify, vs known FEN."""
+import cv2 as cv
+import numpy as np
+import onnxruntime as ort
+import hough_pipeline as hp
+
+TRUE = "rn1qkb1r/pb2pppp/5n2/1ppp4/8/3P1NP1/PPP1PPBP/RNBQ1RK1"
+IDX2SYM = {0:"K",1:"Q",2:"R",3:"B",4:"N",5:"P",6:"k",7:"q",8:"r",9:"b",10:"n",11:"p"}
+
+
+def get_casas(path):
+    im = hp.crop_image(cv.imread(path))
+    board = hp.filter_board_lines(hp.group_lines(hp.detect_lines(hp.detect_edges(im))))
+    rows = hp.compute_intersections(board)
+    by_y = sorted(rows, key=lambda r: np.mean([p[1] for p in r]), reverse=True)
+    rows = [r for r in rows if r is not by_y[2]]
+    return im, hp.build_squares(rows)
+
+
+def crop_square(im, p):
+    xs = [pt[0] for pt in p]; ys = [pt[1] for pt in p]
+    x_min, x_max = min(xs), max(xs); y_min, y_max = min(ys), max(ys)
+    return im[max(0, y_min - 90):y_max, x_min:x_max]
+
+
+def true_grid():
+    g = []
+    for row in TRUE.split("/"):
+        r = []
+        for ch in row:
+            r += ["."] * int(ch) if ch.isdigit() else [ch]
+        g.append(r)
+    return np.array(g)
+
+
+def main():
+    im, casas = get_casas("samples/board.png")
+    print("squares:", len(casas))
+    if len(casas) != 64:
+        return
+    crops = [crop_square(im, p) for p in casas[:64]]
+    sess = ort.InferenceSession("models_onnx/digitizer.fp32.onnx", providers=["CPUExecutionProvider"])
+    T = true_grid(); occ = (T != "."); n = int(occ.sum())
+
+    for nm, fn in [("/255", lambda r: r/255.0),
+                   ("imagenet", lambda r: (r/255.0-[0.485,0.456,0.406])/[0.229,0.224,0.225]),
+                   ("[-1,1]", lambda r: r/127.5-1)]:
+        syms = []
+        for c in crops:
+            if c.size == 0:
+                syms.append("?"); continue
+            rgb = cv.cvtColor(cv.resize(c, (96, 96)), cv.COLOR_BGR2RGB).astype(np.float32)
+            x = np.asarray(fn(rgb), np.float32).transpose(2, 0, 1)[None]
+            out = sess.run(None, {"input": x})[0].flatten()
+            syms.append(IDX2SYM[int(out.argmax())])
+        P = np.array(syms, object).reshape(8, 8)
+        best = max(
+            (int(((Q == T) & occ).sum()), k)
+            for k, Q in [("id", P), ("rot90", np.rot90(P)), ("rot180", np.rot90(P, 2)),
+                         ("rot270", np.rot90(P, 3)), ("flipUD", np.flipud(P)),
+                         ("flipLR", np.fliplr(P)), ("T", P.T), ("anti", np.fliplr(np.rot90(P)))]
+        )
+        print(f"[{nm:9s}] best occupied-match {best[0]:2d}/{n}  ({best[1]})")
+
+
+if __name__ == "__main__":
+    main()

digitize_full_3d.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Full digitization on samples/board.png (i10): exact Preprocess grid (with the
+3rd-from-bottom line removed) + exact bbox+90 crop + classify, vs known FEN."""
+import cv2 as cv
+import numpy as np
+import onnxruntime as ort
+import hough_pipeline as hp
+
+TRUE = "rn1qkb1r/pb2pppp/5n2/1ppp4/8/3P1NP1/PPP1PPBP/RNBQ1RK1"
+IDX2SYM = {0:"K",1:"Q",2:"R",3:"B",4:"N",5:"P",6:"k",7:"q",8:"r",9:"b",10:"n",11:"p"}
+
+
+def get_casas(path):
+    im = hp.crop_image(cv.imread(path))
+    board = hp.filter_board_lines(hp.group_lines(hp.detect_lines(hp.detect_edges(im))))
+    rows = hp.compute_intersections(board)
+    by_y = sorted(rows, key=lambda r: np.mean([p[1] for p in r]), reverse=True)
+    rows = [r for r in rows if r is not by_y[2]]
+    return im, hp.build_squares(rows)
+
+
+def crop_square(im, p):
+    xs = [pt[0] for pt in p]; ys = [pt[1] for pt in p]
+    x_min, x_max = min(xs), max(xs); y_min, y_max = min(ys), max(ys)
+    return im[max(0, y_min - 90):y_max, x_min:x_max]
+
+
+def true_grid():
+    g = []
+    for row in TRUE.split("/"):
+        r = []
+        for ch in row:
+            r += ["."] * int(ch) if ch.isdigit() else [ch]
+        g.append(r)
+    return np.array(g)
+
+
+def main():
+    im, casas = get_casas("samples/board.png")
+    print("squares:", len(casas))
+    if len(casas) != 64:
+        return
+    crops = [crop_square(im, p) for p in casas[:64]]
+    sess = ort.InferenceSession("models_onnx/digitizer3d.fp32.onnx", providers=["CPUExecutionProvider"])
+    T = true_grid(); occ = (T != "."); n = int(occ.sum())
+
+    for nm, fn in [("/255", lambda r: r/255.0),
+                   ("imagenet", lambda r: (r/255.0-[0.485,0.456,0.406])/[0.229,0.224,0.225]),
+                   ("[-1,1]", lambda r: r/127.5-1)]:
+        syms = []
+        for c in crops:
+            if c.size == 0:
+                syms.append("?"); continue
+            rgb = cv.cvtColor(cv.resize(c, (96, 96)), cv.COLOR_BGR2RGB).astype(np.float32)
+            x = np.asarray(fn(rgb), np.float32).transpose(2, 0, 1)[None]
+            out = sess.run(None, {"input": x})[0].flatten()
+            syms.append(IDX2SYM[int(out.argmax())])
+        P = np.array(syms, object).reshape(8, 8)
+        best = max(
+            (int(((Q == T) & occ).sum()), k)
+            for k, Q in [("id", P), ("rot90", np.rot90(P)), ("rot180", np.rot90(P, 2)),
+                         ("rot270", np.rot90(P, 3)), ("flipUD", np.flipud(P)),
+                         ("flipLR", np.fliplr(P)), ("T", P.T), ("anti", np.fliplr(np.rot90(P)))]
+        )
+        print(f"[{nm:9s}] best occupied-match {best[0]:2d}/{n}  ({best[1]})")
+
+
+if __name__ == "__main__":
+    main()

digitize_test.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Diagnostic: classify the 64 squares of samples/board.png and compare to the
+known FEN. Helps calibrate crop/normalization and understand the empty-class issue."""
+import sys
+import cv2 as cv
+import numpy as np
+import onnxruntime as ort
+
+SIZE = 800
+CORNERS = np.array([[520, 140], [1360, 150], [1430, 915], [452, 918]], dtype=np.float32)
+TRUE_FEN = "rn1qkb1r/pb2pppp/5n2/1ppp4/8/3P1NP1/PPP1PPBP/RNBQ1RK1"
+IDX2SYM = {0: "K", 1: "Q", 2: "R", 3: "B", 4: "N", 5: "P",
+           6: "k", 7: "q", 8: "r", 9: "b", 10: "n", 11: "p"}
+
+MEAN = np.array([0.485, 0.456, 0.406], np.float32)
+STD = np.array([0.229, 0.224, 0.225], np.float32)
+
+
+def preprocess(bgr):
+    rgb = cv.cvtColor(cv.resize(bgr, (96, 96)), cv.COLOR_BGR2RGB).astype(np.float32) / 255.0
+    rgb = (rgb - MEAN) / STD
+    return rgb.transpose(2, 0, 1)[None]
+
+
+def fen_grid(fen):
+    grid = []
+    for row in fen.split("/"):
+        r = []
+        for ch in row:
+            if ch.isdigit():
+                r += ["."] * int(ch)
+            else:
+                r.append(ch)
+        grid.append(r)
+    return grid
+
+
+def main():
+    margin = float(sys.argv[1]) if len(sys.argv) > 1 else 0.6  # top margin (cell fractions)
+    img = cv.imread("samples/board.png")
+    dst = np.array([[0, 0], [SIZE, 0], [SIZE, SIZE], [0, SIZE]], np.float32)
+    Minv = cv.getPerspectiveTransform(dst, CORNERS)  # warped -> original
+
+    sess = ort.InferenceSession("models_onnx/digitizer.int8.onnx",
+                                providers=["CPUExecutionProvider"])
+    cell = SIZE / 8
+    pred = [["." for _ in range(8)] for _ in range(8)]
+    prob = [[0.0 for _ in range(8)] for _ in range(8)]
+
+    for r in range(8):
+        for c in range(8):
+            # cell quad in warped space, extended upward by `margin` cells for the piece
+            y0 = (r - margin) * cell
+            quad = np.array([[[c * cell, y0], [(c + 1) * cell, y0],
+                              [(c + 1) * cell, (r + 1) * cell], [c * cell, (r + 1) * cell]]],
+                            np.float32)
+            orig = cv.perspectiveTransform(quad, Minv)[0]
+            xs, ys = orig[:, 0], orig[:, 1]
+            x1, x2 = max(0, int(xs.min())), min(img.shape[1], int(xs.max()))
+            y1, y2 = max(0, int(ys.min())), min(img.shape[0], int(ys.max()))
+            crop = img[y1:y2, x1:x2]
+            if crop.size == 0:
+                continue
+            out = sess.run(None, {"input": preprocess(crop)})[0].flatten()
+            p = np.exp(out) / np.exp(out).sum()
+            k = int(p.argmax())
+            pred[r][c] = IDX2SYM[k]
+            prob[r][c] = float(p[k])
+
+    true = fen_grid(TRUE_FEN)
+    print(f"margin={margin}\n")
+    print("PRED (top row = rank8 assumed):           TRUE:")
+    hits = 0
+    for r in range(8):
+        pr = " ".join(pred[r])
+        tr = " ".join(true[r])
+        hits += sum(1 for a, b in zip(pred[r], true[r]) if a == b)
+        print(f"  {pr}     {tr}")
+    print(f"\nexact-cell match (incl. empties): {hits}/64")
+    print("avg max-prob per row (low on empties?):")
+    for r in range(8):
+        print("  " + " ".join(f"{prob[r][c]:.2f}" for c in range(8)))
+
+
+if __name__ == "__main__":
+    main()

hough_pipeline.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""EXACT Preprocess.ipynb pipeline on a given image, with per-step visualizations.
+
+    python hough_pipeline.py samples/i1000.png
+"""
+import sys
+import cv2 as cv
+import numpy as np
+
+
+def crop_image(im):
+    cx, cy = im.shape[1] // 2, im.shape[0] // 2
+    return im[cy - 520:cy + 450, cx - 550:cx + 550]
+
+def detect_edges(im):  return cv.Canny(im, 100, 150, apertureSize=3)
+def detect_lines(b):   return cv.HoughLines(b, 1, np.pi / 180, 160)
+
+def group_lines(linhas):
+    g = []
+    for linha in linhas:
+        rho, theta = linha[0]
+        if not any(abs(rho - l[0][0]) < 30 and abs(theta - l[0][1]) < np.pi / 18 for l in g):
+            g.append(linha)
+    return g
+
+def filter_board_lines(g):
+    min_rho = None
+    for linha in g:
+        rho, theta = linha[0]
+        if 1 < theta < 3 and (min_rho is None or rho < min_rho):
+            min_rho = rho
+    return [l for l in g if l[0][0] != min_rho]
+
+def line_pts(rho, theta):
+    a, b = np.cos(theta), np.sin(theta)
+    x0, y0 = a * rho, b * rho
+    return ((int(x0 + 10000 * -b), int(y0 + 10000 * a)),
+            (int(x0 - 10000 * -b), int(y0 - 10000 * a)))
+
+def compute_intersections(linhas_casas):
+    lp = [[*line_pts(l[0][0], l[0][1]), l[0][1]] for l in linhas_casas]
+    rows = []
+    for i in range(len(lp)):
+        pts = []
+        for j in range(len(lp)):
+            (x1, y1), (x2, y2) = lp[i][0], lp[i][1]
+            (x3, y3), (x4, y4) = lp[j][0], lp[j][1]
+            det = (x1 - x2) * (y3 - y4) - (y1 - y2) * (x3 - x4)
+            if det != 0:
+                ix = int(((x1 * y2 - y1 * x2) * (x3 - x4) - (x1 - x2) * (x3 * y4 - y3 * x4)) / det)
+                iy = int(((x1 * y2 - y1 * x2) * (y3 - y4) - (y1 - y2) * (x3 * y4 - y3 * x4)) / det)
+                if 0 <= ix <= 1920 and 0 <= iy <= 1080 and 1 < lp[i][2] < 3:
+                    pts.append((ix, iy))
+        if pts:
+            pts.sort(key=lambda p: p[0]); rows.append(pts)
+    rows.sort(key=lambda p: p[0][0])
+    return rows
+
+def build_squares(rows):
+    casas = []
+    for i in range(len(rows) - 1):
+        for j in range(len(rows[i]) - 1):
+            casas.append([rows[i][j], rows[i][j + 1], rows[i + 1][j], rows[i + 1][j + 1]])
+    return casas
+
+
+def main():
+    path = sys.argv[1] if len(sys.argv) > 1 else "samples/i1000.png"
+    im = crop_image(cv.imread(path))
+    edges = detect_edges(im)
+    cv.imwrite("/tmp/h_canny.png", edges)
+
+    lines = detect_lines(edges)
+    print("hough lines:", 0 if lines is None else len(lines))
+    grouped = group_lines(lines)
+    board_lines = filter_board_lines(grouped)
+    print("grouped:", len(grouped), " board_lines:", len(board_lines))
+
+    vis = im.copy()
+    for l in board_lines:
+        (p1, p2) = line_pts(l[0][0], l[0][1])
+        cv.line(vis, p1, p2, (0, 0, 255), 2)
+    cv.imwrite("/tmp/h_lines.png", vis)
+
+    rows = compute_intersections(board_lines)
+    print("intersection rows (raw):", len(rows))
+    # remove the spurious extra horizontal line: the 3rd counting from the bottom
+    by_y = sorted(rows, key=lambda r: np.mean([p[1] for p in r]), reverse=True)
+    if len(by_y) >= 3:
+        extra = by_y[2]
+        rows = [r for r in rows if r is not extra]
+    print("intersection rows (after removing 3rd-from-bottom):", len(rows),
+          " pts/row:", [len(r) for r in rows])
+    vp = im.copy()
+    for r in rows:
+        for (x, y) in r:
+            cv.circle(vp, (x, y), 5, (255, 0, 0), -1)
+    cv.imwrite("/tmp/h_points.png", vp)
+
+    casas = build_squares(rows)
+    print("SQUARES:", len(casas))
+
+
+if __name__ == "__main__":
+    main()

models_onnx/digitizer.fp32.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8caf8cf4ae159f51ea8341e4493da2afe7ebb6447fca7b07f7c66c382ab8e9f4
+size 11516960

models_onnx/digitizer.int8.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:266f19b2ab7892b5c8a1381a3dc353319599985d4cfd56c68d79893d9af09573
+size 3075141

models_onnx/digitizer3d.fp32.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:39ca7e7445d102280aeb117fa2c89a14a965ff13cf137b98366a96305bde230a
+size 11516960

models_onnx/piece.int8.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:eb5c1dc8a615f3ca37c63ce12fe9e35ce15a81ea0df78f92dfdefa48e085cd19
+size 5038398

models_onnx/square_bishop.int8.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4a2ffedd4fc2ad9f4dd4f38ecb71b4a5d9d385638cbd82ab8b151d400700eef7
+size 5068330

models_onnx/square_king.int8.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:da7ce65c37676d4f121778b4ef87866417ab9d96b2b1a168598b203b20de0f7a
+size 5068330

models_onnx/square_knight.int8.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2d9cdf9adcd841a118f59d8cc379827d75340437aee22e5e64e95cb3687a1cec
+size 5068330

models_onnx/square_pawn.int8.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cb978b0b60b4f54f886b276f518409842ebaaf5716b17f96b567aa2a3f7c9292
+size 5068330

models_onnx/square_queen.int8.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:337cef4bd297a6c0b719a257fd2200839f796b9c95938e406cdb618daf92b241
+size 5068330

models_onnx/square_rook.int8.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e743d764a203bec196138239424c41c5f6c652a752e9aa311e591ec20943e60c
+size 5068330

move_predict.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Move prediction inference (CNN part) replicating Predict_Human_Move_Train.test_model.
+Sanity-checks the 12x8x8 encoding + class order on the start position."""
+import sys
+import numpy as np
+import onnxruntime as ort
+import chess
+
+PIECE_ORDER = [chess.PAWN, chess.KNIGHT, chess.BISHOP, chess.ROOK, chess.QUEEN, chess.KING]
+SQUARE_MODELS = ["pawn", "knight", "bishop", "rook", "queen", "king"]
+
+
+def encode(board, row0_rank8=True):
+    """12x8x8: channels 0-5 white P,N,B,R,Q,K; 6-11 black. (white-to-move board)"""
+    enc = np.zeros((12, 8, 8), np.float32)
+    for sq in chess.SQUARES:
+        p = board.piece_at(sq)
+        if p:
+            c = PIECE_ORDER.index(p.piece_type) + (0 if p.color == chess.WHITE else 6)
+            r = 7 - (sq // 8) if row0_rank8 else (sq // 8)
+            enc[c, r, sq % 8] = 1.0
+    return enc[None]
+
+
+def softmax(x):
+    e = np.exp(x - x.max()); return e / e.sum()
+
+
+def cnn_moves(board, piece_sess, square_sesss, row0_rank8=True):
+    enc = encode(board, row0_rank8)
+    pieces = softmax(piece_sess.run(None, {"input": enc})[0].flatten())
+    legal = list(board.legal_moves)
+    move_prob = {}
+    for i, ptype in enumerate(PIECE_ORDER):
+        squares = softmax(square_sesss[i].run(None, {"input": enc})[0].flatten())
+        squares = (squares + pieces[i]) / 2
+        for from_sq in board.pieces(ptype, chess.WHITE):
+            fs = chess.square_name(from_sq)
+            for j in range(64):
+                try:
+                    mv = chess.Move.from_uci(fs + chess.square_name(j))
+                    if mv in legal:
+                        move_prob[mv.uci()] = squares[j]
+                except Exception:
+                    pass
+    return [m for m, _ in sorted(move_prob.items(), key=lambda x: x[1], reverse=True)]
+
+
+def main():
+    piece_sess = ort.InferenceSession("models_onnx/piece.int8.onnx", providers=["CPUExecutionProvider"])
+    square_sesss = [ort.InferenceSession(f"models_onnx/square_{s}.int8.onnx",
+                                         providers=["CPUExecutionProvider"]) for s in SQUARE_MODELS]
+    board = chess.Board()  # start position (white to move)
+    for orient in (True, False):
+        moves = cnn_moves(board, piece_sess, square_sesss, row0_rank8=orient)
+        print(f"row0_rank8={orient}: top CNN moves -> {moves[:8]}")
+
+
+if __name__ == "__main__":
+    main()

preprocess_repro.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Faithful reproduction of Preprocess.ipynb crop pipeline on samples/board.png,
+then classify the 64 squares and compare to the known FEN."""
+import cv2 as cv
+import numpy as np
+import onnxruntime as ort
+
+TRUE = "rn1qkb1r/pb2pppp/5n2/1ppp4/8/3P1NP1/PPP1PPBP/RNBQ1RK1"
+IDX2SYM = {0:"K",1:"Q",2:"R",3:"B",4:"N",5:"P",6:"k",7:"q",8:"r",9:"b",10:"n",11:"p"}
+
+
+# ---- EXACT functions from Preprocess.ipynb ----
+def crop_image(imagem):
+    cx, cy = imagem.shape[1] // 2, imagem.shape[0] // 2
+    return imagem[cy - 520:cy + 450, cx - 550:cx + 550]
+
+def detect_edges(im):       return cv.Canny(im, 100, 150, apertureSize=3)
+def detect_lines(b):        return cv.HoughLines(b, 1, np.pi / 180, 160)
+
+def group_lines(linhas):
+    g = []
+    for linha in linhas:
+        rho, theta = linha[0]
+        if not any(abs(rho - l[0][0]) < 30 and abs(theta - l[0][1]) < np.pi / 18 for l in g):
+            g.append(linha)
+    return g
+
+def filter_board_lines(g):
+    min_rho = None
+    for linha in g:
+        rho, theta = linha[0]
+        if 1 < theta < 3 and (min_rho is None or rho < min_rho):
+            min_rho = rho
+    return [l for l in g if l[0][0] != min_rho]
+
+def compute_intersections(linhas_casas):
+    lp = []
+    for linha in linhas_casas:
+        rho, theta = linha[0]
+        a, b = np.cos(theta), np.sin(theta)
+        x0, y0 = a * rho, b * rho
+        lp.append([(int(x0 + 10000 * -b), int(y0 + 10000 * a)),
+                   (int(x0 - 10000 * -b), int(y0 - 10000 * a)), theta])
+    rows = []
+    for i in range(len(lp)):
+        pts = []
+        for j in range(len(lp)):
+            x1, y1 = lp[i][0]; x2, y2 = lp[i][1]
+            x3, y3 = lp[j][0]; x4, y4 = lp[j][1]
+            det = (x1 - x2) * (y3 - y4) - (y1 - y2) * (x3 - x4)
+            if det != 0:
+                ix = int(((x1 * y2 - y1 * x2) * (x3 - x4) - (x1 - x2) * (x3 * y4 - y3 * x4)) / det)
+                iy = int(((x1 * y2 - y1 * x2) * (y3 - y4) - (y1 - y2) * (x3 * y4 - y3 * x4)) / det)
+                if 0 <= ix <= 1920 and 0 <= iy <= 1080 and 1 < lp[i][2] < 3:
+                    pts.append((ix, iy))
+        if pts:
+            pts.sort(key=lambda p: p[0]); rows.append(pts)
+    rows.sort(key=lambda p: p[0][0])
+    return rows
+
+def build_squares(rows):
+    casas = []
+    for i in range(len(rows) - 1):
+        for j in range(len(rows[i]) - 1):
+            casas.append([rows[i][j], rows[i][j + 1], rows[i + 1][j], rows[i + 1][j + 1]])
+    return casas
+
+
+def crop_square(imagem, p):
+    xs = [pt[0] for pt in p]; ys = [pt[1] for pt in p]
+    x_min, x_max = min(xs), max(xs); y_min, y_max = min(ys), max(ys)
+    if y_min - 80 < 0:
+        y_min = 80
+    return imagem[y_min - 90:y_max, x_min:x_max]
+
+
+def main():
+    img = cv.imread("samples/board.png")
+    im = crop_image(img)
+    print("cropped:", im.shape)
+    lines = detect_lines(detect_edges(im))
+    print("hough lines:", 0 if lines is None else len(lines))
+    g = group_lines(lines)
+    casas = build_squares(compute_intersections(filter_board_lines(g)))
+    print("squares detected:", len(casas))
+
+    # montage of crops in detected order
+    tiles = []
+    for p in casas[:64]:
+        c = crop_square(im, p)
+        tiles.append(cv.resize(c, (90, 90)) if c.size else np.zeros((90, 90, 3), np.uint8))
+    while len(tiles) < 64:
+        tiles.append(np.zeros((90, 90, 3), np.uint8))
+    mont = np.vstack([np.hstack(tiles[r * 8:r * 8 + 8]) for r in range(8)])
+    cv.imwrite("/tmp/sq_montage.png", mont)
+    print("saved /tmp/sq_montage.png")
+
+    if len(casas) != 64:
+        print("!! not 64 squares — pipeline needs tuning for this image"); return
+
+    sess = ort.InferenceSession("models_onnx/digitizer.fp32.onnx", providers=["CPUExecutionProvider"])
+    for nm, fn in [("/255", lambda r: r / 255.0),
+                   ("imagenet", lambda r: (r / 255.0 - [0.485,0.456,0.406]) / [0.229,0.224,0.225])]:
+        import chess
+        board = chess.Board(None)
+        for i, p in enumerate(casas[:64]):
+            c = crop_square(im, p)
+            if c.size == 0:
+                continue
+            rgb = cv.cvtColor(cv.resize(c, (96, 96)), cv.COLOR_BGR2RGB).astype(np.float32)
+            x = np.asarray(fn(rgb), np.float32).transpose(2, 0, 1)[None]
+            out = sess.run(None, {"input": x})[0].flatten()
+            board.set_piece_at(i, chess.Piece.from_symbol(IDX2SYM[int(out.argmax())]))
+        print(f"\n[{nm}] FEN: {board.board_fen()}")
+        print(f"      TRUE: {TRUE}")
+
+
+if __name__ == "__main__":
+    main()

probe_norm.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Probe: is the digitizer responding at all? Try fp32 vs int8 and a few
+normalizations on the 64 squares; report match-count and mean confidence."""
+import cv2 as cv
+import numpy as np
+import onnxruntime as ort
+import torch
+from app.chess_models import PieceImageClassifier
+
+SIZE, MARGIN = 800, 0.6
+CORNERS = np.array([[520, 140], [1360, 150], [1430, 915], [452, 918]], np.float32)
+TRUE = "rn1qkb1r/pb2pppp/5n2/1ppp4/8/3P1NP1/PPP1PPBP/RNBQ1RK1"
+IDX2SYM = {0:"K",1:"Q",2:"R",3:"B",4:"N",5:"P",6:"k",7:"q",8:"r",9:"b",10:"n",11:"p"}
+IMEAN, ISTD = np.array([0.485,0.456,0.406],np.float32), np.array([0.229,0.224,0.225],np.float32)
+
+# re-export an fp32 digitizer (no quantization) for comparison
+m = PieceImageClassifier()
+ck = torch.load("../Master-of-Science-Degree-Project/Models/imageClassifierReal.pth", map_location="cpu", weights_only=False)
+sd = ck if all(isinstance(v, torch.Tensor) for v in ck.values()) else next(v for v in ck.values() if isinstance(v, dict))
+m.load_state_dict(sd); m.eval()
+torch.onnx.export(m, torch.randn(1,3,96,96), "models_onnx/digitizer.fp32.onnx",
+                  input_names=["input"], output_names=["output"],
+                  dynamic_axes={"input":{0:"b",2:"h",3:"w"}}, opset_version=17, dynamo=False)
+
+def grid_true():
+    g=[]
+    for row in TRUE.split("/"):
+        r=[]
+        for ch in row: r += ["."]*int(ch) if ch.isdigit() else [ch]
+        g.append(r)
+    return g
+
+def crops(img):
+    dst=np.array([[0,0],[SIZE,0],[SIZE,SIZE],[0,SIZE]],np.float32)
+    Minv=cv.getPerspectiveTransform(dst,CORNERS); cell=SIZE/8; out=[]
+    for r in range(8):
+        for c in range(8):
+            y0=(r-MARGIN)*cell
+            q=np.array([[[c*cell,y0],[(c+1)*cell,y0],[(c+1)*cell,(r+1)*cell],[c*cell,(r+1)*cell]]],np.float32)
+            o=cv.perspectiveTransform(q,Minv)[0]; xs,ys=o[:,0],o[:,1]
+            x1,x2=max(0,int(xs.min())),min(img.shape[1],int(xs.max()))
+            y1,y2=max(0,int(ys.min())),min(img.shape[0],int(ys.max()))
+            out.append(img[y1:y2,x1:x2])
+    return out
+
+def norms(bgr):
+    rgb=cv.cvtColor(cv.resize(bgr,(96,96)),cv.COLOR_BGR2RGB).astype(np.float32)
+    return {
+        "/255":            (rgb/255.0).transpose(2,0,1)[None],
+        "imagenet":        ((rgb/255.0-IMEAN)/ISTD).transpose(2,0,1)[None],
+        "raw255":          rgb.transpose(2,0,1)[None],
+        "[-1,1]":          (rgb/127.5-1).transpose(2,0,1)[None],
+    }
+
+img=cv.imread("samples/board.png"); cs=crops(img); true=[s for row in grid_true() for s in row]
+for model in ["digitizer.int8.onnx","digitizer.fp32.onnx"]:
+    sess=ort.InferenceSession(f"models_onnx/{model}",providers=["CPUExecutionProvider"])
+    for nm in ["/255","imagenet","raw255","[-1,1]"]:
+        hits=0; probs=[]
+        for crop,t in zip(cs,true):
+            if crop.size==0: continue
+            x=norms(crop)[nm]
+            out=sess.run(None,{"input":x.astype(np.float32)})[0].flatten()
+            p=np.exp(out)/np.exp(out).sum(); k=int(p.argmax()); probs.append(p[k])
+            if IDX2SYM[k]==t: hits+=1
+        print(f"{model:22s} {nm:9s} match {hits:2d}/64  meanconf {np.mean(probs):.2f}")

requirements-convert.txt

@@ -0,0 +1,6 @@
+# Only needed to convert the .pth models to ONNX (convert_to_onnx.py).
+# The runtime backend does NOT need torch — it serves the ONNX models.
+torch>=2.2
+torchvision>=0.17
+onnx>=1.16
+onnxruntime>=1.18

requirements.txt

@@ -0,0 +1,9 @@
+# Runtime serving stack (no torch — serves the ONNX models).
+fastapi>=0.110
+uvicorn[standard]>=0.29
+onnxruntime>=1.18
+opencv-python-headless>=4.9
+numpy>=1.26
+python-chess>=1.999
+stockfish>=3.28
+python-multipart>=0.0.9