Initial commit

.gitattributes

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

.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+.DS_Store
+venv/
+venv311/
+
+# datasets & training artifacts (regenerable)
+ingredients/
+glyph_data/
+checkpoints/
+train_data/
+train_data2/
+train_data3/
+train_data4/
+train_data5/
+preview*.png
+out/
+project.zip
+
+# archived experiments: keep code, ignore heavy model binaries
+legacy/*.pkl
+legacy/*.pth

.python-version

@@ -0,0 +1 @@
+3.11.8

README.md

@@ -0,0 +1,159 @@
+---
+title: Togyzkumalak Scoresheet Reader
+emoji: ♟️
+colorFrom: indigo
+colorTo: green
+sdk: gradio
+sdk_version: 6.20.0
+app_file: app.py
+pinned: false
+---
+
+# Togyzkumalak Move OCR
+
+Classifies a photo of a single scoresheet cell into one of **163 classes**:
+162 moves (`11` … `99x` — start hole 1–9, end hole 1–9, optional capture `x`)
+plus `empty`. A full-sheet reader turns a whole scoresheet photo into PGN game
+records, and a **Gradio demo** (`app.py`) packages it for a HuggingFace Space.
+
+## Live demo (HuggingFace Space)
+
+`app.py` is a Gradio app: upload up to **5** scoresheet photos, optionally tag
+each game's known result, and download the reconstructed PGNs (beam / raw /
+legal) as a zip. Inference runs on the exported **ONNX** models (torch-free),
+so the Space needs only the light serving deps in `requirements.txt`.
+
+```bash
+python scripts/export_onnx.py     # checkpoints/*.pt -> single-file .onnx (+ .classes.json)
+cp checkpoints/best.onnx checkpoints/best.classes.json models/
+cp checkpoints/kazan/best.onnx models/kazan.onnx
+cp checkpoints/kazan/best.classes.json models/kazan.classes.json
+python app.py                     # serve locally at http://127.0.0.1:7860
+```
+
+Deploy: create a Gradio Space and push this repo to its `origin` remote (the
+`.onnx` files are tracked with Git LFS via `.gitattributes`). The Space reads
+the YAML front-matter above and installs `requirements.txt`. No secrets or
+database are required — it is a stateless demo capped at 5 images per run, with
+requests serialized through Gradio's queue so a busy free Space degrades into a
+short wait rather than 429 errors.
+
+## Why the old pipeline failed (and what this one does differently)
+
+| Problem | Old pipeline | This pipeline |
+|---|---|---|
+| Glyph style | EMNIST (American digits) — but players write **European/Kazakh** digits: crossed 7, serif 1, cursive 9 | ARDIS dataset (real European handwriting) + procedural crossbars/serifs on EMNIST glyphs |
+| Preprocessing | Train and inference normalized **differently** (`0.5/0.5` vs ImageNet stats) | One shared module, `togyz/preprocess.py`, imported by both |
+| Framing | Small digits with wide margins in fixed 80×40 cells | Random framing from tight crops to loose cells, matching real photos |
+| Data | 48 900 fixed PNGs on disk | Infinite on-the-fly synthesis, deterministic validation set |
+
+## Layout
+
+```
+togyz/            core library
+  classes.py      canonical 163-class list (indices match legacy class_mapping.json)
+  preprocess.py   THE single image->tensor preprocessing (train AND inference)
+  glyphs.py       per-character glyph pools + procedural style edits
+  synth.py        cell synthesizer;  python -m togyz.synth --preview preview.png
+  dataset.py      on-the-fly synthetic dataset + real-crop eval dataset
+  model.py        resnet18 (grayscale, 163 outputs), checkpoint helpers
+train.py          training CLI (auto device: cuda/mps/cpu)
+eval.py           synthetic val + per-file real-crop report
+predict.py        classify images; --allowed restricts to legal moves
+scripts/get_glyphs.py   downloads/prepares glyph pools (ARDIS, optional EMNIST)
+data/real_crops/  10 labeled real crops (labels.csv) — evaluation only
+legacy/           previous experiments, kept for reference
+```
+
+## Quickstart (local)
+
+```bash
+source venv311/bin/activate         # or: pip install -r requirements.txt
+python scripts/get_glyphs.py        # one-time: download+prepare ARDIS glyphs
+python -m togyz.synth --preview preview.png   # eyeball synthetic vs data/real_crops
+python train.py --epochs 1 --samples-per-epoch 4000 --batch-size 64   # smoke test
+python eval.py --ckpt checkpoints/best.pt
+python predict.py "data/real_crops/*.jpg"
+```
+
+A real training run needs a GPU — see Colab below. Defaults
+(`--epochs 20 --samples-per-epoch 50000`) are a sensible full run.
+
+## Training on Google Colab (or any GPU machine)
+
+Open `notebooks/colab_train.ipynb` in Colab, or manually:
+
+```bash
+git clone <this-repo> && cd 9OCR        # or upload a zip of the project
+pip install -r requirements.txt
+python scripts/get_glyphs.py --emnist   # ingredients/ is gitignored, so also
+                                        # rebuild the EMNIST pool from torchvision
+python train.py --epochs 30
+# download checkpoints/best.pt when done
+```
+
+`predict.py`/`eval.py` run anywhere (CPU is fine) with the downloaded
+checkpoint.
+
+## Inference
+
+```bash
+python predict.py cell.jpg --topk 3
+python predict.py cell.jpg --allowed "12,34x,56"
+```
+
+At any game state at most 9 moves are legal. If an upstream game tracker
+passes them via `--allowed`, probabilities are renormalized over just those
+moves — a large, free accuracy boost when reading whole games.
+
+## Reading a whole scoresheet
+
+```bash
+python read_game.py "data/2026-07-06 00.00.20.jpg" --out out/sheet1 --result 0-1
+```
+
+Pass `--result` (1-0 / 0-1 / draw, from the sheet footer) when known: the
+beam's final pool is re-ranked to prefer reconstructions whose end state is
+consistent with how the game actually ended.
+
+The summary strips between the tables record both kazan counts every 10
+moves (Black's box above the strip, White's below, always two digits 00-81).
+A second classifier reads them (`python train.py --task kazan`, saved to
+`checkpoints/kazan/best.pt`) and the beam gains likelihood when a
+hypothesis' computed kazans match these written checkpoints.
+
+Finds the 8 printed move tables, classifies every cell, and writes:
+
+- `game.json` — per ply: all 163 class probabilities, top-5, legality info
+- `raw.pgn` — pure classifier argmax per ply, even if illegal
+- `legal.pgn` — strict replay, stops at the first illegal argmax
+- `beam.pgn` — **best reconstruction**: beam search over all legal
+  continuations per ply; each legal move is scored by blending its exact
+  class probability with the probability mass of its source digit
+  (the landing digit is derived from the position, so a misread second
+  digit doesn't discard the right source hole). Longest fully legal
+  sequence wins, ties broken by joint probability.
+- `annotated.jpg`, `cells/` — visual debugging
+
+Move annotations: `+` capture, `x` tuzdyk creation. Strip `+` to feed the
+moves to the 9Q engine. Rules implementation: `togyz/rules.py`, validated
+against the 9Q C++ engine fixture (`python tests/test_rules.py`).
+
+Accuracy depends heavily on photo resolution — the CLI warns when cells are
+under 35 px tall; photograph sheets at full camera resolution.
+
+## Improving accuracy further
+
+1. **Label more real cells** — append rows to `data/real_crops/labels.csv`.
+   Even ~50 real crops make the reported real-crop accuracy meaningful; a few
+   hundred would allow fine-tuning on them.
+2. Add glyph styles: put white-on-black PNG masks under
+   `glyph_data/<source>/<char>/` and register the source in `togyz/glyphs.py`.
+3. Full-game decoding with a Togyzkumalak rules engine (choose the most
+   probable *legal* move per cell) — hook already exists via `--allowed`.
+
+## Notes
+
+- `train_data5/` (the old pre-generated dataset) is no longer used and can be
+  deleted; synthesis now happens on the fly.
+- Old models/scripts live in `legacy/` (`.pkl`/`.pth` files are gitignored).

app.py

@@ -0,0 +1,174 @@
+"""Gradio demo for the Togyzkumalak scoresheet reader (HuggingFace Space).
+
+Upload up to 5 scoresheet photos, optionally tag each with its known result,
+and download the reconstructed PGNs. Inference runs on the exported ONNX
+models (torch-free) via `togyz.pipeline.run_pipeline`.
+
+This is a demo, not production: state is per-session, work is capped at 5
+images per run, and requests are serialized through Gradio's queue so a shared
+free Space degrades into a wait rather than a flurry of 429s.
+"""
+
+import os
+import sys
+import tempfile
+import zipfile
+from pathlib import Path
+
+# Unbuffered stdout so boot progress actually shows in the Space container logs
+# (otherwise a slow import/model-load looks like a silent hang).
+try:
+    sys.stdout.reconfigure(line_buffering=True)
+    sys.stderr.reconfigure(line_buffering=True)
+except Exception:
+    pass
+
+
+def _log(msg):
+    print(f"[app] {msg}", flush=True)
+
+
+_log("importing gradio ...")
+import gradio as gr
+
+_log("importing pipeline ...")
+from togyz.pipeline import load_classifier, run_pipeline
+
+MAX_IMAGES = 5
+MODEL_DIR = Path(__file__).parent / "models"
+RESULT_CHOICES = ["unknown", "1-0", "0-1", "draw"]
+
+# Load the ONNX sessions once at import - warm for the whole process lifetime.
+_log(f"loading move model from {MODEL_DIR / 'best.onnx'} ...")
+_MOVES = load_classifier(MODEL_DIR / "best.onnx")
+_KAZAN = None
+_kazan_path = MODEL_DIR / "kazan.onnx"
+if _kazan_path.exists():
+    _log("loading kazan model ...")
+    _KAZAN = load_classifier(_kazan_path)
+_log("models loaded")
+
+
+def _safe_slug(text: str) -> str:
+    keep = "".join(c if c.isalnum() else "_" for c in (text or "").strip())
+    return keep.strip("_")
+
+
+def _process_one(image_path, result_choice, base_name, out_dir: Path):
+    """Run the pipeline on one image; return (row, gallery_item, pgn_files)."""
+    result = None if result_choice in (None, "unknown") else result_choice
+    out = run_pipeline(image_path, _MOVES, _KAZAN, result=result)
+
+    stop = out["stopped"]
+    stop_txt = stop.get("reason", "")
+    if "winner" in stop:
+        stop_txt += f" ({stop['winner']})"
+    note = " ⚠ low-res" if out["low_resolution"] else ""
+
+    files = []
+    for kind in ("beam", "raw", "legal"):
+        f = out_dir / f"{base_name}_{kind}.pgn"
+        f.write_text(out[f"{kind}_pgn"])
+        files.append(str(f))
+
+    row = [base_name, out["beam_plies"], stop_txt + note, out["beam_pgn"].strip()]
+    caption = f"{base_name}: {out['beam_plies']} plies"
+    return row, (out["annotated_image"], caption), files
+
+
+def convert(round_label, *slot_values):
+    """slot_values = [img1, res1, img2, res2, ...] for the 5 fixed slots."""
+    images = slot_values[0::2]
+    results = slot_values[1::2]
+    provided = [(img, res) for img, res in zip(images, results) if img]
+
+    if not provided:
+        raise gr.Error("Please upload at least one scoresheet image.")
+    if len(provided) > MAX_IMAGES:  # defensive; the UI only exposes 5 slots
+        raise gr.Error(f"This demo handles at most {MAX_IMAGES} images per run.")
+
+    out_dir = Path(tempfile.mkdtemp(prefix="togyz_"))
+    round_slug = _safe_slug(round_label)
+    rows, gallery, all_files = [], [], []
+
+    for i, (img, res) in enumerate(provided, start=1):
+        prefix = f"{round_slug}_table{i}" if round_slug else f"table{i}"
+        try:
+            row, gal, files = _process_one(img, res, prefix, out_dir)
+        except Exception as exc:  # one bad image must not kill the batch
+            rows.append([prefix, 0, f"error: {exc}", ""])
+            continue
+        rows.append(row)
+        gallery.append(gal)
+        all_files.extend(files)
+
+    if not all_files:
+        # every image errored - still return the table so the user sees why
+        return rows, gallery, None
+
+    zip_path = out_dir / (f"{round_slug}_pgns.zip" if round_slug else "pgns.zip")
+    with zipfile.ZipFile(zip_path, "w") as zf:
+        for f in all_files:
+            zf.write(f, arcname=Path(f).name)
+
+    return rows, gallery, str(zip_path)
+
+
+def _busy_wrapper(*args):
+    """Turn infrastructure overload into a friendly message instead of a 500."""
+    try:
+        return convert(*args)
+    except gr.Error:
+        raise
+    except Exception as exc:  # noqa: BLE001 - surface anything else gracefully
+        msg = str(exc).lower()
+        if "429" in msg or "too many" in msg or "rate" in msg:
+            raise gr.Error("Server busy — please retry in a moment.")
+        raise gr.Error(f"Something went wrong: {exc}")
+
+
+with gr.Blocks(title="Togyzkumalak Scoresheet Reader") as demo:
+    gr.Markdown(
+        "# Togyzkumalak Scoresheet Reader\n"
+        "Upload up to **5** scoresheet photos, optionally tag each game's known "
+        "result (improves accuracy), then **Convert** to download the PGNs.\n\n"
+        "Outputs per game: `beam` (best legal reconstruction), `raw` (pure OCR), "
+        "`legal` (strict replay). Free demo — a first run may wake the Space, and "
+        "images are processed one at a time."
+    )
+    round_label = gr.Textbox(label="Round (optional)", placeholder="e.g. 3",
+                             scale=1, max_lines=1)
+
+    slots = []
+    for i in range(MAX_IMAGES):
+        with gr.Row():
+            img = gr.Image(label=f"Table {i + 1}", type="filepath", height=150)
+            res = gr.Dropdown(RESULT_CHOICES, value="unknown",
+                              label="Result (1-0 = White won)", scale=1)
+        slots.extend([img, res])
+
+    convert_btn = gr.Button("Convert", variant="primary")
+
+    results_table = gr.Dataframe(
+        headers=["game", "legal plies", "stopped", "beam PGN"],
+        label="Results", wrap=True, interactive=False,
+    )
+    gallery = gr.Gallery(label="Annotated reconstruction", columns=2, height="auto")
+    zip_out = gr.File(label="Download all PGNs (zip)")
+
+    convert_btn.click(
+        _busy_wrapper,
+        inputs=[round_label, *slots],
+        outputs=[results_table, gallery, zip_out],
+    )
+
+# Serialize CPU-heavy runs: callers wait in a bounded queue instead of
+# overloading the shared Space (which is what triggers 429s).
+demo.queue(max_size=16, default_concurrency_limit=1)
+
+if __name__ == "__main__":
+    # Bind explicitly to 0.0.0.0 and the Space's port so HF can detect the
+    # running app (the default 127.0.0.1 bind can leave a Space stuck "Starting").
+    port = int(os.environ.get("GRADIO_SERVER_PORT", os.environ.get("PORT", 7860)))
+    _log(f"launching gradio on 0.0.0.0:{port} ...")
+    demo.launch(server_name="0.0.0.0", server_port=port)

data/real_crops/labels.csv

@@ -0,0 +1,11 @@
+filename,label
+96_a.jpg,96
+96_b.jpg,96
+77_a.jpg,77
+77_b.jpg,77
+13x_a.jpg,13x
+13x_b.jpg,13x
+37_a.jpg,37
+37_b.jpg,37
+85_a.jpg,85
+42_a.jpg,42

docs/superpowers/specs/2026-07-08-hf-space-gradio-demo-design.md

@@ -0,0 +1,70 @@
+# Togyzkumalak Scoresheet Reader — Gradio demo on a HuggingFace Space
+
+## Context
+
+The OCR pipeline reads a scoresheet photo into PGN records (sheet 1 = 36/39
+exact plies). We want a public, shareable **demo** — not production — where
+anyone with the link uploads a few scoresheet photos and downloads the PGNs.
+
+Hosting is a single **HuggingFace Space running Gradio**. A free Space has
+ample RAM (≈16 GB), so no database and no external services are needed —
+outputs are files downloaded in-session. Constraints: **≤5 images per run**
+and **graceful handling of overload (429)** on shared free compute.
+
+The blocker on smaller hosts was PyTorch (528 MiB peak RAM, 441 MB on disk).
+The fix — kept here because it also makes the Space faster and lighter — is to
+run inference under **onnxruntime + numpy**, dropping torch from the serving
+path (torch stays only for training/export).
+
+## Architecture
+
+```
+HuggingFace Space (Gradio SDK)
+  app.py             UI + handler; loads 2 ONNX sessions once at import
+  togyz/pipeline.py  run_pipeline() — torch-free core, shared with the CLI
+  togyz/{sheet,rules,preprocess,classes}.py   already torch-free
+  models/*.onnx      committed via Git LFS (+ .classes.json sidecars)
+  requirements.txt   serving deps (torch-free); requirements-train.txt for training
+```
+
+## Key decisions
+
+- **onnxruntime + numpy inference.** `togyz/preprocess.py` returns numpy;
+  `togyz/pipeline.py` reimplements cell classification, legal-move scoring,
+  kazan evidence, and beam search with numpy. Verified **byte-identical**
+  `beam.pgn` vs the torch baseline on both sample sheets. Peak RAM 394 MiB
+  (was 528), wall time 8.8 s (was 12.9).
+- **Single-file ONNX.** `scripts/export_onnx.py` uses the legacy exporter
+  (`dynamo=False`) + `onnx.save_model(save_as_external_data=False)` so each
+  model is one self-contained ~45 MB `.onnx` (no `.data` sidecar) — clean for
+  Git LFS. Class list saved as a `<stem>.classes.json` sidecar.
+- **Fixed 5 slots** (image + result dropdown each) structurally enforce the
+  5-image cap and give unambiguous per-game result tagging. Result improves
+  accuracy via the beam's end-state re-ranking; `unknown` → no hint.
+- **Graceful overload.** `demo.queue(default_concurrency_limit=1, max_size=16)`
+  serializes CPU-heavy runs so callers wait rather than triggering 429s; a
+  `_busy_wrapper` maps any 429/rate error to a friendly `gr.Error`.
+- **Per-image isolation.** Each image runs in `try/except`; a failure reports
+  an error row and the batch continues.
+
+## Outputs
+
+Per game: `beam` (best legal reconstruction), `raw` (pure OCR argmax), `legal`
+(strict replay) PGNs, plus an annotated preview image. All PGNs are bundled
+into a downloadable zip; filenames use the optional round label
+(`R3_table1_beam.pgn`).
+
+## Verification (all passed)
+
+1. ONNX parity: `beam.pgn` identical to torch on both sheets.
+2. RAM 394 MiB / 8.8 s per image via the ONNX CLI.
+3. `app.convert()` headless on both samples → 39 + 77 plies, zip with 6 PGNs,
+   beam matches the CLI.
+4. Resilience: a table-less image reports an error row while the good image
+   still produces output.
+
+## Out of scope (demo)
+
+Batches >5, persistence/history, auth, tournament round/table auto-detection.
+Larger production hosting (Render/Supabase/Vercel) was considered and dropped
+in favor of this single-Space demo.

eval.py

@@ -0,0 +1,72 @@
+"""Evaluate a checkpoint on the synthetic validation set and the real crops.
+
+    python eval.py --ckpt checkpoints/best.pt
+"""
+
+import argparse
+
+import torch
+from torch.utils.data import DataLoader
+
+from togyz.dataset import RealCropDataset, SyntheticCellDataset
+from togyz.model import auto_device, load_checkpoint
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--ckpt", default="checkpoints/best.pt")
+    parser.add_argument("--val-size", type=int, default=4_000)
+    parser.add_argument("--batch-size", type=int, default=128)
+    parser.add_argument("--workers", type=int, default=4)
+    parser.add_argument("--device", default=None)
+    args = parser.parse_args()
+
+    device = torch.device(args.device) if args.device else auto_device()
+    model, ckpt = load_checkpoint(args.ckpt, device)
+    classes = ckpt["classes"]
+    print(f"Loaded {args.ckpt} (epoch {ckpt['epoch'] + 1}, synth val {ckpt['val_acc']:.2%})")
+
+    # synthetic validation (same fixed seed as train.py)
+    val_loader = DataLoader(
+        SyntheticCellDataset(args.val_size, seed=1234),
+        batch_size=args.batch_size,
+        num_workers=args.workers,
+    )
+    correct = total = 0
+    with torch.no_grad():
+        for images, labels in val_loader:
+            preds = model(images.to(device)).argmax(dim=1).cpu()
+            correct += (preds == labels).sum().item()
+            total += labels.numel()
+    print(f"Synthetic val accuracy: {correct / total:.2%} ({total} samples)")
+
+    # real crops with per-file report
+    real = RealCropDataset()
+    if len(real) == 0:
+        print("No real crops found in data/real_crops - skipping.")
+        return
+    images, labels, names = real.batch()
+    with torch.no_grad():
+        probs = torch.softmax(model(images.to(device)).cpu(), dim=1)
+    topk = probs.topk(3, dim=1)
+
+    print(f"\nReal crops ({len(real)} files):")
+    top1 = top3 = 0
+    for i, name in enumerate(names):
+        truth = classes[labels[i]]
+        guesses = [
+            f"{classes[idx]} {p:.1%}"
+            for idx, p in zip(topk.indices[i].tolist(), topk.values[i].tolist())
+        ]
+        hit1 = topk.indices[i, 0] == labels[i]
+        hit3 = (topk.indices[i] == labels[i]).any()
+        top1 += int(hit1)
+        top3 += int(hit3)
+        marker = "OK " if hit1 else ("~3 " if hit3 else "MISS")
+        print(f"  [{marker}] {name:<14} truth={truth:<4} top3: {', '.join(guesses)}")
+    print(f"Real top-1: {top1}/{len(real)} ({top1 / len(real):.0%})  "
+          f"top-3: {top3}/{len(real)} ({top3 / len(real):.0%})")
+
+
+if __name__ == "__main__":
+    main()

legacy/a.py

@@ -0,0 +1,43 @@
+import os
+import torchvision
+from PIL import Image
+
+# 1. Create the folder structure
+base_dir = "ingredients"
+classes_we_want = {
+    1: "1", 2: "2", 3: "3", 4: "4", 5: "5", 
+    6: "6", 7: "7", 8: "8", 9: "9", 33: "x"
+}
+
+for folder_name in classes_we_want.values():
+    os.makedirs(os.path.join(base_dir, folder_name), exist_ok=True)
+
+# 2. Load the dataset
+dataset = torchvision.datasets.EMNIST(root='./data', split='balanced', train=True, download=True)
+
+print("Extracting and FIXING rotation... please wait.")
+
+counts = {k: 0 for k in classes_we_want.keys()}
+limit_per_class = 2000 
+
+for i in range(len(dataset)):
+    img, label = dataset[i] # img is a PIL Image
+    
+    if label in classes_we_want:
+        if counts[label] < limit_per_class:
+            label_name = classes_we_want[label]
+            file_path = os.path.join(base_dir, label_name, f"{label_name}_{counts[label]}.png")
+            
+            # --- THE FIX ---
+            # EMNIST is stored (width, height) instead of (height, width)
+            # We transpose it to make it human-readable
+            fixed_img = img.transpose(Image.TRANSPOSE)
+            # ---------------
+            
+            fixed_img.save(file_path)
+            counts[label] += 1
+
+    if all(c >= limit_per_class for c in counts.values()):
+        break
+
+print("Success! Check your 'ingredients' folder now. They should be upright.")

legacy/b.py

@@ -0,0 +1,93 @@
+import os
+import random
+import glob
+import numpy as np
+from PIL import Image, ImageOps, ImageFilter
+
+# --- CONFIGURATION ---
+INGREDIENTS_PATH = "ingredients"
+OUTPUT_PATH = "train_data"
+BOX_HEIGHT = 40
+BOX_WIDTH = 120  # 3:1 Proportion
+SAMPLES_PER_CLASS = 300 # Adjust based on your disk space
+
+# 1. Generate the 163 Class Names
+# Format: "72" (no x) or "72x" (with x)
+move_classes = []
+for start_hole in range(1, 10):
+    for end_hole in range(1, 10):
+        move_classes.append(f"{start_hole}{end_hole}")   # e.g., "72"
+        move_classes.append(f"{start_hole}{end_hole}x")  # e.g., "72x"
+
+classes = move_classes + ['empty']
+
+os.makedirs(OUTPUT_PATH, exist_ok=True)
+
+def get_random_ingredient(char):
+    # char will be '1'-'9' or 'x'
+    files = glob.glob(os.path.join(INGREDIENTS_PATH, char, "*.png"))
+    if not files:
+        raise ValueError(f"No images found for character: {char}")
+    return Image.open(random.choice(files))
+
+def create_move_image(class_name):
+    # 1. Create the 3:1 paper background (light gray/off-white)
+    bg_color = random.randint(220, 250) 
+    img = Image.new('L', (BOX_WIDTH, BOX_HEIGHT), color=bg_color)
+    
+    if class_name == 'empty':
+        return img
+
+    chars_to_draw = list(class_name)
+    
+    for slot in range(len(chars_to_draw)):
+        char = chars_to_draw[slot]
+        char_img = get_random_ingredient(char) # This is White-on-Black
+        
+        # Resize
+        size = random.randint(28, 36)
+        char_img = char_img.resize((size, size), Image.Resampling.LANCZOS)
+        
+        # Rotate
+        char_img = char_img.rotate(random.randint(-10, 10), expand=False, fillcolor=0)
+
+        # --- THE FIX: MASKED PASTING ---
+        # Instead of inverting the whole square, we use the original 
+        # White-on-Black image as a "mask". 
+        
+        # Create a solid black square of the same size
+        ink_color = random.randint(0, 50) # Dark gray to black ink
+        ink_layer = Image.new('L', (size, size), color=ink_color)
+        
+        # Position
+        slot_center_x = (slot * 40) + 20
+        paste_x = slot_center_x - (size // 2) + random.randint(-4, 4)
+        paste_y = (BOX_HEIGHT // 2) - (size // 2) + random.randint(-3, 3)
+        
+        # We paste the "ink_layer" onto the "img" ONLY where "char_img" is white.
+        img.paste(ink_layer, (paste_x, paste_y), mask=char_img)
+
+    # 4. Final touch: Add a little bit of noise to the whole box
+    # This makes the "pure" background look more like paper texture
+    arr = np.array(img)
+    noise = np.random.randint(-5, 5, arr.shape)
+    arr = np.clip(arr + noise, 0, 255).astype(np.uint8)
+    
+    return Image.fromarray(arr)
+
+# --- EXECUTION ---
+print(f"Generating {len(classes)} classes...")
+
+for cls in classes:
+    class_dir = os.path.join(OUTPUT_PATH, cls)
+    os.makedirs(class_dir, exist_ok=True)
+    
+    # Use fewer samples if you are just testing, increase for final training
+    for i in range(SAMPLES_PER_CLASS):
+        box_img = create_move_image(cls)
+        # We save as '72x_1.png' etc.
+        box_img.save(os.path.join(class_dir, f"{cls}_{i}.png"))
+    
+    print(f"Class {cls} generated.")
+
+print(f"\nSuccess! Generated {len(classes)} folders in {OUTPUT_PATH}")

legacy/b2.py

@@ -0,0 +1,124 @@
+import os
+import random
+import glob
+import numpy as np
+from PIL import Image, ImageOps, ImageFilter
+import cv2
+# --- CONFIGURATION ---
+INGREDIENTS_PATH = "ingredients"
+OUTPUT_PATH = "train_data2"
+BOX_HEIGHT = 40
+BOX_WIDTH = 120  # 3:1 Proportion
+SAMPLES_PER_CLASS = 300 # Adjust based on your disk space
+
+# 1. Generate the 163 Class Names
+move_classes = []
+for start_hole in range(1, 10):
+    for end_hole in range(1, 10):
+        move_classes.append(f"{start_hole}{end_hole}")   # e.g., "72"
+        move_classes.append(f"{start_hole}{end_hole}x")  # e.g., "72x"
+
+classes = move_classes + ['empty']
+
+os.makedirs(OUTPUT_PATH, exist_ok=True)
+
+def get_random_ingredient(char):
+    files = glob.glob(os.path.join(INGREDIENTS_PATH, char, "*.png"))
+    if not files:
+        raise ValueError(f"No images found for character: {char}")
+    return Image.open(random.choice(files))
+
+def create_move_image(class_name):
+    # 1. Create a pure, solid white paper background (255)
+    # This matches the clean white background of the post-processed real photos
+    img = Image.new('L', (BOX_WIDTH, BOX_HEIGHT), color=255)
+    
+    if class_name == 'empty':
+        return img
+
+    chars_to_draw = list(class_name)
+    prepared_chars = []
+    total_width = 0
+    gaps = []
+
+    # --- STEP 1: PREPARE AND MEASURE ALL CHARACTERS ---
+    for i, char in enumerate(chars_to_draw):
+        char_img = get_random_ingredient(char)
+        
+        # Make 'x' slightly smaller than numbers
+        if char == 'x':
+            size = random.randint(20, 26)
+        else:
+            size = random.randint(28, 36)
+            
+        char_img = char_img.resize((size, size), Image.Resampling.LANCZOS)
+        char_img = char_img.rotate(random.randint(-10, 10), expand=False, fillcolor=0)
+        
+        # Crop the black space around the EMNIST digit
+        bbox = char_img.getbbox()
+        if bbox:
+            char_img = char_img.crop(bbox)
+            
+        prepared_chars.append(char_img)
+        total_width += char_img.width
+        
+        # Calculate random gap
+        if i < len(chars_to_draw) - 1:
+            gap = random.randint(-2, 5) 
+            gaps.append(gap)
+            total_width += gap
+
+    # --- STEP 2: RANDOM TRANSLATION ---
+    max_start_x = BOX_WIDTH - total_width
+    if max_start_x <= 2: 
+        start_x = 2 
+    else:
+        start_x = random.randint(2, max_start_x - 2)
+
+    # --- STEP 3: PASTE THE CHARACTERS (Using Solid Black Ink) ---
+    current_x = start_x
+    for i, char_img in enumerate(prepared_chars):
+        # We use solid pure black ink (0) to match post-threshold images
+        ink_layer = Image.new('L', char_img.size, color=0)
+        
+        max_y = BOX_HEIGHT - char_img.height
+        paste_y = random.randint(2, max(2, max_y - 2))
+        
+        img.paste(ink_layer, (current_x, paste_y), mask=char_img)
+        
+        if i < len(gaps):
+            current_x += char_img.width + gaps[i]
+
+    # --- STEP 4: DILATION ALIGNMENT ---
+    # Convert to numpy array for OpenCV
+    arr = np.array(img)
+    
+    # Invert the image so the ink is white (required for dilation)
+    ink_is_white = cv2.bitwise_not(arr)
+    
+    # Apply a 3x3 dilation kernel to thicken the strokes
+    # This matches the dilated thickness of the real-world processed pen strokes!
+    kernel = np.ones((3,3), np.uint8)
+    thick_ink = cv2.dilate(ink_is_white, kernel, iterations=1)
+    
+    # Invert back: Ink is Black (0), Background is Pure White (255)
+    final_img = cv2.bitwise_not(thick_ink)
+
+    return Image.fromarray(final_img)
+
+# --- EXECUTION ---
+print(f"Generating {len(classes)} classes with Dynamic Spacing...")
+
+for cls in classes:
+    class_dir = os.path.join(OUTPUT_PATH, cls)
+    os.makedirs(class_dir, exist_ok=True)
+    
+    for i in range(SAMPLES_PER_CLASS):
+        box_img = create_move_image(cls)
+        box_img.save(os.path.join(class_dir, f"{cls}_{i}.png"))
+    
+    # Optional print to track progress
+    if (classes.index(cls) + 1) % 10 == 0:
+        print(f"Generated {classes.index(cls) + 1}/{len(classes)} classes...")
+
+print(f"\nSuccess! Generated {len(classes)} folders in {OUTPUT_PATH}")

legacy/b3.py

@@ -0,0 +1,80 @@
+import os
+import random
+import glob
+import numpy as np
+from PIL import Image, ImageFilter
+import cv2
+
+INGREDIENTS_PATH = "ingredients"
+OUTPUT_PATH = "train_data2"
+BOX_HEIGHT = 40
+BOX_WIDTH = 80
+SAMPLES_PER_CLASS = 300 
+
+move_classes = [f"{s}{e}" for s in range(1, 10) for e in range(1, 10)] + \
+               [f"{s}{e}x" for s in range(1, 10) for e in range(1, 10)]
+classes = move_classes + ['empty']
+
+os.makedirs(OUTPUT_PATH, exist_ok=True)
+
+def crop_and_center_ink(cv2_gray_img, target_w=80, target_h=40, margin=4):
+    ink_mask = cv2.bitwise_not(cv2_gray_img)
+    coords = cv2.findNonZero(ink_mask)
+    if coords is not None:
+        x, y, w, h = cv2.boundingRect(coords)
+        crop = cv2_gray_img[y:y+h, x:x+w]
+        scale = min((target_w - 2*margin) / w, (target_h - 2*margin) / h)
+        new_w, new_h = max(1, int(w * scale)), max(1, int(h * scale))
+        resized_crop = cv2.resize(crop, (new_w, new_h), interpolation=cv2.INTER_AREA)
+        canvas = np.full((target_h, target_w), 255, dtype=np.uint8)
+        start_x, start_y = (target_w - new_w) // 2, (target_h - new_h) // 2
+        canvas[start_y:start_y+new_h, start_x:start_x+new_w] = resized_crop
+        return canvas
+    return np.full((target_h, target_w), 255, dtype=np.uint8)
+
+def create_move_image(class_name):
+    if class_name == 'empty':
+        return Image.new('L', (BOX_WIDTH, BOX_HEIGHT), color=255)
+
+    # Start with a clean canvas
+    img = Image.new('L', (200, 200), color=255)
+    current_x = 40 
+    for char in class_name:
+        files = glob.glob(os.path.join(INGREDIENTS_PATH, char, "*.png"))
+        char_img = Image.open(random.choice(files))
+        size = random.randint(22, 28) if char == 'x' else random.randint(32, 42)
+        char_img = char_img.resize((size, size), Image.Resampling.LANCZOS)
+        char_img = char_img.rotate(random.randint(-12, 12), expand=True, fillcolor=0)
+        bbox = char_img.getbbox()
+        if bbox: char_img = char_img.crop(bbox)
+        
+        ink_layer = Image.new('L', char_img.size, color=0)
+        paste_y = 100 - (char_img.height // 2) + random.randint(-5, 5)
+        img.paste(ink_layer, (current_x, paste_y), mask=char_img)
+        current_x += char_img.width + random.randint(-1, 4)
+
+    # --- THE CRITICAL FIX: Center FIRST, then Dilate ---
+    temp_arr = np.array(img)
+    centered = crop_and_center_ink(temp_arr, BOX_WIDTH, BOX_HEIGHT)
+    
+    # Randomly vary thickness (Some thin, some thick)
+    ink_is_white = cv2.bitwise_not(centered)
+    thickness = random.choice([1, 2, 2]) # Weight it towards thicker lines
+    kernel = np.ones((thickness, thickness), np.uint8)
+    thick_ink = cv2.dilate(ink_is_white, kernel, iterations=1)
+    
+    # Add a tiny bit of blur/noise to simulate real camera focus
+    final_img = cv2.bitwise_not(thick_ink)
+    pil_final = Image.fromarray(final_img)
+    if random.random() > 0.5:
+        pil_final = pil_final.filter(ImageFilter.GaussianBlur(radius=0.3))
+        
+    return pil_final
+
+# ... Execution loop remains same as previous ...
+print("Generating centered data with variable thickness...")
+for cls in classes:
+    class_dir = os.path.join(OUTPUT_PATH, cls)
+    os.makedirs(class_dir, exist_ok=True)
+    for i in range(SAMPLES_PER_CLASS):
+        create_move_image(cls).save(os.path.join(class_dir, f"{cls}_{i}.png"))

legacy/b4.py

@@ -0,0 +1,143 @@
+import os
+import random
+import glob
+import numpy as np
+from PIL import Image, ImageFilter
+import cv2
+
+# --- CONFIGURATION ---
+INGREDIENTS_PATH = "ingredients"
+OUTPUT_PATH = "train_data5"
+BOX_HEIGHT = 40
+BOX_WIDTH = 80  
+SAMPLES_PER_CLASS = 300 
+
+# 1. Generate the 163 Class Names
+move_classes = []
+for start_hole in range(1, 10):
+    for end_hole in range(1, 10):
+        move_classes.append(f"{start_hole}{end_hole}")   
+        move_classes.append(f"{start_hole}{end_hole}x")  
+
+classes = move_classes + ['empty']
+os.makedirs(OUTPUT_PATH, exist_ok=True)
+
+def get_random_ingredient(char):
+    files = glob.glob(os.path.join(INGREDIENTS_PATH, char, "*.png"))
+    if not files:
+        raise ValueError(f"No images found for character: {char}")
+    # Convert to grayscale to act perfectly as an alpha mask
+    return Image.open(random.choice(files)).convert('L')
+
+def add_camera_noise(img_array):
+    """Simulates rough paper texture and camera sensor noise"""
+    noise = np.random.randint(0, 25, img_array.shape, dtype='uint8')
+    # Subtracting noise makes random pixels slightly darker, like paper grain
+    noisy_img = np.clip(img_array.astype(int) - noise, 0, 255).astype('uint8')
+    return noisy_img
+
+def create_move_image(class_name):
+    # --- PHILOSOPHY 1: IMPERFECT PAPER BACKGROUND ---
+    # Random RGB values mimicking paper under different lighting (off-white, warm, cool)
+    bg_gray = random.randint(200, 255)
+
+    img = Image.new('L', (BOX_WIDTH, BOX_HEIGHT), color=bg_gray)
+    
+    if class_name == 'empty':
+        img_arr = add_camera_noise(np.array(img))
+        img = Image.fromarray(img_arr)
+        return img.filter(ImageFilter.GaussianBlur(radius=random.uniform(0.1, 0.5)))
+
+    # --- PHILOSOPHY 2: REAL PEN INK COLORS ---
+    # Randomly pick black, dark blue, or bright blue ink
+
+    ink_color = random.choice([0,15,30,45])
+
+    chars_to_draw = list(class_name)
+    prepared_chars = []
+    total_width = 0
+    gaps = []
+
+    for i, char in enumerate(chars_to_draw):
+        char_img = get_random_ingredient(char)
+        
+        # Sizing
+        size = random.randint(14, 18) if char == 'x' else random.randint(20, 26)
+        char_img = char_img.resize((size, size), Image.Resampling.LANCZOS)
+        
+        # Rotation
+        char_img = char_img.rotate(random.randint(-15, 15), expand=True, fillcolor=0)
+        
+        # --- PHILOSOPHY 3: VARIABLE PEN PRESSURE ---
+        # Randomly thicken or thin the stroke using morphology
+        char_arr = np.array(char_img)
+        kernel = np.ones((2, 2), np.uint8)
+        thickness_op = random.choice(['dilate', 'erode', 'none', 'dilate']) # Bias slightly towards thicker
+        
+        if thickness_op == 'dilate':
+            char_arr = cv2.dilate(char_arr, kernel, iterations=1)
+        elif thickness_op == 'erode':
+            char_arr = cv2.erode(char_arr, kernel, iterations=1)
+            
+        char_img = Image.fromarray(char_arr)
+
+        # Crop tight around the character
+        bbox = char_img.getbbox()
+        if bbox:
+            char_img = char_img.crop(bbox)
+            
+        prepared_chars.append(char_img)
+        total_width += char_img.width
+        
+        # Gaps (Allowing negative numbers means strokes might overlap naturally!)
+        if i < len(chars_to_draw) - 1:
+            gap = random.randint(-6, 1) 
+            gaps.append(gap)
+            total_width += gap
+
+    # Translation
+    max_start_x = BOX_WIDTH - total_width
+    start_x = random.randint(2, max(2, max_start_x - 2))
+
+    # Paste using the EMNIST mask
+    current_x = start_x
+    for i, char_mask in enumerate(prepared_chars):
+        # Create a solid block of our chosen ink color
+        ink_layer = Image.new('RGB', char_mask.size, color=ink_color)
+        
+        max_y = BOX_HEIGHT - char_mask.height
+        paste_y = random.randint(1, max(1, max_y - 1))
+        
+        # Paste the ink onto the paper, using the white EMNIST digit as the stencil
+        img.paste(ink_layer, (current_x, paste_y), mask=char_mask)
+        
+        if i < len(gaps):
+            current_x += char_mask.width + gaps[i]
+
+    # --- PHILOSOPHY 4: THE "DIRTY" REALITY ---
+    # 1. Add noise
+    img_arr = np.array(img)
+    img_arr = add_camera_noise(img_arr)
+    final_img = Image.fromarray(img_arr)
+    
+    # 2. Add random camera blur
+    blur_radius = random.uniform(0.1, 0.8)
+    final_img = final_img.filter(ImageFilter.GaussianBlur(radius=blur_radius))
+
+    return final_img
+
+# --- EXECUTION ---
+print(f"Generating {len(classes)} classes with Real-World Domain Shift...")
+
+for cls in classes:
+    class_dir = os.path.join(OUTPUT_PATH, cls)
+    os.makedirs(class_dir, exist_ok=True)
+    
+    for i in range(SAMPLES_PER_CLASS):
+        box_img = create_move_image(cls)
+        box_img.save(os.path.join(class_dir, f"{cls}_{i}.png"))
+    
+    if (classes.index(cls) + 1) % 10 == 0:
+        print(f"Generated {classes.index(cls) + 1}/{len(classes)} classes...")
+
+print(f"\nSuccess! Generated highly robust dataset in {OUTPUT_PATH}")

legacy/book.txt

@@ -0,0 +1,8 @@
+1. 98 11 K1:10 K2:10 K3:20 T:00
+1. 98 22 K1:10 K2:10 K3:20 T:00
+1. 98 33 K1:10 K2:10 K3:20 T:00
+1. 98 44 K1:10 K2:10 K3:20 T:00
+1. 98 55 K1:10 K2:10 K3:20 T:00
+1. 98 66 K1:10 K2:10 K3:20 T:00
+1. 98 77 K1:10 K2:10 K3:20 T:00
+1. 98 98 K1:10 K2:10 K3:20 T:00

legacy/c.py

@@ -0,0 +1,108 @@
+import torch
+import torch.nn as nn
+import torch.optim as optim
+from torchvision import datasets, transforms, models
+from torch.utils.data import DataLoader, random_split
+import json
+import os
+import time
+
+# 1. HYPERPARAMETERS
+BATCH_SIZE = 256
+EPOCHS = 6 # Lowered to 6 because you were already at 95% by epoch 2!
+LEARNING_RATE = 0.001
+DATA_DIR = "train_data3" 
+
+def main():
+    if torch.cuda.is_available():
+        device = torch.device("cuda")
+        use_pin_memory = True
+    elif torch.backends.mps.is_available():
+        device = torch.device("mps") # Apple Silicon Mac!
+        use_pin_memory = False       # MPS doesn't support pin_memory yet
+    else:
+        device = torch.device("cpu")
+        use_pin_memory = False
+        
+    print(f"Using device: {device}")
+
+    # 2. DATA TRANSFORMATIONS 
+    # Change THIS line in c.py before you retrain!
+    transform = transforms.Compose([
+        transforms.Resize((40, 80)),  # <--- Changed from 120 to 80
+        transforms.ColorJitter(brightness=0.2, contrast=0.2), 
+        transforms.ToTensor(),
+        transforms.Normalize(mean=[0.5, 0.5, 0.5], std=[0.5, 0.5, 0.5]) 
+    ])
+
+    # 3. LOAD DATASET
+    print("Loading dataset...")
+    full_dataset = datasets.ImageFolder(root=DATA_DIR, transform=transform)
+    NUM_CLASSES = len(full_dataset.classes)
+    class_names = full_dataset.classes
+
+    print(f"Total classes detected: {NUM_CLASSES}")
+    
+    with open("class_mapping.json", "w") as f:
+        json.dump(full_dataset.class_to_idx, f)
+    print("Class mapping saved to class_mapping.json")
+
+    # 4. TRAIN/VALIDATION SPLIT
+    train_size = int(0.8 * len(full_dataset))
+    val_size = len(full_dataset) - train_size
+    train_dataset, val_dataset = random_split(full_dataset, [train_size, val_size])
+
+    # The workers are safely spawned now!
+    train_loader = DataLoader(train_dataset, batch_size=BATCH_SIZE, shuffle=True, 
+                              num_workers=4, pin_memory=use_pin_memory)
+    val_loader = DataLoader(val_dataset, batch_size=BATCH_SIZE, shuffle=False, 
+                            num_workers=4, pin_memory=use_pin_memory)
+
+    # 5. INITIALIZE ResNet-18
+    model = models.resnet18(weights=None)
+    num_ftrs = model.fc.in_features
+    model.fc = nn.Linear(num_ftrs, NUM_CLASSES)
+    model = model.to(device)
+
+    # 6. LOSS AND OPTIMIZER
+    criterion = nn.CrossEntropyLoss()
+    optimizer = optim.Adam(model.parameters(), lr=LEARNING_RATE)
+
+    # 7. TRAINING LOOP
+    print("Starting training...")
+    start_time = time.time()
+    
+    for epoch in range(EPOCHS):
+        model.train()
+        running_loss = 0.0
+        for images, labels in train_loader:
+            images, labels = images.to(device), labels.to(device)
+            optimizer.zero_grad()
+            outputs = model(images)
+            loss = criterion(outputs, labels)
+            loss.backward()
+            optimizer.step()
+            running_loss += loss.item()
+        
+        # VALIDATION
+        model.eval()
+        correct = 0
+        total = 0
+        with torch.no_grad():
+            for images, labels in val_loader:
+                images, labels = images.to(device), labels.to(device)
+                outputs = model(images)
+                _, predicted = torch.max(outputs.data, 1)
+                total += labels.size(0)
+                correct += (predicted == labels).sum().item()
+                
+        elapsed = time.time() - start_time
+        print(f"[{elapsed:.2f}s] Epoch [{epoch+1}/{EPOCHS}] Loss: {running_loss/len(train_loader):.4f} Val Acc: {100*correct/total:.2f}%")
+
+    # 8. SAVE MODEL
+    torch.save(model.state_dict(), "togyzkumalak_model.pth")
+    print("Model saved to togyzkumalak_model.pth. Done!")
+
+# THIS IS THE MAGIC LINE THAT FIXES THE CRASH
+if __name__ == '__main__':
+    main()

legacy/class_mapping.json

@@ -0,0 +1 @@
+{"11": 0, "11x": 1, "12": 2, "12x": 3, "13": 4, "13x": 5, "14": 6, "14x": 7, "15": 8, "15x": 9, "16": 10, "16x": 11, "17": 12, "17x": 13, "18": 14, "18x": 15, "19": 16, "19x": 17, "21": 18, "21x": 19, "22": 20, "22x": 21, "23": 22, "23x": 23, "24": 24, "24x": 25, "25": 26, "25x": 27, "26": 28, "26x": 29, "27": 30, "27x": 31, "28": 32, "28x": 33, "29": 34, "29x": 35, "31": 36, "31x": 37, "32": 38, "32x": 39, "33": 40, "33x": 41, "34": 42, "34x": 43, "35": 44, "35x": 45, "36": 46, "36x": 47, "37": 48, "37x": 49, "38": 50, "38x": 51, "39": 52, "39x": 53, "41": 54, "41x": 55, "42": 56, "42x": 57, "43": 58, "43x": 59, "44": 60, "44x": 61, "45": 62, "45x": 63, "46": 64, "46x": 65, "47": 66, "47x": 67, "48": 68, "48x": 69, "49": 70, "49x": 71, "51": 72, "51x": 73, "52": 74, "52x": 75, "53": 76, "53x": 77, "54": 78, "54x": 79, "55": 80, "55x": 81, "56": 82, "56x": 83, "57": 84, "57x": 85, "58": 86, "58x": 87, "59": 88, "59x": 89, "61": 90, "61x": 91, "62": 92, "62x": 93, "63": 94, "63x": 95, "64": 96, "64x": 97, "65": 98, "65x": 99, "66": 100, "66x": 101, "67": 102, "67x": 103, "68": 104, "68x": 105, "69": 106, "69x": 107, "71": 108, "71x": 109, "72": 110, "72x": 111, "73": 112, "73x": 113, "74": 114, "74x": 115, "75": 116, "75x": 117, "76": 118, "76x": 119, "77": 120, "77x": 121, "78": 122, "78x": 123, "79": 124, "79x": 125, "81": 126, "81x": 127, "82": 128, "82x": 129, "83": 130, "83x": 131, "84": 132, "84x": 133, "85": 134, "85x": 135, "86": 136, "86x": 137, "87": 138, "87x": 139, "88": 140, "88x": 141, "89": 142, "89x": 143, "91": 144, "91x": 145, "92": 146, "92x": 147, "93": 148, "93x": 149, "94": 150, "94x": 151, "95": 152, "95x": 153, "96": 154, "96x": 155, "97": 156, "97x": 157, "98": 158, "98x": 159, "99": 160, "99x": 161, "empty": 162}

legacy/d.py

@@ -0,0 +1,64 @@
+import torch
+import torch.nn as nn
+from torchvision import transforms, models
+from PIL import Image
+import json
+import sys
+
+def main(image_path):
+    # 1. SETUP DEVICE
+    if torch.backends.mps.is_available():
+        device = torch.device("mps")
+    elif torch.cuda.is_available():
+        device = torch.device("cuda")
+    else:
+        device = torch.device("cpu")
+
+    # 2. LOAD CLASS MAPPING
+    # Reverse the mapping from { "19x": 5 } to { 5: "19x" }
+    with open("class_mapping.json", "r") as f:
+        class_to_idx = json.load(f)
+    idx_to_class = {v: k for k, v in class_to_idx.items()}
+    NUM_CLASSES = len(idx_to_class)
+
+    # 3. LOAD THE MODEL
+    model = models.resnet18(weights=None)
+    num_ftrs = model.fc.in_features
+    model.fc = nn.Linear(num_ftrs, NUM_CLASSES)
+    model.load_state_dict(torch.load("togyzkumalak_model.pth", map_location=device))
+    model = model.to(device)
+    model.eval() # Set to evaluation mode!
+
+    # 4. PREPARE THE IMAGE
+    # Notice we removed ColorJitter because we don't augment during inference!
+    transform = transforms.Compose([
+        transforms.Resize((40, 120)),
+        transforms.ToTensor(),
+        transforms.Normalize(mean=[0.5, 0.5, 0.5], std=[0.5, 0.5, 0.5]) 
+    ])
+
+    image = Image.open(image_path).convert('RGB') # Ensure it's 3-channel
+    image_tensor = transform(image).unsqueeze(0).to(device) # Add batch dimension
+
+    # 5. PREDICT
+    with torch.no_grad():
+        outputs = model(image_tensor)
+        # Apply Softmax to convert raw logits into percentages (0 to 1)
+        probabilities = torch.nn.functional.softmax(outputs[0], dim=0)
+
+    # 6. GET TOP 3 PREDICTIONS
+    top_probs, top_classes = torch.topk(probabilities, 3)
+
+    print(f"\n--- AI PREDICTIONS FOR '{image_path}' ---")
+    for i in range(3):
+        prob = top_probs[i].item() * 100
+        class_idx = top_classes[i].item()
+        class_name = idx_to_class[class_idx]
+        print(f"Choice {i+1}: Move '{class_name}' with {prob:.2f}% confidence")
+    print("------------------------------------------\n")
+
+if __name__ == '__main__':
+    if len(sys.argv) < 2:
+        print("Usage: python predict.py <path_to_image>")
+    else:
+        main(sys.argv[1])

legacy/d2.py

@@ -0,0 +1,118 @@
+import torch
+import torch.nn as nn
+from torchvision import transforms, models
+from PIL import Image, ImageOps
+import json
+import sys
+import cv2
+import numpy as np
+
+def preprocess_for_ai(image_path):
+    img = cv2.imread(image_path)
+    if img is None:
+        print(f"Error: Could not read image at {image_path}")
+        sys.exit(1)
+
+    # 1. Convert to Grayscale
+    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+
+    # 2. Gaussian Blur (Smooths out paper texture before thresholding)
+    blurred = cv2.GaussianBlur(gray, (5, 5), 0)
+
+    # 3. FIX HOLLOW LINES: Increase block size to 35, constant to 10.
+    # This forces it to see the whole pen stroke, not just the edges!
+    # 1. Lower the constant from 10 to 5 (This tells the math: "Don't be so aggressive at deleting faint ink!")
+    thresh = cv2.adaptiveThreshold(
+        blurred, 255, 
+        cv2.ADAPTIVE_THRESH_GAUSSIAN_C, 
+        cv2.THRESH_BINARY, 
+        35, 5  # <-- Changed 10 to 5
+    )
+
+    ink_is_white = cv2.bitwise_not(thresh)
+
+    # 2. Bigger kernel to fill the white holes inside the '9'
+    kernel_close = np.ones((5,5), np.uint8)
+    closed_ink = cv2.morphologyEx(ink_is_white, cv2.MORPH_CLOSE, kernel_close)
+
+    # 3. DILATION (THE NEW FIX): Thicken the ink to bridge the gap in the '3'
+    kernel_dilate = np.ones((3,3), np.uint8)
+    thick_ink = cv2.dilate(closed_ink, kernel_dilate, iterations=1)
+
+    # 4. Remove noise dots (same as before, but on thick_ink)
+    contours, _ = cv2.findContours(thick_ink, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+    for cnt in contours:
+        area = cv2.contourArea(cnt)
+        if area < 40:  
+            cv2.drawContours(thick_ink, [cnt], -1, 0, -1)
+
+    # Invert back to black ink on white paper
+    final_img = cv2.bitwise_not(thick_ink)
+
+    # --- ALIGNMENT FIX (b2.py vs d2.py) ---
+    # b2.py creates un-stretched characters accurately placed in a 120x40 (3:1) bounding box.
+    # To prevent PyTorch from squashing arbitrary crops, we pad it to exactly 120x40 first!
+    pil_img = Image.fromarray(final_img).convert('RGB')
+    pil_img = ImageOps.pad(pil_img, (120, 40), color=(255, 255, 255))
+    # ---------------------------------------
+
+    # Save debug image strictly as the AI sees it
+    pil_img.save("debug_AI_eyes.png")
+
+    return pil_img
+
+def main(image_path):
+    # SETUP DEVICE
+    if torch.backends.mps.is_available():
+        device = torch.device("mps")
+    elif torch.cuda.is_available():
+        device = torch.device("cuda")
+    else:
+        device = torch.device("cpu")
+
+    # LOAD CLASS MAPPING
+    with open("class_mapping.json", "r") as f:
+        class_to_idx = json.load(f)
+    idx_to_class = {int(v): k for k, v in class_to_idx.items()}
+    NUM_CLASSES = len(idx_to_class)
+
+    # LOAD MODEL
+    model = models.resnet18(weights=None)
+    num_ftrs = model.fc.in_features
+    model.fc = nn.Linear(num_ftrs, NUM_CLASSES)
+    model.load_state_dict(torch.load("togyzkumalak_model_OBED.pth", map_location=device))
+    model = model.to(device)
+    model.eval()
+
+    # PREPARE IMAGE USING OPENCV PREPROCESSING
+    pil_image = preprocess_for_ai(image_path)
+
+    transform = transforms.Compose([
+        transforms.Resize((40, 120)),
+        transforms.ToTensor(),
+        transforms.Normalize(mean=[0.5, 0.5, 0.5], std=[0.5, 0.5, 0.5]) 
+    ])
+
+    image_tensor = transform(pil_image).unsqueeze(0).to(device)
+
+    # PREDICT
+    with torch.no_grad():
+        outputs = model(image_tensor)
+        probabilities = torch.nn.functional.softmax(outputs[0], dim=0)
+
+    top_probs, top_classes = torch.topk(probabilities, 3)
+
+    print(f"\n--- AI PREDICTIONS FOR '{image_path}' ---")
+    for i in range(3):
+        prob = top_probs[i].item() * 100
+        class_idx = top_classes[i].item()
+        class_name = idx_to_class[class_idx]
+        print(f"Choice {i+1}: Move '{class_name}' with {prob:.2f}% confidence")
+    print("------------------------------------------\n")
+    print("Check 'debug_AI_eyes.png' in your folder to see the preprocessed image!")
+
+if __name__ == '__main__':
+    if len(sys.argv) < 2:
+        print("Usage: python d2.py <path_to_image>")
+    else:
+        main(sys.argv[1])

legacy/d3.py

@@ -0,0 +1,105 @@
+import torch
+import torch.nn as nn
+from torchvision import transforms, models
+from PIL import Image
+import json
+import sys
+import cv2
+import numpy as np
+
+# --- EXACT SAME FUNCTION FROM b2.py ---
+def crop_and_center_ink(cv2_gray_img, target_w=80, target_h=40, margin=4):
+    ink_mask = cv2.bitwise_not(cv2_gray_img)
+    coords = cv2.findNonZero(ink_mask)
+    
+    if coords is not None:
+        x, y, w, h = cv2.boundingRect(coords)
+        if w > 0 and h > 0:
+            crop = cv2_gray_img[y:y+h, x:x+w]
+            scale = min((target_w - 2*margin) / w, (target_h - 2*margin) / h)
+            new_w = max(1, int(w * scale))
+            new_h = max(1, int(h * scale))
+            
+            resized_crop = cv2.resize(crop, (new_w, new_h), interpolation=cv2.INTER_AREA)
+            
+            canvas = np.full((target_h, target_w), 255, dtype=np.uint8)
+            start_x = (target_w - new_w) // 2
+            start_y = (target_h - new_h) // 2
+            canvas[start_y:start_y+new_h, start_x:start_x+new_w] = resized_crop
+            return canvas
+            
+    return np.full((target_h, target_w), 255, dtype=np.uint8)
+
+# ... (imports and crop_and_center_ink stay the same) ...
+
+def preprocess_for_ai(image_path):
+    img = cv2.imread(image_path)
+    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    
+    # Use a sharper threshold to keep lines crisp
+    blurred = cv2.GaussianBlur(gray, (3, 3), 0)
+    thresh = cv2.adaptiveThreshold(blurred, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, 
+                                   cv2.THRESH_BINARY, 21, 7)
+    
+    # Clean up small noise dots ONLY
+    ink_is_white = cv2.bitwise_not(thresh)
+    contours, _ = cv2.findContours(ink_is_white, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+    for cnt in contours:
+        if cv2.contourArea(cnt) < 15: # Smaller threshold for noise
+            cv2.drawContours(ink_is_white, [cnt], -1, 0, -1)
+
+    # DO NOT dilate here. Let the centering handle the size.
+    final_img = cv2.bitwise_not(ink_is_white)
+
+    # Center it
+    centered_np = crop_and_center_ink(final_img, target_w=80, target_h=40)
+    
+    # Optional: Apply a standard 2x2 dilation to match training "thick" mode
+    # if the handwriting is very thin.
+    # centered_np = cv2.erode(centered_np, np.ones((2,2), np.uint8)) 
+
+    pil_img = Image.fromarray(centered_np).convert('RGB')
+    pil_img.save("debug_AI_eyes.png")
+    return pil_img
+
+# ... (main function stays same as previous) ...
+
+def main(image_path):
+    device = torch.device("mps") if torch.backends.mps.is_available() else torch.device("cpu")
+
+    with open("class_mapping.json", "r") as f:
+        class_to_idx = json.load(f)
+    idx_to_class = {int(v): k for k, v in class_to_idx.items()}
+    NUM_CLASSES = len(idx_to_class)
+
+    model = models.resnet18(weights=None)
+    model.fc = nn.Linear(model.fc.in_features, NUM_CLASSES)
+    model.load_state_dict(torch.load("togyzkumalak_model.pth", map_location=device))
+    model = model.to(device)
+    model.eval()
+
+    pil_image = preprocess_for_ai(image_path)
+
+    transform = transforms.Compose([
+        transforms.Resize((40, 80)), # MUST match the 2:1 ratio
+        transforms.ToTensor(),
+        transforms.Normalize(mean=[0.5, 0.5, 0.5], std=[0.5, 0.5, 0.5]) 
+    ])
+
+    image_tensor = transform(pil_image).unsqueeze(0).to(device)
+
+    with torch.no_grad():
+        outputs = model(image_tensor)
+        probabilities = torch.nn.functional.softmax(outputs[0], dim=0)
+
+    top_probs, top_classes = torch.topk(probabilities, 3)
+
+    print(f"\n--- AI PREDICTIONS FOR '{image_path}' ---")
+    for i in range(3):
+        print(f"Choice {i+1}: Move '{idx_to_class[top_classes[i].item()]}' with {top_probs[i].item() * 100:.2f}% conf")
+
+if __name__ == '__main__':
+    if len(sys.argv) < 2:
+        print("Usage: python d2.py <path_to_image>")
+    else:
+        main(sys.argv[1])

legacy/d4.py

@@ -0,0 +1,78 @@
+import os
+os.environ["OMP_NUM_THREADS"] = "1"
+os.environ["MKL_NUM_THREADS"] = "1"
+os.environ["VECLIB_MAXIMUM_THREADS"] = "1"
+
+import torch
+torch.set_num_threads(1)
+
+import torchvision.transforms as T
+from PIL import Image
+from fastai.vision.all import load_learner
+import pickle
+import plum._resolver
+
+# --- THE MODEL LOADING PATCH ---
+class PatchedResolver(plum._resolver.Resolver):
+    def __setstate__(self, state):
+        if isinstance(state, dict):
+            for k, v in state.items():
+                try: setattr(self, k, v)
+                except AttributeError: pass
+        elif isinstance(state, tuple):
+            for item in state:
+                if isinstance(item, dict):
+                    for k, v in item.items():
+                        try: setattr(self, k, v)
+                        except AttributeError: pass
+
+class SafeUnpickler(pickle.Unpickler):
+    def find_class(self, module, name):
+        if name == 'Resolver' and 'plum' in module:
+            return PatchedResolver
+        return super().find_class(module, name)
+
+class SafePickle:
+    Unpickler = SafeUnpickler
+# -------------------------------
+
+# 1. Load the model using our safe unpickler
+print("Loading model...")
+learn = load_learner('handwriting_classifier.pkl', pickle_module=SafePickle)
+print("Model loaded successfully!")
+
+# 2. Extract the raw PyTorch model and the classes (vocab)
+pytorch_model = learn.model
+pytorch_model.eval()            # Set model to evaluation mode
+vocab = list(learn.dls.vocab)    # Get the list of your 163 classes
+
+# 3. Standard PyTorch Image Preprocessing (Bypasses FastAI transforms entirely)
+# This perfectly matches the Resize and standard ImageNet normalization used by ResNet
+preprocess = T.Compose([
+    T.Resize((40, 120)),
+    T.ToTensor(),
+    T.Normalize(
+        mean=[0.485, 0.456, 0.406],  # Standard ImageNet stats
+        std=[0.229, 0.224, 0.225]
+    )
+])
+
+# 4. Open the image using Pillow and preprocess it
+img = Image.open('IMG_1521 (4) (1).jpg').convert('RGB')
+input_tensor = preprocess(img).unsqueeze(0)  # Add batch dimension [1, 3, 40, 120]
+
+# 5. Raw PyTorch Forward Pass
+print("Running raw PyTorch inference...")
+with torch.no_grad():
+    outputs = pytorch_model(input_tensor)
+    # Apply softmax to convert raw outputs to probabilities
+    probabilities = torch.nn.functional.softmax(outputs[0], dim=0)
+
+# 6. Extract the top 3 predictions
+top_prob, top_catid = torch.topk(probabilities, 3)
+
+print("\nPrediction Results:")
+for i in range(top_prob.size(0)):
+    class_name = vocab[top_catid[i].item()]
+    confidence = top_prob[i].item() * 100
+    print(f"Class {class_name}: {confidence:.2f}%")

legacy/d5.py

@@ -0,0 +1,80 @@
+import os
+os.environ["OMP_NUM_THREADS"] = "1"
+os.environ["MKL_NUM_THREADS"] = "1"
+os.environ["VECLIB_MAXIMUM_THREADS"] = "1"
+
+import torch
+torch.set_num_threads(1)
+
+import torchvision.transforms as T
+from PIL import Image, ImageOps
+from fastai.vision.all import load_learner
+import pickle
+import plum._resolver
+
+# --- THE MODEL LOADING PATCH ---
+class PatchedResolver(plum._resolver.Resolver):
+    def __setstate__(self, state):
+        if isinstance(state, dict):
+            for k, v in state.items():
+                try: setattr(self, k, v)
+                except AttributeError: pass
+        elif isinstance(state, tuple):
+            for item in state:
+                if isinstance(item, dict):
+                    for k, v in item.items():
+                        try: setattr(self, k, v)
+                        except AttributeError: pass
+
+class SafeUnpickler(pickle.Unpickler):
+    def find_class(self, module, name):
+        if name == 'Resolver' and 'plum' in module:
+            return PatchedResolver
+        return super().find_class(module, name)
+
+class SafePickle:
+    Unpickler = SafeUnpickler
+# -------------------------------
+
+# 1. Load the model using our safe unpickler
+print("Loading model...")
+learn = load_learner('handwriting_classifier_best (1).pkl', pickle_module=SafePickle)
+print("Model loaded successfully!")
+
+
+# 2. Extract the raw PyTorch model and the classes (vocab)
+pytorch_model = learn.model
+pytorch_model.eval()            # Set model to evaluation mode
+vocab = list(learn.dls.vocab)    # Get the list of your 163 classes
+
+# 3. Standard PyTorch Image Preprocessing (Bypasses FastAI transforms entirely)
+# This perfectly matches the Resize and standard ImageNet normalization used by ResNet
+preprocess = T.Compose([
+    T.Resize((40, 80)),
+    T.ToTensor(),
+    T.Normalize(
+        mean=[0.485, 0.456, 0.406],  # Standard ImageNet stats
+        std=[0.229, 0.224, 0.225]
+    )
+])
+
+# 4. Open the image using Pillow and preprocess it
+img = Image.open('IMG_1521 (1) (1) (1).jpg')
+img = ImageOps.exif_transpose(img).convert('L').convert('RGB')  # Fix iPhone rotation bug by applying EXIF orientation
+input_tensor = preprocess(img).unsqueeze(0)  # Add batch dimension [1, 3, 40, 80]
+
+# 5. Raw PyTorch Forward Pass
+print("Running raw PyTorch inference...")
+with torch.no_grad():
+    outputs = pytorch_model(input_tensor)
+    # Apply softmax to convert raw outputs to probabilities
+    probabilities = torch.nn.functional.softmax(outputs[0], dim=0)
+
+# 6. Extract the top 3 predictions
+top_prob, top_catid = torch.topk(probabilities, 3)
+
+print("\nPrediction Results:")
+for i in range(top_prob.size(0)):
+    class_name = vocab[top_catid[i].item()]
+    confidence = top_prob[i].item() * 100
+    print(f"Class {class_name}: {confidence:.2f}%")

legacy/e4.py

@@ -0,0 +1,28 @@
+from fastai.vision.all import load_learner, PILImage
+from PIL import ImageOps
+
+# 1. Load the model
+print("Loading model...")
+learn = load_learner('handwriting_classifier_best.pkl')
+
+# 2. Open the image and FIX the iPhone rotation bug!
+raw_img = PILImage.create('IMG_1521 (4) (1).jpg')
+
+# FastAI's PILImage.create actually attempts to transpose EXIF under the hood,
+# but let's double check by physically saving what the model sees:
+raw_img.save("what_the_model_actually_sees.png")
+print("Saved 'what_the_model_actually_sees.png'. Please open this file and check if it is upright!")
+
+# 3. Predict using FastAI's official pipeline
+pred, pred_idx, probs = learn.predict(raw_img)
+
+print(f"\n--- Prediction ---")
+print(f"Predicted Class: {pred}")
+print(f"Confidence: {probs[pred_idx]*100:.2f}%")
+
+# Show top 3
+class_probabilities = dict(zip(learn.dls.vocab, probs.tolist()))
+sorted_guesses = sorted(class_probabilities.items(), key=lambda x: x[1], reverse=True)
+print("\nTop 3 Guesses:")
+for cls, prob in sorted_guesses[:3]:
+    print(f"Class {cls}: {prob * 100:.2f}%")

models/best.classes.json

@@ -0,0 +1 @@
+["11", "11x", "12", "12x", "13", "13x", "14", "14x", "15", "15x", "16", "16x", "17", "17x", "18", "18x", "19", "19x", "21", "21x", "22", "22x", "23", "23x", "24", "24x", "25", "25x", "26", "26x", "27", "27x", "28", "28x", "29", "29x", "31", "31x", "32", "32x", "33", "33x", "34", "34x", "35", "35x", "36", "36x", "37", "37x", "38", "38x", "39", "39x", "41", "41x", "42", "42x", "43", "43x", "44", "44x", "45", "45x", "46", "46x", "47", "47x", "48", "48x", "49", "49x", "51", "51x", "52", "52x", "53", "53x", "54", "54x", "55", "55x", "56", "56x", "57", "57x", "58", "58x", "59", "59x", "61", "61x", "62", "62x", "63", "63x", "64", "64x", "65", "65x", "66", "66x", "67", "67x", "68", "68x", "69", "69x", "71", "71x", "72", "72x", "73", "73x", "74", "74x", "75", "75x", "76", "76x", "77", "77x", "78", "78x", "79", "79x", "81", "81x", "82", "82x", "83", "83x", "84", "84x", "85", "85x", "86", "86x", "87", "87x", "88", "88x", "89", "89x", "91", "91x", "92", "92x", "93", "93x", "94", "94x", "95", "95x", "96", "96x", "97", "97x", "98", "98x", "99", "99x", "empty"]

models/best.onnx

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

models/kazan.classes.json

@@ -0,0 +1 @@
+["00", "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31", "32", "33", "34", "35", "36", "37", "38", "39", "40", "41", "42", "43", "44", "45", "46", "47", "48", "49", "50", "51", "52", "53", "54", "55", "56", "57", "58", "59", "60", "61", "62", "63", "64", "65", "66", "67", "68", "69", "70", "71", "72", "73", "74", "75", "76", "77", "78", "79", "80", "81", "empty"]

models/kazan.onnx

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

notebooks/colab_train.ipynb

@@ -0,0 +1,93 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Togyzkumalak Move OCR — Colab training\n",
+    "\n",
+    "Runtime → Change runtime type → **GPU**, then run the cells in order.\n",
+    "\n",
+    "Get the project into Colab either by cloning your repo or by uploading a zip\n",
+    "of the project directory (without `venv311/`, `train_data5/`, `legacy/`)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Option A: clone (edit URL)\n",
+    "# !git clone https://github.com/<you>/9OCR.git project\n",
+    "\n",
+    "# Option B: upload a zip named project.zip via the Files sidebar, then:\n",
+    "# !unzip -q project.zip -d project\n",
+    "\n",
+    "%cd project"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!pip install -q -r requirements.txt"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Build glyph pools: ARDIS (European handwriting) + EMNIST via torchvision\n",
+    "# (--emnist is needed because ingredients/ is gitignored and absent here)\n",
+    "!python scripts/get_glyphs.py --emnist"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Sanity check: synthetic cells should resemble data/real_crops/*.jpg\n",
+    "!python -m togyz.synth --preview preview.png\n",
+    "from IPython.display import Image as IPImage\n",
+    "IPImage('preview.png')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!python train.py --epochs 30 --samples-per-epoch 50000 --batch-size 256 --workers 2"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!python eval.py --ckpt checkpoints/best.pt\n",
+    "\n",
+    "# download the trained model\n",
+    "from google.colab import files\n",
+    "files.download('checkpoints/best.pt')"
+   ]
+  }
+ ],
+ "metadata": {
+  "accelerator": "GPU",
+  "colab": {"provenance": []},
+  "kernelspec": {"display_name": "Python 3", "name": "python3"},
+  "language_info": {"name": "python"}
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

predict.py

@@ -0,0 +1,68 @@
+"""Classify cropped cell images.
+
+    python predict.py data/real_crops/96_a.jpg
+    python predict.py "data/real_crops/*.jpg" --topk 3
+    python predict.py cell.jpg --allowed "12,34x,56"   # restrict to legal moves
+
+--allowed renormalizes probabilities over the given moves - at any game state
+at most 9 moves are legal, so an upstream game tracker can pass them here.
+"""
+
+import argparse
+import glob
+
+import numpy as np
+import torch
+
+from togyz.classes import CLASS_TO_IDX
+from togyz.model import auto_device, load_checkpoint
+from togyz.preprocess import preprocess_file
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("images", nargs="+", help="image paths or globs")
+    parser.add_argument("--ckpt", default="checkpoints/best.pt")
+    parser.add_argument("--topk", type=int, default=3)
+    parser.add_argument("--allowed", default=None,
+                        help="comma-separated legal moves, e.g. '12,34x,56'")
+    parser.add_argument("--device", default=None)
+    args = parser.parse_args()
+
+    paths = []
+    for pattern in args.images:
+        matched = sorted(glob.glob(pattern))
+        paths.extend(matched if matched else [pattern])
+
+    device = torch.device(args.device) if args.device else auto_device()
+    model, ckpt = load_checkpoint(args.ckpt, device)
+    classes = ckpt["classes"]
+
+    allowed_idx = None
+    if args.allowed:
+        moves = [m.strip() for m in args.allowed.split(",") if m.strip()]
+        unknown = [m for m in moves if m not in CLASS_TO_IDX]
+        if unknown:
+            parser.error(f"unknown moves in --allowed: {unknown}")
+        allowed_idx = torch.tensor([CLASS_TO_IDX[m] for m in moves])
+
+    batch = torch.from_numpy(np.stack([preprocess_file(p) for p in paths]))
+    with torch.no_grad():
+        probs = torch.softmax(model(batch.to(device)).cpu(), dim=1)
+
+    for path, p in zip(paths, probs):
+        topk = p.topk(min(args.topk, len(classes)))
+        guesses = ", ".join(
+            f"{classes[i]} {v:.1%}" for i, v in zip(topk.indices.tolist(), topk.values.tolist())
+        )
+        line = f"{path}: {guesses}"
+        if allowed_idx is not None:
+            legal = p[allowed_idx]
+            legal = legal / legal.sum()
+            best = int(legal.argmax())
+            line += f"  | legal pick: {classes[int(allowed_idx[best])]} {legal[best]:.1%}"
+        print(line)
+
+
+if __name__ == "__main__":
+    main()

read_game.py

@@ -0,0 +1,95 @@
+"""Read an entire Togyzkumalak scoresheet photo into game records (ONNX).
+
+    python read_game.py "data/2026-07-06 00.00.20.jpg" --out out/sheet1 --result 0-1
+
+Outputs in --out:
+    game.json      per ply: bbox, probabilities for all 163 classes, top-k,
+                   raw argmax, legal move set, legality flag
+    raw.pgn        pure classifier argmax for every ply (even if illegal)
+    legal.pgn      replayed under the rules; STOPS at the first illegal argmax,
+                   the first empty cell, or when the game is over
+    beam.pgn       best fully-legal reconstruction (beam search + kazan/result
+                   evidence)
+    annotated.jpg  sheet with cell boxes and the beam reconstruction labels
+    cells/         every scanned cell crop, e.g. 07_W.png
+
+Inference runs on the exported ONNX models (torch-free). Regenerate them with
+`python scripts/export_onnx.py` after training. PGN move annotations: '+' =
+capture, 'x' = tuzdyk creation; strip '+' to feed the moves to the 9Q engine.
+"""
+
+import argparse
+import json
+from pathlib import Path
+
+from togyz.pipeline import RESULT_CODES, load_classifier, run_pipeline
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("image", help="scoresheet photo")
+    parser.add_argument("--onnx", default="checkpoints/best.onnx",
+                        help="move classifier ONNX (with a .classes.json sidecar)")
+    parser.add_argument("--kazan-onnx", default="checkpoints/kazan/best.onnx",
+                        help="kazan-number ONNX; checkpoint matching is skipped "
+                             "if the file does not exist")
+    parser.add_argument("--out", default=None, help="output dir (default: out/<image stem>)")
+    parser.add_argument("--topk", type=int, default=5)
+    parser.add_argument("--beam-width", type=int, default=1024,
+                        help="hypotheses kept during beam decoding")
+    parser.add_argument("--beam-top", type=int, default=9,
+                        help="legal continuations considered per ply (9 = all)")
+    parser.add_argument("--result", choices=sorted(RESULT_CODES),
+                        help="known game result from the sheet footer "
+                             "(1-0 = Bast./White won); re-ranks the beam pool")
+    parser.add_argument("--no-tta", action="store_true",
+                        help="disable test-time augmentation (7 shifted views/cell)")
+    parser.add_argument("--temperature", type=float, default=1.0,
+                        help="softmax temperature; >1 softens overconfident cells")
+    args = parser.parse_args()
+
+    out_dir = Path(args.out or Path("out") / Path(args.image).stem)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    moves_clf = load_classifier(args.onnx)
+    kazan_clf = None
+    if Path(args.kazan_onnx).exists():
+        kazan_clf = load_classifier(args.kazan_onnx)
+    else:
+        print(f"No kazan classifier at {args.kazan_onnx} - checkpoint matching off.")
+
+    print(f"Reading {args.image} ...")
+    out = run_pipeline(
+        args.image, moves_clf, kazan_clf,
+        result=args.result, topk=args.topk,
+        beam_width=args.beam_width, per_ply=args.beam_top,
+        temperature=args.temperature, tta=not args.no_tta,
+        save_cells_dir=out_dir / "cells",
+    )
+
+    if out["low_resolution"]:
+        print(f"WARNING: median cell height is only {out['median_cell_height']}px - "
+              "accuracy suffers at this resolution; re-photograph at full camera "
+              "resolution if possible.")
+    if out["kazan_report"]:
+        print("Kazan checkpoints read: "
+              f"{[(r['move'], r['side'], r['read']) for r in out['kazan_report']]}")
+
+    result = {"image": args.image, "onnx": args.onnx, **out["game_json"]}
+    (out_dir / "game.json").write_text(json.dumps(result, indent=1))
+    (out_dir / "raw.pgn").write_text(out["raw_pgn"])
+    (out_dir / "legal.pgn").write_text(out["legal_pgn"])
+    (out_dir / "beam.pgn").write_text(out["beam_pgn"])
+    out["annotated_image"].save(out_dir / "annotated.jpg", quality=90)
+
+    beam = out["game_json"]["beam"]
+    agree = sum(d["agrees_with_raw"] for d in beam["moves"])
+    print(f"Scanned {out['plies_scanned']} plies; strict legal replay covers {out['legal_plies']}.")
+    print(f"Beam decode: {out['beam_plies']} fully legal plies "
+          f"(log-prob {beam['log_prob']:.1f}, agrees with raw argmax on {agree}/{out['beam_plies']}).")
+    print(f"Stopped: {out['stopped']}")
+    print(f"Outputs in {out_dir}/: game.json, raw.pgn, legal.pgn, beam.pgn, annotated.jpg, cells/")
+
+
+if __name__ == "__main__":
+    main()

requirements-train.txt

@@ -0,0 +1,9 @@
+# Training + ONNX export deps (local / Colab GPU). The Space itself does NOT
+# install these - it only needs the torch-free serving set in requirements.txt.
+torch>=2.1
+torchvision>=0.16
+onnx>=1.16
+onnxscript>=0.1
+numpy>=1.24
+opencv-python-headless>=4.8
+pillow>=10.0

requirements.txt

@@ -0,0 +1,8 @@
+# HuggingFace Space (serving) deps - torch-free, installed by the Space builder.
+# Training/export uses requirements-train.txt instead.
+gradio>=6.20
+onnxruntime>=1.20
+numpy>=1.24
+# pin below OpenCV 5.x: the pipeline's cv2 calls are tested against 4.x
+opencv-python-headless>=4.8,<5
+pillow>=10.0

scripts/export_onnx.py

@@ -0,0 +1,82 @@
+"""Export the trained .pt checkpoints to ONNX for torch-free serving.
+
+    python scripts/export_onnx.py
+
+Writes, next to each source checkpoint:
+    checkpoints/best.onnx          + checkpoints/best.classes.json
+    checkpoints/kazan/best.onnx    + checkpoints/kazan/best.classes.json
+
+ONNX carries no Python metadata, so the class list (which maps output index
+-> move/kazan string) is saved as a JSON sidecar the serving code reads. The
+graph has a dynamic batch axis so one session handles any number of cells.
+"""
+
+import argparse
+import json
+from pathlib import Path
+
+import onnx
+import torch
+
+from togyz.model import build_model
+from togyz.preprocess import TARGET_H, TARGET_W
+
+OPSET = 17
+
+
+def export_one(ckpt_path: Path) -> Path:
+    ckpt = torch.load(ckpt_path, map_location="cpu", weights_only=True)
+    classes = ckpt["classes"]
+    model = build_model(len(classes))
+    model.load_state_dict(ckpt["model_state"])
+    model.eval()
+
+    onnx_path = ckpt_path.with_suffix(".onnx")
+    classes_path = ckpt_path.with_suffix(".classes.json")
+    # Legacy TorchScript exporter (dynamo=False) embeds weights directly, so
+    # the result is a single self-contained .onnx (no sidecar .data file) -
+    # much cleaner to commit to the HuggingFace Space via Git LFS.
+    dummy = torch.zeros(1, 1, TARGET_H, TARGET_W)
+    torch.onnx.export(
+        model,
+        dummy,
+        str(onnx_path),
+        input_names=["input"],
+        output_names=["logits"],
+        dynamic_axes={"input": {0: "batch"}, "logits": {0: "batch"}},
+        opset_version=OPSET,
+        dynamo=False,
+    )
+    # Belt and braces: if any external data slipped out, fold it back in so the
+    # .onnx is guaranteed standalone, then drop the stray .data file.
+    model_proto = onnx.load(str(onnx_path))
+    onnx.save_model(model_proto, str(onnx_path), save_as_external_data=False)
+    data_file = onnx_path.with_suffix(".onnx.data")
+    if data_file.exists():
+        data_file.unlink()
+
+    classes_path.write_text(json.dumps(classes))
+    size_mb = onnx_path.stat().st_size / 1e6
+    print(f"{ckpt_path} -> {onnx_path} ({len(classes)} classes, {size_mb:.1f} MB)")
+    return onnx_path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "checkpoints",
+        nargs="*",
+        default=["checkpoints/best.pt", "checkpoints/kazan/best.pt"],
+        help="checkpoint(s) to export (default: moves + kazan best.pt)",
+    )
+    args = parser.parse_args()
+    for path in args.checkpoints:
+        p = Path(path)
+        if p.exists():
+            export_one(p)
+        else:
+            print(f"skip: {p} not found")
+
+
+if __name__ == "__main__":
+    main()

scripts/get_glyphs.py

@@ -0,0 +1,182 @@
+"""Build the glyph pools used by the synthesizer (idempotent).
+
+    python scripts/get_glyphs.py            # download + prepare ARDIS
+    python scripts/get_glyphs.py --emnist   # also rebuild the EMNIST pool
+                                            # (only needed if ingredients/ is absent,
+                                            #  e.g. on Colab)
+
+ARDIS (https://ardisdataset.github.io/ARDIS/) Dataset II contains ~10k digit
+images cropped from 19th-century European church records - crossed 7s, serif
+1s, cursive styles that match Kazakh/European handwriting far better than
+EMNIST. Images are normalized here into white-on-black float masks under
+glyph_data/ardis/<digit>/.
+"""
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+GLYPH_DATA = PROJECT_ROOT / "glyph_data"
+ARDIS_URL = (
+    "https://github.com/ardisdataset/ARDIS/raw/Updates-Date-String/ARDIS_DATASET_II.rar"
+)
+IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".bmp"}
+
+
+def download(url: str, dest: Path) -> None:
+    if dest.exists() and dest.stat().st_size > 0:
+        print(f"Already downloaded: {dest}")
+        return
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    print(f"Downloading {url} ...")
+    subprocess.run(["curl", "-L", "--fail", "-o", str(dest), url], check=True)
+
+
+def extract_rar(archive: Path, dest: Path) -> None:
+    if dest.exists() and any(dest.iterdir()):
+        print(f"Already extracted: {dest}")
+        return
+    dest.mkdir(parents=True, exist_ok=True)
+    if shutil.which("bsdtar"):
+        subprocess.run(["bsdtar", "-xf", str(archive), "-C", str(dest)], check=True)
+    elif shutil.which("unar"):
+        subprocess.run(["unar", "-quiet", "-o", str(dest), str(archive)], check=True)
+    elif shutil.which("unrar"):
+        subprocess.run(["unrar", "x", "-inul", str(archive), str(dest)], check=True)
+    else:
+        sys.exit(
+            "No RAR extractor found (need bsdtar, unar, or unrar). "
+            "On Ubuntu/Colab: apt-get install -y unar"
+        )
+
+
+def infer_digit_label(path: Path) -> str | None:
+    if path.parent.name.isdigit() and len(path.parent.name) == 1:
+        return path.parent.name
+    stem = path.stem
+    for sep in ("_", "-", " "):
+        token = stem.split(sep)[0]
+        if token.isdigit() and len(token) == 1:
+            return token
+    return None
+
+
+def photo_to_mask(path: Path) -> np.ndarray | None:
+    """Ink-on-paper photo -> white-on-black float mask, tight-cropped."""
+    with Image.open(path) as img:
+        gray = np.asarray(img.convert("L"), dtype=np.float32)
+    if gray.shape[0] < 10 or gray.shape[1] < 5:
+        return None
+    inverted = 255.0 - gray
+    background = np.percentile(inverted, 50)
+    signal = np.clip(inverted - background, 0, None)
+    peak = np.percentile(signal, 99.5)
+    if peak < 12:  # effectively blank
+        return None
+    mask = np.clip(signal / peak, 0.0, 1.0)
+    mask[mask < 0.18] = 0.0  # suppress paper texture
+    ys, xs = np.where(mask > 0.18)
+    if len(ys) < 20:
+        return None
+    mask = mask[ys.min() : ys.max() + 1, xs.min() : xs.max() + 1]
+    if mask.shape[0] < 8 or mask.shape[1] < 3:
+        return None
+    return mask
+
+
+def prepare_ardis() -> None:
+    archive = GLYPH_DATA / "_downloads" / "ARDIS_DATASET_II.rar"
+    raw_dir = GLYPH_DATA / "_raw" / "ardis2"
+    out_root = GLYPH_DATA / "ardis"
+    if out_root.exists() and any(out_root.glob("*/*.png")):
+        print(f"ARDIS pool already prepared at {out_root}")
+        return
+
+    download(ARDIS_URL, archive)
+    extract_rar(archive, raw_dir)
+
+    counts: dict[str, int] = {}
+    skipped = 0
+    for path in sorted(raw_dir.rglob("*")):
+        if path.suffix.lower() not in IMAGE_EXTS:
+            continue
+        label = infer_digit_label(path)
+        if label is None:  # 0 is kept: kazan checkpoint numbers use it
+            skipped += 1
+            continue
+        mask = photo_to_mask(path)
+        if mask is None:
+            skipped += 1
+            continue
+        out_dir = out_root / label
+        out_dir.mkdir(parents=True, exist_ok=True)
+        index = counts.get(label, 0)
+        Image.fromarray((mask * 255).astype(np.uint8)).save(out_dir / f"{label}_{index}.png")
+        counts[label] = index + 1
+
+    print(f"ARDIS pool: {sum(counts.values())} glyphs "
+          f"({', '.join(f'{k}:{v}' for k, v in sorted(counts.items()))}), "
+          f"skipped {skipped}")
+    if not counts:
+        print("WARNING: no ARDIS glyphs extracted - the synthesizer will fall back "
+              "to EMNIST + procedural styles.")
+
+
+def prepare_emnist(per_class: int) -> None:
+    from torchvision.datasets import EMNIST
+
+    out_root = GLYPH_DATA / "emnist"
+    if out_root.exists() and any(out_root.glob("*/*.png")):
+        print(f"EMNIST pool already prepared at {out_root}")
+        return
+
+    print("Downloading EMNIST (byclass) via torchvision ...")
+    dataset = EMNIST(str(GLYPH_DATA / "_downloads"), split="byclass", train=True, download=True)
+    # byclass labels: 0-9 digits, 10-35 A-Z, 36-61 a-z
+    wanted = {label: str(label) for label in range(0, 10)}
+    wanted[33] = "x"  # 'X'
+    wanted[59] = "x"  # 'x'
+
+    counts: dict[str, int] = {}
+    for img, label in zip(dataset.data, dataset.targets):
+        char = wanted.get(int(label))
+        if char is None:
+            continue
+        if counts.get(char, 0) >= per_class:
+            if all(counts.get(c, 0) >= per_class for c in wanted.values()):
+                break
+            continue
+        arr = img.numpy().T  # EMNIST images are stored transposed
+        out_dir = out_root / char
+        out_dir.mkdir(parents=True, exist_ok=True)
+        index = counts.get(char, 0)
+        Image.fromarray(arr).save(out_dir / f"{char}_{index}.png")
+        counts[char] = index + 1
+    print(f"EMNIST pool: {sum(counts.values())} glyphs "
+          f"({', '.join(f'{k}:{v}' for k, v in sorted(counts.items()))})")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--emnist", action="store_true",
+                        help="also build EMNIST pool (needed when ingredients/ is absent)")
+    parser.add_argument("--per-class", type=int, default=2500,
+                        help="max EMNIST glyphs per character")
+    args = parser.parse_args()
+
+    prepare_ardis()
+    if args.emnist or not (PROJECT_ROOT / "ingredients").is_dir():
+        prepare_emnist(args.per_class)
+
+    # final summary through the sampler itself
+    sys.path.insert(0, str(PROJECT_ROOT))
+    from togyz.glyphs import GlyphSampler
+
+    print("\nGlyph pools as seen by the synthesizer:")
+    print(GlyphSampler(PROJECT_ROOT).describe())

tests/fixtures/shortest_candidate_replay.tsv

@@ -0,0 +1,14 @@
+shortest_candidate_halfmoves	11
+initial_position	p1_side=81	p2_side=81	p1_kazan=0	p2_kazan=0
+halfmove	player	move	p1_kazan	p2_kazan	p1_side	p2_side	p1_tuzdyk	p2_tuzdyk	winner
+1	P1	98	10	0	73	79	-1	-1	ongoing
+2	P2	22	10	10	65	77	-1	-1	ongoing
+3	P1	87	22	10	58	72	-1	-1	ongoing
+4	P2	12	22	10	60	70	-1	-1	ongoing
+5	P1	76	36	10	54	62	-1	-1	ongoing
+6	P2	25	36	10	54	62	-1	-1	ongoing
+7	P1	65	52	10	49	51	-1	-1	ongoing
+8	P2	13	52	10	49	51	-1	-1	ongoing
+9	P1	93	70	10	46	36	-1	-1	ongoing
+10	P2	25	70	10	46	36	-1	-1	ongoing
+11	P1	54	88	10	42	22	-1	-1	P1

tests/fixtures/shortest_terminal_game.txt

@@ -0,0 +1,6 @@
+1. 98 22
+2. 87 12
+3. 76 25
+4. 65 13
+5. 93 25
+6. 54

tests/test_rules.py

@@ -0,0 +1,110 @@
+"""Validate togyz/rules.py against the 9Q engine's shortest-game fixture.
+
+Replays tests/fixtures/shortest_candidate_replay.tsv move by move and asserts
+that notation, kazans, side totals, tuzdyks, and the winner all match the
+C++ engine's recorded state after every halfmove.
+
+    python tests/test_rules.py
+"""
+
+import csv
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from togyz.rules import Game
+
+FIXTURE = Path(__file__).parent / "fixtures" / "shortest_candidate_replay.tsv"
+
+
+def main() -> None:
+    with open(FIXTURE, newline="") as f:
+        lines = f.read().splitlines()
+    rows = list(csv.DictReader(lines[2:], delimiter="\t"))  # skip 2 meta lines
+
+    game = Game()
+    for row in rows:
+        expected = row["move"]
+        player = 0 if row["player"] == "P1" else 1
+        assert game.to_play == player, f"halfmove {row['halfmove']}: wrong side to move"
+
+        legal = {m.notation for m in game.legal_moves()}
+        assert expected in legal, f"halfmove {row['halfmove']}: {expected} not in {legal}"
+
+        played = game.play_notation(expected)
+        assert played.notation == expected
+
+        state = (game.kazans[0], game.kazans[1], *game.side_totals(),
+                 game.tuzdyks[0], game.tuzdyks[1])
+        want = tuple(int(row[k]) for k in
+                     ("p1_kazan", "p2_kazan", "p1_side", "p2_side", "p1_tuzdyk", "p2_tuzdyk"))
+        assert state == want, (
+            f"halfmove {row['halfmove']} ({expected}): state {state} != fixture {want}"
+        )
+
+        if row["winner"] != "ongoing":
+            assert game.is_over, f"halfmove {row['halfmove']}: game should be over"
+            expected_winner = {"P1": 0, "P2": 1, "draw": -1}[row["winner"]]
+            assert game.winner() == expected_winner
+
+    print(f"OK: replayed {len(rows)} halfmoves, all states match the 9Q fixture")
+
+    # extra sanity: fresh game has exactly 9 legal moves, all distinct notations
+    fresh = Game()
+    moves = fresh.legal_moves()
+    assert len(moves) == 9 and len({m.notation for m in moves}) == 9
+    print("OK: initial position has 9 distinct legal moves")
+
+    # tuzdyk scenario (not covered by the fixture): P1 sows 3 stones from
+    # hole 9 -> last stone lands in P2's hole 2 (pit 10) making it 3 -> "92x"
+    g = Game()
+    g.pits = [9, 9, 9, 9, 9, 9, 9, 9, 3] + [2, 2, 9, 9, 9, 9, 9, 9, 9]
+    move = g.play_notation("92x")
+    assert move.makes_tuzdyk and g.tuzdyks[0] == 1 and g.kazans[0] == 3
+    assert g.pits[10] == 0
+    # P2 may not move from their own hole 2 (it is P1's tuzdyk now)
+    assert 1 not in g.legal_actions()
+    # P2 sows 3 stones from their hole 1 (pit 9): one falls into the tuzdyk
+    # and must be collected by its owner P1
+    g.play_notation("13")
+    assert g.kazans[0] == 3 + 1, "stone sown into tuzdyk must go to owner"
+    assert g.pits[10] == 0
+    print("OK: tuzdyk creation, blocking, and collection behave correctly")
+
+    # BOTH players may create one tuzdyk each (as on the real scoresheet:
+    # 47x by White then 91x by Black) - but never a second one, never in
+    # hole 9, and never mirroring the opponent's tuzdyk column.
+    g = Game()
+    g.tuzdyks = [4, -1]  # White already owns a tuzdyk (Black's hole 5)
+    g.to_play = 1
+    g.pits = [9, 9, 2, 9, 9, 9, 9, 9, 9] + [9] * 9
+    # Black hole 4 (pit 12), 9 stones: lands (12+9-1)%18 = pit 2, making 3
+    move = g.play_notation("43x")
+    assert move.makes_tuzdyk and g.tuzdyks == [4, 2]
+    # a second tuzdyk for the same player must be impossible anywhere
+    g.to_play = 1
+    assert not any(m.makes_tuzdyk for m in g.legal_moves())
+    print("OK: both players can own one tuzdyk; no second tuzdyk possible")
+
+    # mirror restriction: creation blocked where the opponent's tuzdyk sits
+    g = Game()
+    g.tuzdyks = [-1, 2]  # Black owns White's hole 3 (column index 2)
+    g.pits = [9] * 18
+    g.pits[8] = 4  # White hole 9: lands (8+4-1)%18 = pit 11 (Black col 2)
+    g.pits[11] = 2  # becomes 3 on landing - but mirrored, so no tuzdyk
+    move = g.play_notation("93")
+    assert not move.makes_tuzdyk and g.tuzdyks[0] == -1
+
+    # hole 9 restriction: landing makes 3 in opponent hole 9 -> no tuzdyk
+    g = Game()
+    g.pits = [9] * 18
+    g.pits[8] = 10  # White hole 9: lands (8+10-1)%18 = pit 17 (Black hole 9)
+    g.pits[17] = 2  # becomes 3 on landing
+    move = g.play_notation("99")
+    assert not move.makes_tuzdyk and g.tuzdyks[0] == -1, "hole 9 must never be tuzdyk"
+    print("OK: mirror and hole-9 tuzdyk restrictions enforced")
+
+
+if __name__ == "__main__":
+    main()

togyz/classes.py

@@ -0,0 +1,23 @@
+"""Canonical class list for Togyzkumalak move OCR.
+
+162 moves (start hole 1-9, end hole 1-9, with or without a capture 'x')
+plus 'empty'. The order matches the alphabetical order used by
+torchvision ImageFolder in the legacy pipeline (legacy/class_mapping.json),
+so old and new indices agree.
+"""
+
+MOVES = [
+    f"{start}{end}{suffix}"
+    for start in range(1, 10)
+    for end in range(1, 10)
+    for suffix in ("", "x")
+]
+
+EMPTY = "empty"
+CLASSES = MOVES + [EMPTY]
+CLASS_TO_IDX = {name: i for i, name in enumerate(CLASSES)}
+NUM_CLASSES = len(CLASSES)  # 163
+
+# Kazan checkpoint numbers on the scoresheet summary strips: always exactly
+# two digits (with leading zero), values 00-81, never an 'x'.
+KAZAN_CLASSES = [f"{v:02d}" for v in range(82)] + [EMPTY]

togyz/dataset.py

@@ -0,0 +1,71 @@
+"""Datasets: on-the-fly synthetic cells and the labeled real crops."""
+
+import csv
+import random
+from pathlib import Path
+
+import torch
+from torch.utils.data import Dataset
+
+from .classes import CLASSES, CLASS_TO_IDX
+from .glyphs import GlyphSampler
+from .preprocess import preprocess_file, preprocess_pil
+from .synth import synthesize_cell
+
+
+class SyntheticCellDataset(Dataset):
+    """Generates cells on the fly - no dataset folders on disk.
+
+    With seed=None every access is fresh random data (infinite training
+    variety; DataLoader workers are seeded independently by torch). With a
+    seed, sample i is always the same image: a fixed validation set.
+    """
+
+    def __init__(self, num_samples: int, seed: int | None = None, project_root=".",
+                 classes: list[str] | None = None):
+        self.sampler = GlyphSampler(project_root)
+        self.num_samples = num_samples
+        self.seed = seed
+        self.classes = classes or CLASSES
+        self.class_to_idx = {c: i for i, c in enumerate(self.classes)}
+
+    def __len__(self) -> int:
+        return self.num_samples
+
+    def __getitem__(self, index: int):
+        if self.seed is not None:
+            rng = random.Random(f"{self.seed}:{index}")
+        else:
+            rng = random.Random(random.getrandbits(64))
+        class_name = self.classes[rng.randrange(len(self.classes))]
+        img = synthesize_cell(class_name, self.sampler, rng)
+        return torch.from_numpy(preprocess_pil(img)), self.class_to_idx[class_name]
+
+
+class RealCropDataset(Dataset):
+    """The labeled real photos in data/real_crops (tiny; used for eval only)."""
+
+    def __init__(self, root: str = "data/real_crops"):
+        self.root = Path(root)
+        self.items: list[tuple[str, str]] = []
+        labels_file = self.root / "labels.csv"
+        if labels_file.exists():
+            with open(labels_file, newline="") as f:
+                for row in csv.DictReader(f):
+                    label = row["label"].strip()
+                    if label in CLASS_TO_IDX:
+                        self.items.append((row["filename"].strip(), label))
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+    def __getitem__(self, index: int):
+        filename, label = self.items[index]
+        tensor = torch.from_numpy(preprocess_file(str(self.root / filename)))
+        return tensor, CLASS_TO_IDX[label]
+
+    def batch(self) -> tuple[torch.Tensor, torch.Tensor, list[str]]:
+        """All crops as one batch plus their filenames (for reporting)."""
+        tensors, labels = zip(*(self[i] for i in range(len(self))))
+        names = [name for name, _ in self.items]
+        return torch.stack(tensors), torch.tensor(labels), names

togyz/glyphs.py

@@ -0,0 +1,167 @@
+"""Glyph pools: per-character handwriting samples used by the synthesizer.
+
+Sources (all optional, at least one digit source must exist):
+  * ingredients/<char>/*.png        EMNIST-style masks, white ink on black
+  * glyph_data/emnist/<char>/*.png  same, regenerated via scripts/get_glyphs.py --emnist
+  * glyph_data/ardis/<digit>/*.png  European handwriting (ARDIS), pre-normalized
+                                    to white-on-black masks by scripts/get_glyphs.py
+
+EMNIST glyphs are American-style; real Togyzkumalak scoresheets use
+European/Kazakh styles (crossed 7, serif 1, cursive 9). ARDIS provides real
+European glyphs; on top of that, procedural edits (crossbar on 7, flag on 1)
+convert a share of EMNIST glyphs to European style, and 'x' marks are also
+drawn procedurally for extra variety.
+"""
+
+import math
+import os
+import random
+from pathlib import Path
+
+import cv2
+import numpy as np
+from PIL import Image
+
+DIGITS = "123456789"  # move notation digits; '0' appears only in kazan numbers
+CHARS = "0" + DIGITS + "x"
+INK_THRESHOLD = 0.15  # mask values above this count as ink
+
+
+def _list_images(directory: Path) -> list[str]:
+    if not directory.is_dir():
+        return []
+    exts = {".png", ".jpg", ".jpeg", ".bmp"}
+    return sorted(
+        str(p) for p in directory.iterdir() if p.suffix.lower() in exts
+    )
+
+
+def _tight_crop(mask: np.ndarray) -> np.ndarray:
+    ys, xs = np.where(mask > INK_THRESHOLD)
+    if len(ys) == 0:
+        return mask
+    return mask[ys.min() : ys.max() + 1, xs.min() : xs.max() + 1]
+
+
+def _load_mask(path: str) -> np.ndarray:
+    """Load a white-on-black glyph image as float mask in [0, 1]."""
+    with Image.open(path) as img:
+        arr = np.asarray(img.convert("L"), dtype=np.float32) / 255.0
+    return _tight_crop(arr)
+
+
+def add_crossbar_to_7(mask: np.ndarray, rng: random.Random) -> np.ndarray:
+    """European 7: horizontal bar through the stem."""
+    h, w = mask.shape
+    if h < 8 or w < 4:
+        return mask
+    y = int(h * rng.uniform(0.40, 0.60))
+    x0 = int(w * rng.uniform(-0.05, 0.15))
+    x1 = int(w * rng.uniform(0.85, 1.05))
+    dy = int(w * rng.uniform(-0.10, 0.10))
+    thickness = max(2, int(round(h * 0.05 * rng.uniform(0.8, 1.6))))
+    out = mask.copy()
+    cv2.line(out, (x0, y - dy // 2), (x1, y + dy // 2), 1.0, thickness, cv2.LINE_AA)
+    return np.clip(out, 0.0, 1.0)
+
+
+def add_flag_to_1(mask: np.ndarray, rng: random.Random) -> np.ndarray:
+    """European 1: diagonal flag from the top of the stem down-left."""
+    h, w = mask.shape
+    if h < 8:
+        return mask
+    ink_rows = np.where(mask.max(axis=1) > INK_THRESHOLD)[0]
+    if len(ink_rows) == 0:
+        return mask
+    y_top = int(ink_rows[0])
+    row = mask[min(y_top + 1, h - 1)]
+    x_top = int(np.argmax(row))
+    length = h * rng.uniform(0.22, 0.42)
+    angle = math.radians(rng.uniform(25, 55))
+    x_end = int(x_top - length * math.cos(angle))
+    y_end = int(y_top + length * math.sin(angle))
+    thickness = max(2, int(round(h * 0.05 * rng.uniform(0.8, 1.4))))
+    # give the flag room on the left if it would leave the canvas
+    pad = max(0, -x_end + 2)
+    out = np.pad(mask, ((0, 0), (pad, 0)))
+    cv2.line(out, (x_top + pad, y_top), (x_end + pad, y_end), 1.0, thickness, cv2.LINE_AA)
+    return np.clip(out, 0.0, 1.0)
+
+
+def _bezier_points(p0, p1, p2, n=24):
+    t = np.linspace(0.0, 1.0, n)[:, None]
+    pts = (1 - t) ** 2 * p0 + 2 * (1 - t) * t * p1 + t**2 * p2
+    return pts.astype(np.int32)
+
+
+def procedural_x(rng: random.Random) -> np.ndarray:
+    """Two crossing, slightly curved pen strokes."""
+    s = 64
+    canvas = np.zeros((s, s), np.float32)
+    for (ax, ay), (bx, by) in [((0.15, 0.12), (0.85, 0.88)), ((0.85, 0.10), (0.15, 0.90))]:
+        p0 = np.array([ax + rng.uniform(-0.08, 0.08), ay + rng.uniform(-0.08, 0.08)]) * s
+        p2 = np.array([bx + rng.uniform(-0.08, 0.08), by + rng.uniform(-0.08, 0.08)]) * s
+        mid = (p0 + p2) / 2 + np.array([rng.uniform(-0.15, 0.15), rng.uniform(-0.15, 0.15)]) * s
+        pts = _bezier_points(p0, mid, p2)
+        thickness = rng.randint(3, 6)
+        cv2.polylines(canvas, [pts], False, 1.0, thickness, cv2.LINE_AA)
+    canvas = cv2.GaussianBlur(canvas, (3, 3), 0.6)
+    return _tight_crop(np.clip(canvas, 0.0, 1.0))
+
+
+class GlyphSampler:
+    """Samples a glyph mask (float [0,1], white ink, tight-cropped) per character."""
+
+    def __init__(self, project_root: str | os.PathLike = "."):
+        root = Path(project_root)
+        self.pools: dict[str, dict[str, list[str]]] = {c: {} for c in CHARS}
+        for char in CHARS:
+            emnist = _list_images(root / "ingredients" / char) + _list_images(
+                root / "glyph_data" / "emnist" / char
+            )
+            if emnist:
+                self.pools[char]["emnist"] = emnist
+            if char != "x":
+                ardis = _list_images(root / "glyph_data" / "ardis" / char)
+                if ardis:
+                    self.pools[char]["ardis"] = ardis
+
+        missing = [c for c in DIGITS if not self.pools[c]]
+        if missing:
+            raise FileNotFoundError(
+                f"No glyph images found for digits {missing}. "
+                "Run `python scripts/get_glyphs.py` (optionally with --emnist) first."
+            )
+
+    def describe(self) -> str:
+        lines = []
+        for char in CHARS:
+            sources = ", ".join(
+                f"{name}:{len(paths)}" for name, paths in self.pools[char].items()
+            ) or "procedural only"
+            lines.append(f"  '{char}': {sources}")
+        return "\n".join(lines)
+
+    def sample(self, char: str, rng: random.Random) -> np.ndarray:
+        if char == "x" and (not self.pools["x"] or rng.random() < 0.35):
+            return procedural_x(rng)
+
+        sources = self.pools[char]
+        if not sources:
+            raise FileNotFoundError(
+                f"No glyphs for {char!r} - re-run scripts/get_glyphs.py "
+                "(digit 0 needs the ARDIS pool or --emnist)"
+            )
+        if "ardis" in sources and "emnist" in sources:
+            source = "ardis" if rng.random() < 0.55 else "emnist"
+        else:
+            source = next(iter(sources))
+        mask = _load_mask(rng.choice(sources[source]))
+
+        # Convert a share of EMNIST glyphs to European style; ARDIS already is.
+        euro_prob = 0.15 if source == "ardis" else 0.45
+        if char == "7" and rng.random() < euro_prob:
+            mask = add_crossbar_to_7(mask, rng)
+        if char == "1" and source == "emnist" and rng.random() < 0.35:
+            mask = add_flag_to_1(mask, rng)
+        return mask

togyz/model.py

@@ -0,0 +1,46 @@
+"""Model factory and checkpoint helpers (plain torch.save, no fastai pickles)."""
+
+import torch
+import torch.nn as nn
+from torchvision import models
+
+from .classes import CLASSES
+from .preprocess import TARGET_H, TARGET_W
+
+
+def build_model(num_classes: int = len(CLASSES)) -> nn.Module:
+    model = models.resnet18(weights=None)
+    model.conv1 = nn.Conv2d(1, 64, kernel_size=7, stride=2, padding=3, bias=False)
+    model.fc = nn.Linear(model.fc.in_features, num_classes)
+    return model
+
+
+def auto_device() -> torch.device:
+    if torch.cuda.is_available():
+        return torch.device("cuda")
+    if torch.backends.mps.is_available():
+        return torch.device("mps")
+    return torch.device("cpu")
+
+
+def save_checkpoint(path, model, epoch, val_acc, optimizer=None, classes=None):
+    torch.save(
+        {
+            "model_state": model.state_dict(),
+            "classes": classes or CLASSES,
+            "input_size": [TARGET_H, TARGET_W],
+            "epoch": epoch,
+            "val_acc": val_acc,
+            "optimizer_state": optimizer.state_dict() if optimizer else None,
+        },
+        path,
+    )
+
+
+def load_checkpoint(path, device=None) -> tuple[nn.Module, dict]:
+    device = device or auto_device()
+    ckpt = torch.load(path, map_location=device, weights_only=True)
+    model = build_model(len(ckpt["classes"]))
+    model.load_state_dict(ckpt["model_state"])
+    model.to(device).eval()
+    return model, ckpt

togyz/pipeline.py

@@ -0,0 +1,355 @@
+"""Torch-free scoresheet -> game reconstruction (onnxruntime + numpy).
+
+This is the single inference core shared by the CLI (`read_game.py`) and the
+Gradio demo (`app.py`). It deliberately imports **no torch**: the move and
+kazan classifiers run as ONNX sessions, and every array op is numpy. The
+heavy lifting of cell extraction (`togyz.sheet`) and the rules engine
+(`togyz.rules`) are already torch-free and imported as-is.
+
+The scoring/beam logic here is a straight port of the torch version whose
+weights and variants are benchmarked against hand-transcribed truth in the
+git history (sheet 1 = 36/39 exact plies). Keep it numerically equivalent.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+import onnxruntime as ort
+from PIL import Image
+
+from .classes import EMPTY
+from .preprocess import preprocess_pil
+from .rules import Game
+from .sheet import clean_cell, extract_cells, extract_kazan_cells, render_overlay
+
+MIN_CELL_HEIGHT = 35  # px; below this, resolution is low (surfaced as a warning)
+MIN_INK_RATIO = 0.02  # cells with less handwriting ink than this are empty
+MIN_KAZAN_INK = 0.028  # kazan boxes are small; box-edge remnants score higher
+
+TTA_SHIFTS = [(0, 0), (-2, 0), (2, 0), (0, -2), (0, 2), (-2, -2), (2, 2)]
+
+EXACT_WEIGHT = 0.5  # weight of the exact class-string probability
+FACTOR_WEIGHT = 0.5  # weight of the factorized digit-marginal probability
+KAZAN_FLOOR = 1e-4  # a misread checkpoint must not single-handedly kill truth
+RESULT_CODES = {"1-0": 0, "0-1": 1, "draw": -1}
+
+
+# --------------------------------------------------------------------------- #
+# ONNX session loading
+# --------------------------------------------------------------------------- #
+@dataclass
+class Classifier:
+    """An ONNX classifier plus the class list its output indices map to."""
+
+    session: ort.InferenceSession
+    classes: list[str]
+    input_name: str = field(default="")
+
+    def __post_init__(self):
+        self.input_name = self.session.get_inputs()[0].name
+
+    def run(self, batch: np.ndarray) -> np.ndarray:
+        """batch [N,1,H,W] float32 -> logits [N, num_classes] float32."""
+        return self.session.run(None, {self.input_name: batch})[0]
+
+
+def load_classifier(onnx_path: str | Path) -> Classifier:
+    """Load a .onnx and its `<stem>.classes.json` sidecar (written by export)."""
+    onnx_path = Path(onnx_path)
+    classes_path = onnx_path.with_suffix(".classes.json")
+    classes = json.loads(classes_path.read_text())
+    session = ort.InferenceSession(str(onnx_path), providers=["CPUExecutionProvider"])
+    return Classifier(session, classes)
+
+
+# --------------------------------------------------------------------------- #
+# Cell classification (numpy + ONNX, with test-time augmentation)
+# --------------------------------------------------------------------------- #
+def _softmax(logits: np.ndarray, temperature: float = 1.0) -> np.ndarray:
+    z = logits / temperature
+    z = z - z.max(axis=1, keepdims=True)
+    e = np.exp(z)
+    return e / e.sum(axis=1, keepdims=True)
+
+
+def _tta_views(img: Image.Image):
+    """Slightly shifted crops of one cell - averaging their predictions
+    smooths out crop-alignment luck (measured: sheet 1 29 -> 36/39 exact)."""
+    w, h = img.size
+    views = []
+    for dx, dy in TTA_SHIFTS:
+        views.append(img.crop((max(0, dx), max(0, dy), w + min(0, dx), h + min(0, dy))))
+    return views
+
+
+def classify_cells(images, clf: Classifier, temperature=1.0, tta=True, batch_size=64):
+    """Class probabilities per cell, averaged over TTA views."""
+    views_per_cell = len(TTA_SHIFTS) if tta else 1
+    tensors = []
+    for img in images:
+        for view in _tta_views(img) if tta else [img]:
+            tensors.append(preprocess_pil(view))
+    if not tensors:
+        return np.empty((0, len(clf.classes)), dtype=np.float32)
+
+    probs_chunks = []
+    for i in range(0, len(tensors), batch_size):
+        batch = np.stack(tensors[i : i + batch_size]).astype(np.float32)
+        probs_chunks.append(_softmax(clf.run(batch), temperature))
+    stacked = np.concatenate(probs_chunks, axis=0)
+    return stacked.reshape(len(images), views_per_cell, -1).mean(axis=1)
+
+
+# --------------------------------------------------------------------------- #
+# Legal-move scoring, kazan evidence, beam search  (numpy port)
+# --------------------------------------------------------------------------- #
+def _legal_scores(probs, legal_moves, classes, class_idx):
+    """Redistribute the 162-class distribution over the current legal moves.
+
+    A legal move earns credit from (a) its exact class string and (b) a
+    factorized term P(source digit) * P(landing digit), times agreement with
+    the written x-mark probability. Scores stay UNNORMALIZED for the beam so a
+    hypothesis whose legal set explains the observation poorly accumulates a
+    genuinely low joint likelihood (measured: 24/39 vs 29/39 when normalized).
+    """
+    source_marginal = [0.0] * 9
+    landing_marginal = [0.0] * 9
+    x_marginal = 0.0
+    for c, p in zip(classes, probs.tolist()):
+        if c == "empty":
+            continue
+        source_marginal[int(c[0]) - 1] += p
+        landing_marginal[int(c[1]) - 1] += p
+        if c.endswith("x"):
+            x_marginal += p
+
+    scored = []
+    for move in legal_moves:
+        exact = float(probs[class_idx[move.notation]])
+        factorized = source_marginal[move.action] * landing_marginal[int(move.notation[1]) - 1] * 9
+        x_agreement = x_marginal if move.makes_tuzdyk else 1.0 - x_marginal
+        scored.append(
+            ((EXACT_WEIGHT * exact + FACTOR_WEIGHT * factorized) * x_agreement, move)
+        )
+    total = sum(s for s, _ in scored) or 1.0
+    return sorted(((s, s / total, m) for s, m in scored), key=lambda t: -t[0])
+
+
+def _result_consistency(game: Game, result: str | None) -> int:
+    """How well a final hypothesis state matches how the game really ended."""
+    if result is None:
+        return 1 if game.is_over else 0
+    want = RESULT_CODES[result]
+    if game.is_over and game.winner() == want:
+        return 2
+    kazans = game.kazans
+    leader = -1 if kazans[0] == kazans[1] else (0 if kazans[0] > kazans[1] else 1)
+    return 1 if leader == want else 0
+
+
+def _kazan_logp(game: Game, checkpoint_probs) -> float:
+    """Log-likelihood of a hypothesis' kazan counts under the checkpoint reads."""
+    logp = 0.0
+    for side, player in (("W", 0), ("B", 1)):
+        probs = checkpoint_probs.get(side)
+        if probs is None:
+            continue
+        value = game.kazans[player]
+        p = float(probs[value]) if value < len(probs) else 0.0
+        logp += math.log(max(p, KAZAN_FLOOR))
+    return logp
+
+
+def beam_decode(ply_probs, classes, beam_width=1024, per_ply=9, result=None,
+                checkpoints=None):
+    """Longest fully-legal move sequence with the highest joint probability,
+    exploring all `per_ply` legal continuations per ply; the final pool is
+    re-ranked by kazan-checkpoint and known-result consistency.
+
+    Returns (annotated_moves, log_prob, per_ply_share_list).
+    """
+    checkpoints = checkpoints or {}
+    class_idx = {c: i for i, c in enumerate(classes)}
+    active = [(Game(), [], [], 0.0)]  # (game, annotated_moves, chosen_shares, logp)
+    finished = []
+
+    for probs in ply_probs:
+        expanded = []
+        for game, moves, chosen, logp in active:
+            candidates = _legal_scores(probs, game.legal_moves(), classes, class_idx)
+            for raw, share, move in candidates[:per_ply]:
+                nxt = game.copy()
+                played = nxt.play(move.action)
+                annotated = played.notation + ("+" if played.captured else "")
+                new_logp = logp + math.log(max(raw, 1e-12))
+                if len(moves) + 1 in checkpoints:
+                    new_logp += _kazan_logp(nxt, checkpoints[len(moves) + 1])
+                hyp = (nxt, moves + [annotated], chosen + [share], new_logp)
+                (finished if nxt.is_over else expanded).append(hyp)
+        if not expanded:
+            break
+        active = sorted(expanded, key=lambda h: -h[3])[:beam_width]
+
+    pool = active + finished
+    best = max(pool, key=lambda h: (len(h[1]), _result_consistency(h[0], result), h[3]))
+    return best[1], best[3], best[2]
+
+
+def format_pgn(plies: list[str]) -> str:
+    """plies -> '1. 54+ 42x' lines (one White/Black pair per line)."""
+    lines = []
+    for i in range(0, len(plies), 2):
+        pair = " ".join(plies[i : i + 2])
+        lines.append(f"{i // 2 + 1}. {pair}")
+    return "\n".join(lines) + "\n"
+
+
+# --------------------------------------------------------------------------- #
+# The single entry point
+# --------------------------------------------------------------------------- #
+def run_pipeline(image, moves_clf: Classifier, kazan_clf: Classifier | None = None,
+                 result=None, topk=5, beam_width=1024, per_ply=9,
+                 temperature=1.0, tta=True, save_cells_dir=None):
+    """Read one scoresheet image into game records.
+
+    `image` is a path or a PIL.Image. Returns a dict with the reconstructed
+    PGNs and diagnostics; no files are written unless `save_cells_dir` is set
+    (the CLI uses it, the Gradio app does not).
+
+    Keys: beam_pgn, raw_pgn, legal_pgn, game_json (dict), stopped,
+    plies_scanned, legal_plies, beam_plies, kazan_report, annotated_image (PIL),
+    median_cell_height, low_resolution (bool).
+    """
+    classes = moves_clf.classes
+    empty_idx = classes.index(EMPTY)
+
+    cells, sheet = extract_cells(image)
+    cells.sort(key=lambda c: (c.move_no, c.side != "W"))  # game order: 1W 1B 2W ...
+    median_h = sorted(c.bbox[3] for c in cells)[len(cells) // 2]
+
+    cleaned = [clean_cell(c.image) for c in cells]  # (image, ink_ratio) pairs
+    all_probs = classify_cells(
+        [img for img, _ in cleaned], moves_clf, temperature=temperature, tta=tta
+    )
+
+    game = Game()
+    plies, raw_pgn, legal_pgn = [], [], []
+    ply_prob_arrays = []
+    labels = {}
+    stopped = None
+    in_sync = True
+
+    cells_dir = Path(save_cells_dir) if save_cells_dir else None
+    if cells_dir:
+        cells_dir.mkdir(parents=True, exist_ok=True)
+
+    for cell, (clean_img, ink_ratio), probs in zip(cells, cleaned, all_probs):
+        if ink_ratio < MIN_INK_RATIO or int(np.argmax(probs)) == empty_idx:
+            stopped = {"move": cell.move_no, "side": cell.side, "reason": "empty cell"}
+            break
+
+        move_probs = probs.copy()
+        move_probs[empty_idx] = 0.0
+        raw = classes[int(np.argmax(move_probs))]
+
+        legal = {m.notation: m for m in game.legal_moves()} if in_sync else {}
+        topk_idx = np.argsort(-probs)[:topk]
+        entry = {
+            "move": cell.move_no,
+            "side": cell.side,
+            "bbox": list(cell.bbox),
+            "raw": raw,
+            "raw_is_legal": raw in legal if in_sync else None,
+            "legal": sorted(legal),
+            "top5": [[classes[int(i)], round(float(probs[int(i)]), 4)] for i in topk_idx],
+            "probs": {c: round(float(p), 6) for c, p in zip(classes, probs)},
+        }
+        plies.append(entry)
+        ply_prob_arrays.append(probs)
+        if cells_dir:
+            clean_img.save(cells_dir / f"{cell.move_no:02d}_{cell.side}.png")
+
+        if in_sync and raw in legal:
+            played = game.play_notation(raw)
+            annotated = played.notation + ("+" if played.captured else "")
+            raw_pgn.append(annotated)
+            legal_pgn.append(annotated)
+            if game.is_over:
+                stopped = {"move": cell.move_no, "side": cell.side, "reason": "game over",
+                           "winner": ["P1", "P2", "draw"][game.winner()]}
+                in_sync = False
+        else:
+            if in_sync:
+                entry["legal_alternatives"] = sorted(
+                    ((n, round(float(probs[classes.index(n)]), 4)) for n in legal),
+                    key=lambda t: -t[1],
+                )
+                stopped = stopped or {"move": cell.move_no, "side": cell.side,
+                                      "reason": f"illegal move {raw!r}"}
+                in_sync = False
+            raw_pgn.append(raw)
+
+    # kazan checkpoint numbers from the summary strips (every 10 moves)
+    checkpoints, checkpoint_report = {}, []
+    if kazan_clf is not None:
+        kz_cells = [(c, *clean_cell(c.image)) for c in extract_kazan_cells(sheet)]
+        kz_cells = [(c, img) for c, img, ink in kz_cells if ink >= MIN_KAZAN_INK]
+        if kz_cells:
+            kz_probs = classify_cells(
+                [img for _, img in kz_cells], kazan_clf,
+                temperature=temperature, tta=tta,
+            )
+            for (cell, img), probs in zip(kz_cells, kz_probs):
+                if kazan_clf.classes[int(np.argmax(probs))] == EMPTY:
+                    continue
+                values = probs[:82] / max(float(probs[:82].sum()), 1e-9)
+                checkpoints.setdefault(cell.move_no * 2, {})[cell.side] = values
+                top = int(np.argmax(values))
+                checkpoint_report.append(
+                    {"move": cell.move_no, "side": cell.side,
+                     "read": f"{top:02d}", "prob": round(float(values[top]), 4)}
+                )
+                if cells_dir:
+                    img.save(cells_dir / f"kazan_{cell.move_no:02d}_{cell.side}.png")
+
+    beam_moves, beam_logp, beam_shares = beam_decode(
+        ply_prob_arrays, classes, beam_width, per_ply,
+        result=result, checkpoints=checkpoints,
+    )
+    beam_detail = [
+        {"move": p["move"], "side": p["side"], "chosen": m,
+         "prob": round(q, 4), "agrees_with_raw": m.rstrip("+") == p["raw"]}
+        for p, m, q in zip(plies, beam_moves, beam_shares)
+    ]
+    for p, m in zip(plies, beam_moves):
+        labels[(p["move"], p["side"])] = m
+
+    annotated = render_overlay(sheet, cells[: len(plies)], labels)
+
+    game_json = {
+        "plies_scanned": len(plies),
+        "legal_plies": len(legal_pgn),
+        "beam": {"plies": len(beam_moves), "log_prob": round(beam_logp, 3), "moves": beam_detail},
+        "kazan_checkpoints": checkpoint_report,
+        "stopped": stopped or {"reason": "sheet exhausted"},
+        "plies": plies,
+    }
+    return {
+        "beam_pgn": format_pgn(beam_moves),
+        "raw_pgn": format_pgn(raw_pgn),
+        "legal_pgn": format_pgn(legal_pgn),
+        "game_json": game_json,
+        "stopped": stopped or {"reason": "sheet exhausted"},
+        "plies_scanned": len(plies),
+        "legal_plies": len(legal_pgn),
+        "beam_plies": len(beam_moves),
+        "kazan_report": checkpoint_report,
+        "annotated_image": annotated,
+        "median_cell_height": int(median_h),
+        "low_resolution": median_h < MIN_CELL_HEIGHT,
+    }

togyz/preprocess.py

@@ -0,0 +1,52 @@
+"""The single image -> array preprocessing used by training AND inference.
+
+The legacy pipeline failed partly because train and inference normalized
+differently. Every consumer (dataset, eval, predict, the ONNX pipeline) must
+import from here.
+
+This module is deliberately **torch-free** (numpy only) so the serving path
+can import it without pulling in PyTorch. Torch consumers wrap the returned
+array with ``torch.from_numpy(...)``.
+"""
+
+import numpy as np
+from PIL import Image, ImageOps
+
+TARGET_H = 64
+TARGET_W = 128
+MEAN = 0.5
+STD = 0.5
+
+
+def _estimate_background(gray: Image.Image) -> int:
+    """Median of the image border, so padding blends with the paper."""
+    arr = np.asarray(gray)
+    border = np.concatenate([arr[0, :], arr[-1, :], arr[:, 0], arr[:, -1]])
+    return int(np.median(border))
+
+
+def preprocess_pil(img: Image.Image) -> np.ndarray:
+    """PIL image (any mode/size) -> float32 array [1, TARGET_H, TARGET_W]."""
+    img = ImageOps.exif_transpose(img).convert("L")
+    w, h = img.size
+    target_ratio = TARGET_W / TARGET_H
+
+    # Pad (never crop) to the target aspect ratio, centered on paper-colored canvas.
+    if w / h < target_ratio:
+        new_w, new_h = int(round(h * target_ratio)), h
+    else:
+        new_w, new_h = w, int(round(w / target_ratio))
+    if (new_w, new_h) != (w, h):
+        canvas = Image.new("L", (new_w, new_h), color=_estimate_background(img))
+        canvas.paste(img, ((new_w - w) // 2, (new_h - h) // 2))
+        img = canvas
+
+    img = img.resize((TARGET_W, TARGET_H), Image.BILINEAR)
+    arr = np.asarray(img, dtype=np.float32) / 255.0
+    arr = arr[None, :, :]  # add channel axis -> [1, H, W]
+    return (arr - MEAN) / STD
+
+
+def preprocess_file(path: str) -> np.ndarray:
+    with Image.open(path) as img:
+        return preprocess_pil(img)

togyz/rules.py

@@ -0,0 +1,143 @@
+"""Togyzkumalak rules engine, ported from the 9Q C++ engine
+(~/Desktop/9Q/src/togyzkumalak_rules.cpp) and validated against its
+shortest-game replay fixture (tests/test_rules.py).
+
+Notation matches 9Q and the scoresheet classifier classes:
+"{source_hole}{landing_column}" with an "x" suffix when the move creates a
+tuzdyk, e.g. "98", "13x". Source hole and landing column are 1-9; the landing
+column is the pit's index within its own side, regardless of side.
+"""
+
+from dataclasses import dataclass, field
+
+WIN_THRESHOLD = 82
+PITS_PER_SIDE = 9
+
+
+@dataclass
+class Move:
+    action: int  # 0-8 source hole index on the mover's side
+    notation: str  # e.g. "98" or "13x"
+    captured: int  # stones captured by the landing rule (excl. tuzdyk income)
+    makes_tuzdyk: bool
+
+
+@dataclass
+class Game:
+    pits: list[int] = field(default_factory=lambda: [9] * 18)  # P1: 0-8, P2: 9-17
+    kazans: list[int] = field(default_factory=lambda: [0, 0])
+    # tuzdyks[p] = column (0-8) OWNED BY p on the opponent's side, -1 = none
+    tuzdyks: list[int] = field(default_factory=lambda: [-1, -1])
+    to_play: int = 0
+
+    def copy(self) -> "Game":
+        return Game(self.pits[:], self.kazans[:], self.tuzdyks[:], self.to_play)
+
+    # --- core mechanics -------------------------------------------------
+
+    def _side_of(self, pit: int) -> int:
+        return pit // PITS_PER_SIDE
+
+    def _apply(self, action: int) -> Move:
+        """Apply a (legal) move for `to_play`; returns the Move played."""
+        p = self.to_play
+        opp = 1 - p
+        start = p * PITS_PER_SIDE + action
+        stones = self.pits[start]
+
+        if stones == 1:
+            self.pits[start] = 0
+            last = (start + 1) % 18
+            self.pits[last] += 1
+        else:
+            self.pits[start] = 1
+            pit = start
+            for _ in range(stones - 1):
+                pit = (pit + 1) % 18
+                self.pits[pit] += 1
+            last = pit
+
+        # stones sown into a tuzdyk go to its owner's kazan
+        for owner in (0, 1):
+            col = self.tuzdyks[owner]
+            if col >= 0:
+                tuz_pit = (1 - owner) * PITS_PER_SIDE + col
+                if self.pits[tuz_pit]:
+                    self.kazans[owner] += self.pits[tuz_pit]
+                    self.pits[tuz_pit] = 0
+
+        captured = 0
+        makes_tuzdyk = False
+        if self._side_of(last) == opp:
+            col = last % PITS_PER_SIDE
+            count = self.pits[last]
+            if (
+                count == 3
+                and self.tuzdyks[p] == -1
+                and col != PITS_PER_SIDE - 1  # hole 9 can never become a tuzdyk
+                and self.tuzdyks[opp] != col  # no mirrored tuzdyks
+            ):
+                self.tuzdyks[p] = col
+                self.kazans[p] += 3
+                self.pits[last] = 0
+                makes_tuzdyk = True
+            elif count % 2 == 0:
+                captured = count
+                self.kazans[p] += count
+                self.pits[last] = 0
+
+        notation = f"{action + 1}{(last % PITS_PER_SIDE) + 1}"
+        if makes_tuzdyk:
+            notation += "x"
+        self.to_play = opp
+        return Move(action, notation, captured, makes_tuzdyk)
+
+    # --- public API -----------------------------------------------------
+
+    def legal_actions(self) -> list[int]:
+        p = self.to_play
+        opp = 1 - p
+        return [
+            a
+            for a in range(PITS_PER_SIDE)
+            if self.pits[p * PITS_PER_SIDE + a] > 0 and self.tuzdyks[opp] != a
+        ]
+
+    def legal_moves(self) -> list[Move]:
+        """The <=9 legal moves with their exact notation (via simulation)."""
+        return [self.copy()._apply(a) for a in self.legal_actions()]
+
+    def play(self, action: int) -> Move:
+        if action not in self.legal_actions():
+            raise ValueError(f"illegal action {action + 1} for player {self.to_play + 1}")
+        return self._apply(action)
+
+    def play_notation(self, notation: str) -> Move:
+        """Play by full notation string; raises ValueError if not legal."""
+        for move in self.legal_moves():
+            if move.notation == notation:
+                return self._apply(move.action)
+        raise ValueError(f"move {notation!r} is not legal here")
+
+    @property
+    def is_over(self) -> bool:
+        return (
+            max(self.kazans) >= WIN_THRESHOLD
+            or not self.legal_actions()
+        )
+
+    def winner(self) -> int:
+        """0/1 = player, -1 = draw. If the side to move is stuck (atsyrau),
+        the opponent collects the stones remaining on their own side."""
+        kazans = self.kazans[:]
+        if max(kazans) < WIN_THRESHOLD and not self.legal_actions():
+            opp = 1 - self.to_play
+            kazans[opp] += sum(
+                self.pits[opp * PITS_PER_SIDE : (opp + 1) * PITS_PER_SIDE]
+            )
+        if kazans[0] == kazans[1]:
+            return -1
+        return 0 if kazans[0] > kazans[1] else 1
+
+    def side_totals(self) -> tuple[int, int]:
+        return sum(self.pits[:PITS_PER_SIDE]), sum(self.pits[PITS_PER_SIDE:])

togyz/sheet.py

@@ -0,0 +1,298 @@
+"""Locate the 8 printed move tables on a scoresheet photo and crop move cells.
+
+Federation scoresheet layout: two bands of 4 tables (moves 1-40 top,
+41-80 bottom), each table = header row + 10 move rows with columns
+[No | Bast. (White) | Kost. (Black)]. Only these tables are read; the
+header, summary strips, and footer are ignored.
+
+Table boxes are found via printed grid lines (morphology + connected
+components). Row/column separators inside a table are refined from detected
+lines when they are complete, otherwise the known uniform structure is used
+(photos are often too low-res for reliable thin-line detection).
+"""
+
+from dataclasses import dataclass
+
+import cv2
+import numpy as np
+from PIL import Image, ImageOps
+
+TABLES = 8
+ROWS_PER_TABLE = 10  # plus one header row
+# column boundaries as fractions of table width: No | Bast | Kost
+COLUMN_FRACTIONS = (0.0, 0.20, 0.60, 1.0)
+CELL_MARGIN = 0.15  # expand crops; handwriting overflows the printed cells
+
+
+@dataclass
+class Cell:
+    move_no: int  # 1-80
+    side: str  # "W" (Bast.) or "B" (Kost.)
+    bbox: tuple[int, int, int, int]  # x, y, w, h in original image coords
+    image: Image.Image
+    quad: np.ndarray | None = None  # 4x2 original-image corners (tilt-aware)
+
+
+def _grid_mask(gray: np.ndarray) -> np.ndarray:
+    h, w = gray.shape
+    thr = cv2.adaptiveThreshold(
+        gray, 255, cv2.ADAPTIVE_THRESH_MEAN_C, cv2.THRESH_BINARY_INV, 25, 12
+    )
+    horiz = cv2.morphologyEx(
+        thr, cv2.MORPH_OPEN, cv2.getStructuringElement(cv2.MORPH_RECT, (w // 30, 1))
+    )
+    vert = cv2.morphologyEx(
+        thr, cv2.MORPH_OPEN, cv2.getStructuringElement(cv2.MORPH_RECT, (1, h // 40))
+    )
+    return cv2.dilate(cv2.add(horiz, vert), np.ones((3, 3), np.uint8))
+
+
+def _order_corners(points: np.ndarray) -> np.ndarray:
+    """Order 4 points as top-left, top-right, bottom-right, bottom-left."""
+    points = points.reshape(4, 2).astype(np.float32)
+    sums, diffs = points.sum(axis=1), np.diff(points, axis=1).ravel()
+    return np.array(
+        [points[sums.argmin()], points[diffs.argmin()],
+         points[sums.argmax()], points[diffs.argmax()]],
+        np.float32,
+    )
+
+
+def _find_table_quads(gray: np.ndarray) -> list[np.ndarray]:
+    """Corner quads of the 8 move tables (phone photos are tilted, so tables
+    are general quadrilaterals, not axis-aligned rectangles)."""
+    h, w = gray.shape
+    mask = _grid_mask(gray)
+    n, labels, stats, _ = cv2.connectedComponentsWithStats(mask)
+    quads = []
+    for i in range(1, n):
+        if stats[i][2] <= w * 0.1 or stats[i][3] <= h * 0.1:
+            continue
+        component = (labels == i).astype(np.uint8)
+        contours, _ = cv2.findContours(component, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+        hull = cv2.convexHull(max(contours, key=cv2.contourArea))
+        approx = cv2.approxPolyDP(hull, 0.02 * cv2.arcLength(hull, True), True)
+        if len(approx) == 4:
+            quad = _order_corners(approx)
+        else:  # fall back to the min-area rectangle corners
+            quad = _order_corners(cv2.boxPoints(cv2.minAreaRect(hull)))
+        quads.append((cv2.contourArea(quad), quad))
+    if len(quads) < TABLES:
+        raise RuntimeError(
+            f"Found only {len(quads)} move tables (need {TABLES}). "
+            "Check photo quality/framing."
+        )
+    quads = [q for _, q in sorted(quads, key=lambda t: -t[0])[:TABLES]]
+    # split into top/bottom bands by y, order each band left to right
+    quads.sort(key=lambda q: q[:, 1].mean())
+    top = sorted(quads[:4], key=lambda q: q[:, 0].mean())
+    bottom = sorted(quads[4:], key=lambda q: q[:, 0].mean())
+    return top + bottom
+
+
+def _detect_lines(mask: np.ndarray, axis: int, min_frac: float) -> list[int]:
+    """Positions of long line clusters along `axis` (0=rows, 1=cols)."""
+    profile = mask.sum(axis=1 - axis)
+    limit = 255 * mask.shape[1 - axis] * min_frac
+    positions = np.where(profile > limit)[0]
+    clusters: list[list[int]] = []
+    for pos in positions:
+        if clusters and pos - clusters[-1][-1] <= 2:
+            clusters[-1].append(int(pos))
+        else:
+            clusters.append([int(pos)])
+    return [int(np.mean(c)) for c in clusters]
+
+
+UPSCALE = 2  # rectified tables are rendered at 2x for a little more pixel room
+
+
+def _rectify_table(gray: np.ndarray, quad: np.ndarray):
+    """Warp a (possibly tilted) table quad to a flat rectangle.
+
+    Returns (warped gray image, inverse homography back to sheet coords).
+    """
+    top = np.linalg.norm(quad[1] - quad[0])
+    bottom = np.linalg.norm(quad[2] - quad[3])
+    left = np.linalg.norm(quad[3] - quad[0])
+    right = np.linalg.norm(quad[2] - quad[1])
+    tw = int(round((top + bottom) / 2)) * UPSCALE
+    th = int(round((left + right) / 2)) * UPSCALE
+    target = np.array([[0, 0], [tw, 0], [tw, th], [0, th]], np.float32)
+    matrix = cv2.getPerspectiveTransform(quad, target)
+    warped = cv2.warpPerspective(gray, matrix, (tw, th), flags=cv2.INTER_CUBIC)
+    return warped, np.linalg.inv(matrix)
+
+
+def _row_lines(warped: np.ndarray) -> list[int]:
+    """Row separators in a rectified table; uniform fallback."""
+    h, w = warped.shape
+    thr = cv2.adaptiveThreshold(
+        warped, 255, cv2.ADAPTIVE_THRESH_MEAN_C, cv2.THRESH_BINARY_INV, 25, 12
+    )
+    horiz = cv2.morphologyEx(
+        thr, cv2.MORPH_OPEN, cv2.getStructuringElement(cv2.MORPH_RECT, (max(w // 3, 3), 1))
+    )
+    rows = _detect_lines(horiz, axis=0, min_frac=0.4)
+    if len(rows) != ROWS_PER_TABLE + 2:  # header + 10 rows needs 12 lines
+        rows = [round(i * h / (ROWS_PER_TABLE + 1)) for i in range(ROWS_PER_TABLE + 2)]
+    return rows
+
+
+def extract_cells(image) -> tuple[list[Cell], Image.Image]:
+    """All 160 move cells (80 moves x W/B) plus the upright sheet image.
+
+    `image` is a path (str/Path) or a PIL.Image. Each table is
+    perspective-rectified before being split, so cell crops stay aligned even
+    on tilted phone photos.
+    """
+    if isinstance(image, Image.Image):
+        pil = ImageOps.exif_transpose(image).convert("L")
+    else:
+        with Image.open(image) as img:
+            pil = ImageOps.exif_transpose(img).convert("L")
+    gray = np.asarray(pil)
+
+    cells: list[Cell] = []
+    for t, quad in enumerate(_find_table_quads(gray)):
+        warped, inverse = _rectify_table(gray, quad)
+        th, tw = warped.shape
+        rows = _row_lines(warped)
+        cols = [round(f * tw) for f in COLUMN_FRACTIONS]
+        for r in range(ROWS_PER_TABLE):
+            y0, y1 = rows[r + 1], rows[r + 2]  # rows[0..1] is the header
+            for col_index, side in ((1, "W"), (2, "B")):
+                x0, x1 = cols[col_index], cols[col_index + 1]
+                mx = round((x1 - x0) * CELL_MARGIN)
+                my = round((y1 - y0) * CELL_MARGIN)
+                cx0, cy0 = max(0, x0 - mx), max(0, y0 - my)
+                cx1, cy1 = min(tw, x1 + mx), min(th, y1 + my)
+                crop = Image.fromarray(warped[cy0:cy1, cx0:cx1])
+
+                # map the cell corners back onto the original sheet
+                corners = np.array(
+                    [[cx0, cy0], [cx1, cy0], [cx1, cy1], [cx0, cy1]], np.float32
+                ).reshape(-1, 1, 2)
+                sheet_quad = cv2.perspectiveTransform(corners, inverse).reshape(4, 2)
+                x_min, y_min = sheet_quad.min(axis=0)
+                x_max, y_max = sheet_quad.max(axis=0)
+                bbox = (int(x_min), int(y_min), int(x_max - x_min), int(y_max - y_min))
+                cells.append(
+                    Cell(t * ROWS_PER_TABLE + r + 1, side, bbox, crop, sheet_quad)
+                )
+    return cells, pil
+
+
+def extract_kazan_cells(sheet: Image.Image) -> list[Cell]:
+    """Kazan checkpoint boxes from the 8 summary strips between table bands.
+
+    After every 10 moves the scorer records both kazan counts next to a small
+    board diagram: the box protruding ABOVE the strip is the Kost. (Black)
+    kazan, the box BELOW is the Bast. (White) kazan. Returned as Cell objects
+    with move_no = the checkpoint move (10, 20, ... 80) and side "B"/"W".
+    The 2x9 board-pit grid itself is ignored (too messy to read reliably).
+    """
+    gray = np.asarray(sheet)
+    h, w = gray.shape
+    mask = _grid_mask(gray)
+    table_area = float(np.median([cv2.contourArea(q) for q in _find_table_quads(gray)]))
+
+    n, _, stats, _ = cv2.connectedComponentsWithStats(mask)
+    strips = [
+        tuple(int(v) for v in stats[i][:4])
+        for i in range(1, n)
+        if stats[i][2] > w * 0.1
+        and h * 0.02 < stats[i][3] < h * 0.12
+        and stats[i][2] > 1.5 * stats[i][3]
+        and stats[i][2] * stats[i][3] < 0.9 * table_area
+    ]
+    strips.sort(key=lambda b: (b[1] > h / 2, b[0]))  # band, then left-to-right
+
+    cells: list[Cell] = []
+    for k, (x, y, bw, bh) in enumerate(strips[:8]):
+        checkpoint = (k + 1) * 10
+        sub = mask[y : y + bh, x : x + bw]
+        long_rows = np.where((sub > 0).sum(axis=1) > bw * 0.55)[0]
+        if len(long_rows) == 0:
+            continue
+        # kazan boxes are ~1 row tall; a tight zone avoids swallowing the
+        # neighboring table's header text below the strip
+        zones = {
+            "B": (max(0, y + int(long_rows.min()) - 30), y + int(long_rows.min()) - 1, False),
+            "W": (y + int(long_rows.max()) + 3, min(h, y + int(long_rows.max()) + 31), True),
+        }
+        for side, (gy0, gy1, truncate_below) in zones.items():
+            if gy1 - gy0 < 8:
+                continue
+            zone = mask[gy0:gy1, x : x + bw]
+            # stop at any full-width line (a neighboring table's grid)
+            full = np.where((zone > 0).sum(axis=1) > bw * 0.7)[0]
+            if len(full):
+                if truncate_below:
+                    zone = zone[: full.min()]
+                else:
+                    zone = zone[full.max() + 1 :]
+                    gy0 += int(full.max()) + 1
+            ys, xs = np.where(zone > 0)
+            if len(xs) < 15:
+                continue
+            bx0, bx1 = int(xs.min()), int(xs.max())
+            by0, by1 = gy0 + int(ys.min()), gy0 + int(ys.max())
+            if bx1 - bx0 < 10 or by1 - by0 < 8:
+                continue
+            cx0, cy0 = max(0, x + bx0 - 3), max(0, by0 - 2)
+            cx1, cy1 = min(w, x + bx1 + 4), min(h, by1 + 3)
+            cells.append(Cell(
+                checkpoint, side, (cx0, cy0, cx1 - cx0, cy1 - cy0),
+                Image.fromarray(gray[cy0:cy1, cx0:cx1]),
+            ))
+    return cells
+
+
+def clean_cell(image: Image.Image) -> tuple[Image.Image, float]:
+    """Remove printed grid-line fragments from a cell crop.
+
+    Returns the cleaned crop and the fraction of remaining ink pixels
+    (handwriting). Blank cells score near zero even when grid lines cross
+    the crop, so this is a classifier-independent emptiness signal.
+    """
+    gray = np.asarray(image)
+    h, w = gray.shape
+    thr = cv2.adaptiveThreshold(
+        gray, 255, cv2.ADAPTIVE_THRESH_MEAN_C, cv2.THRESH_BINARY_INV, 25, 12
+    )
+    # printed lines: long straight runs spanning most of the crop
+    horiz = cv2.morphologyEx(
+        thr, cv2.MORPH_OPEN, cv2.getStructuringElement(cv2.MORPH_RECT, (max(3, int(w * 0.6)), 1))
+    )
+    vert = cv2.morphologyEx(
+        thr, cv2.MORPH_OPEN, cv2.getStructuringElement(cv2.MORPH_RECT, (1, max(3, int(h * 0.6))))
+    )
+    lines = cv2.dilate(cv2.add(horiz, vert), np.ones((3, 3), np.uint8))
+
+    background = int(np.median(gray[thr == 0])) if (thr == 0).any() else 255
+    cleaned = gray.copy()
+    cleaned[lines > 0] = background
+
+    ink = (thr > 0) & (lines == 0)
+    ink[: h // 8, :] = ink[-h // 8 :, :] = False  # ignore crop edges: neighbor
+    ink[:, : w // 12] = ink[:, -w // 12 :] = False  # rows/cells bleeding in
+    ink_ratio = float(ink.sum()) / (h * w)
+    return Image.fromarray(cleaned), ink_ratio
+
+
+def render_overlay(sheet: Image.Image, cells: list[Cell], labels: dict | None = None) -> Image.Image:
+    """Debug image: cell boxes (green) with optional predicted labels (red)."""
+    vis = cv2.cvtColor(np.asarray(sheet), cv2.COLOR_GRAY2BGR)
+    for cell in cells:
+        x, y, w, h = cell.bbox
+        if cell.quad is not None:
+            cv2.polylines(vis, [cell.quad.astype(np.int32)], True, (0, 180, 0), 1)
+        else:
+            cv2.rectangle(vis, (x, y), (x + w, y + h), (0, 180, 0), 1)
+        if labels:
+            text = labels.get((cell.move_no, cell.side))
+            if text:
+                cv2.putText(vis, text, (x + 2, y + h - 3),
+                            cv2.FONT_HERSHEY_SIMPLEX, 0.45, (0, 0, 255), 1, cv2.LINE_AA)
+    return Image.fromarray(cv2.cvtColor(vis, cv2.COLOR_BGR2RGB))

togyz/synth.py

@@ -0,0 +1,238 @@
+"""Synthesizes realistic scoresheet-cell photos for any of the 163 classes.
+
+Design targets, derived from the real crops in data/real_crops/:
+  * digits are large and fill most of the crop height (tight framing)
+  * cursive right slant, overlapping kerning, variable stroke thickness
+  * mid-gray paper with shading, blue-ink-turned-gray strokes (not black)
+  * phone-camera artifacts: blur, sensor noise, JPEG compression
+  * crop aspect ratio anywhere between ~1:1 and ~3.3:1
+
+Everything is driven by an explicit `random.Random` so the validation set
+can be fully deterministic while training data stays infinite.
+"""
+
+import argparse
+import io
+import math
+import random
+
+import cv2
+import numpy as np
+from PIL import Image
+
+from .classes import CLASSES, EMPTY
+from .glyphs import GlyphSampler
+
+# working resolution: glyphs are rendered at this digit height, the finished
+# cell is later downscaled to a random "photo" size (anti-aliased strokes)
+RENDER_DIGIT_H = 96
+
+
+def _transform_mask(mask: np.ndarray, rot_deg: float, shear: float) -> np.ndarray:
+    """Rotate + italic-shear a glyph mask on an expanded canvas."""
+    h, w = mask.shape
+    pad = int(max(h, w) * 0.4) + 2
+    mask = np.pad(mask, pad)
+    ph, pw = mask.shape
+    center = (pw / 2, ph / 2)
+    m = cv2.getRotationMatrix2D(center, rot_deg, 1.0)
+    # italic shear: top of the glyph shifts right relative to the bottom
+    shear_m = np.array([[1.0, -shear, shear * ph / 2], [0.0, 1.0, 0.0]])
+    full = np.vstack([shear_m, [0, 0, 1]]) @ np.vstack([m, [0, 0, 1]])
+    out = cv2.warpAffine(mask, full[:2], (pw, ph), flags=cv2.INTER_LINEAR)
+    ys, xs = np.where(out > 0.1)
+    if len(ys) == 0:
+        return mask
+    return out[ys.min() : ys.max() + 1, xs.min() : xs.max() + 1]
+
+
+def _vary_thickness(mask: np.ndarray, rng: random.Random) -> np.ndarray:
+    op = rng.choice(["dilate", "none", "dilate", "erode", "none"])
+    if op == "none":
+        return mask
+    kernel = np.ones((2, 2), np.uint8)
+    fn = cv2.dilate if op == "dilate" else cv2.erode
+    return fn(mask, kernel, iterations=1)
+
+
+def _paper(rng: random.Random, h: int, w: int) -> np.ndarray:
+    base = rng.uniform(160, 235)
+    img = np.full((h, w), base, np.float32)
+    ys, xs = np.mgrid[0:h, 0:w].astype(np.float32)
+    # linear lighting gradient
+    gx, gy = rng.uniform(-1, 1), rng.uniform(-1, 1)
+    plane = gx * xs / max(w, 1) + gy * ys / max(h, 1)
+    ptp = plane.max() - plane.min()
+    if ptp > 1e-6:
+        img += rng.uniform(0, 22) * ((plane - plane.min()) / ptp - 0.5)
+    # occasional soft shadow blob
+    if rng.random() < 0.4:
+        cx, cy = rng.uniform(0, w), rng.uniform(0, h)
+        r = rng.uniform(0.5, 1.3) * max(w, h)
+        d2 = ((xs - cx) ** 2 + (ys - cy) ** 2) / (r * r)
+        img -= rng.uniform(5, 20) * np.exp(-d2)
+    return img
+
+
+def _compose_ink(paper: np.ndarray, alpha: np.ndarray, rng: random.Random) -> np.ndarray:
+    """Blend an ink alpha mask onto paper with per-pixel ink tone variation."""
+    ink_base = rng.uniform(30, 110)
+    ink = ink_base + np.random.default_rng(rng.getrandbits(63)).normal(
+        0, 8, paper.shape
+    ).astype(np.float32)
+    alpha = np.clip(alpha, 0.0, 1.0) * rng.uniform(0.85, 1.0)
+    return paper * (1 - alpha) + ink * alpha
+
+
+def _add_border_lines(img: np.ndarray, rng: random.Random) -> np.ndarray:
+    """Fragment of the printed cell border caught by an imperfect crop."""
+    h, w = img.shape
+    edge = rng.choice(["top", "bottom", "left", "right"])
+    offset = rng.randint(0, max(1, int(0.06 * min(h, w))))
+    darkness = rng.uniform(60, 140)
+    thickness = rng.randint(1, 3)
+    if edge in ("top", "bottom"):
+        y = offset if edge == "top" else h - 1 - offset
+        x0, x1 = sorted((rng.randint(0, w // 2), rng.randint(w // 2, w - 1)))
+        cv2.line(img, (x0, y), (x1, y), darkness, thickness, cv2.LINE_AA)
+    else:
+        x = offset if edge == "left" else w - 1 - offset
+        y0, y1 = sorted((rng.randint(0, h // 2), rng.randint(h // 2, h - 1)))
+        cv2.line(img, (x, y0), (x, y1), darkness, thickness, cv2.LINE_AA)
+    return img
+
+
+def _camera_effects(img: np.ndarray, rng: random.Random) -> np.ndarray:
+    # optical blur
+    img = cv2.GaussianBlur(img, (0, 0), rng.uniform(0.4, 1.4))
+    # occasional slight motion blur
+    if rng.random() < 0.15:
+        k = rng.choice([3, 5])
+        kernel = np.zeros((k, k), np.float32)
+        angle = rng.uniform(0, math.pi)
+        cv2.line(
+            kernel,
+            (0, int((k - 1) / 2 * (1 - math.sin(angle)))),
+            (k - 1, int((k - 1) / 2 * (1 + math.sin(angle)))),
+            1.0,
+            1,
+        )
+        kernel /= max(kernel.sum(), 1e-6)
+        img = cv2.filter2D(img, -1, kernel)
+    # sensor noise
+    noise_rng = np.random.default_rng(rng.getrandbits(63))
+    img = img + noise_rng.normal(0, rng.uniform(1.5, 7.0), img.shape).astype(np.float32)
+    # brightness / contrast jitter
+    img = (img - 128.0) * rng.uniform(0.82, 1.15) + 128.0 + rng.uniform(-15, 15)
+    img = np.clip(img, 0, 255).astype(np.uint8)
+    # JPEG artifacts
+    if rng.random() < 0.6:
+        ok, buf = cv2.imencode(".jpg", img, [cv2.IMWRITE_JPEG_QUALITY, rng.randint(25, 85)])
+        if ok:
+            img = cv2.imdecode(buf, cv2.IMREAD_GRAYSCALE)
+    return img
+
+
+def synthesize_cell(
+    class_name: str, sampler: GlyphSampler, rng: random.Random
+) -> Image.Image:
+    """Render one cell photo for `class_name` ('11'..'99x' or 'empty')."""
+    if class_name == EMPTY:
+        h = rng.randint(60, 180)
+        w = int(h * rng.uniform(1.2, 3.3))
+        img = _paper(rng, h, w)
+        if rng.random() < 0.25:
+            img = _add_border_lines(img, rng)
+        return Image.fromarray(_camera_effects(img, rng))
+
+    # --- prepare glyph masks ---
+    slant = rng.uniform(-0.10, 0.40)  # shared cursive slant, biased rightward
+    masks = []
+    for char in class_name:
+        mask = sampler.sample(char, rng)
+        rel_h = rng.uniform(0.5, 0.8) if char == "x" else rng.uniform(0.85, 1.15)
+        target_h = max(8, int(RENDER_DIGIT_H * rel_h))
+        target_w = max(4, int(mask.shape[1] * target_h / mask.shape[0]))
+        mask = cv2.resize(mask, (target_w, target_h), interpolation=cv2.INTER_LINEAR)
+        mask = _transform_mask(mask, rng.uniform(-7, 7), slant + rng.uniform(-0.05, 0.05))
+        mask = _vary_thickness(mask, rng)
+        masks.append(mask)
+
+    gaps = [
+        int(rng.uniform(-0.18, 0.15) * masks[i].shape[1])
+        for i in range(len(masks) - 1)
+    ]
+    total_w = sum(m.shape[1] for m in masks) + sum(gaps)
+    max_h = max(m.shape[0] for m in masks)
+
+    # --- cell geometry: digits fill `fill` of the crop height ---
+    fill = rng.uniform(0.45, 0.92)
+    cell_h = int(max_h / fill)
+    aspect = rng.uniform(0.95, 3.3)
+    cell_w = max(int(cell_h * aspect), int(total_w * rng.uniform(1.02, 1.2)))
+
+    # horizontal placement: real crops are sometimes left-aligned with empty space
+    slack = cell_w - total_w
+    align = rng.random()
+    if align < 0.35:  # left
+        x = int(slack * rng.uniform(0.0, 0.15))
+    elif align < 0.85:  # center-ish
+        x = int(slack * rng.uniform(0.25, 0.6))
+    else:  # right
+        x = int(slack * rng.uniform(0.7, 0.95))
+
+    # --- compose ink alpha on full-cell canvas ---
+    alpha = np.zeros((cell_h, cell_w), np.float32)
+    y_center = (cell_h - max_h) / 2
+    for i, mask in enumerate(masks):
+        mh, mw = mask.shape
+        y = int(y_center + (max_h - mh) * rng.uniform(0.2, 0.8) + rng.uniform(-0.04, 0.04) * cell_h)
+        y = min(max(y, 0), cell_h - mh)
+        x = min(max(x, 0), cell_w - mw)
+        region = alpha[y : y + mh, x : x + mw]
+        np.maximum(region, mask, out=region)
+        if i < len(gaps):
+            x += mw + gaps[i]
+
+    img = _compose_ink(_paper(rng, cell_h, cell_w), alpha, rng)
+    if rng.random() < 0.12:
+        img = _add_border_lines(img, rng)
+
+    # downscale to a random photo resolution (real crops are 115-260 px tall)
+    out_h = rng.randint(48, 190)
+    out_w = max(16, int(cell_w * out_h / cell_h))
+    img = cv2.resize(img, (out_w, out_h), interpolation=cv2.INTER_AREA)
+
+    return Image.fromarray(_camera_effects(img, rng))
+
+
+def _preview(path: str, seed: int, count: int) -> None:
+    """Render a comparison grid: the real-crop classes first, then random ones."""
+    sampler = GlyphSampler()
+    rng = random.Random(seed)
+    fixed = ["96", "77", "13x", "37", "85", "42"] * 2
+    names = fixed + [rng.choice(CLASSES) for _ in range(max(0, count - len(fixed)))]
+
+    tile_w, tile_h, caption = 200, 100, 14
+    cols = 6
+    rows = math.ceil(len(names) / cols)
+    sheet = Image.new("L", (cols * tile_w, rows * (tile_h + caption)), 255)
+    from PIL import ImageDraw
+
+    draw = ImageDraw.Draw(sheet)
+    for i, name in enumerate(names):
+        cell = synthesize_cell(name, sampler, rng).resize((tile_w, tile_h))
+        cx, cy = (i % cols) * tile_w, (i // cols) * (tile_h + caption)
+        sheet.paste(cell, (cx, cy + caption))
+        draw.text((cx + 4, cy + 1), name, fill=0)
+    sheet.save(path)
+    print(f"Saved {len(names)}-cell preview to {path}")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--preview", default="preview.png", help="output image path")
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument("--n", type=int, default=48, help="number of cells")
+    args = parser.parse_args()
+    _preview(args.preview, args.seed, args.n)