Add model card

README.md

@@ -0,0 +1,124 @@
+---
+license: other
+tags:
+  - change-detection
+  - object-detection
+  - document-analysis
+  - centernet
+  - siamese
+library_name: pytorch
+---
+
+# CyberAI Cup 2026 — Task 1: Packaging Material Difference Mining
+
+Complete working state of the solution: trained weights, all source code, documentation, and the raw
+evidence behind every reported number. Private repository — this is a working handover, not a release.
+
+## Current result
+
+Fold-0 out-of-fold **global F1 0.9049** (precision 0.9225, recall 0.8881, score threshold 0.31),
+measured on 40 held-out validation pairs with the competition's own metric: TP/FP/FN accumulated
+across all images before computing precision and recall, boxes matched at IoU ≥ 0.5.
+
+For scale, the classical image-difference baseline scores **0.029** on the same split.
+
+Folds 1–4 are untrained and no submission has been generated. `HANDOVER.md` section 5 holds the
+prioritized queue for whoever continues.
+
+## What is in here
+
+| Path | Contents |
+|---|---|
+| `checkpoints/stage1_fold0_convnext_tiny/best.pt` | The model — 128 MB, epoch 19, the 0.9049 checkpoint |
+| `checkpoints/stage1_fold0_convnext_tiny/last.pt` | 384 MB, epoch 35, with optimizer and scheduler state for resuming |
+| `checkpoints/oof/` | Out-of-fold candidate boxes and the threshold sweep |
+| `checkpoints/stage2_ab/` | Verifier from the A/B test — reference only, its measured delta was +0.0009 |
+| `src/pmdm/` | 14 modules, ~1500 lines: preprocessing, model, losses, decoding, training, inference, metric |
+| `modal_app.py` | Every Modal function and entrypoint used to produce these results |
+| `scripts/` | CPU smoke test, local training without Modal, dataset analysis, error analysis |
+| `runs/` | Raw training logs, per-epoch history, and analysis output from every run |
+| `Task1/` | The competition dataset: 200 training pairs with 1407 annotated boxes, 100 test pairs |
+| `HANDOVER.md` | Start here — architecture, results, error breakdown, mistakes, next steps |
+| `RUNBOOK.md` | Every command with measured timings |
+| `IMPLEMENTATION_PLAN.md` | Original design rationale |
+
+## Architecture
+
+A siamese CenterNet. Both images pass through a shared ConvNeXt-tiny encoder taking 4 channels
+(BGR plus a local-background-normalized "ink map" that makes the features invariant to the photo's
+shadows). Features fuse per scale as `conv(concat(a, b, |a − b|))`, decode through a U-Net upsampling
+path, and emit four heads at **output stride 2** — a Gaussian focal heatmap for difference centers,
+width/height, a sub-pixel offset, and an auxiliary change-mask segmentation.
+
+Stride 2 is the load-bearing choice: 83 of the ground-truth boxes are 8×8 pixels, which vanish
+entirely at the stride 4 a standard CenterNet uses.
+
+Three things about the data drove the rest of the design:
+
+1. **Pairs are already sub-pixel aligned.** Of 300 pairs, 284 need no registration at all and 16 need
+   a pure translation. No warping is applied by default.
+2. **Blur, not geometry, is the dominant false-positive source.** The photo is softer than the
+   template, so the template is blur-matched to it with a σ grid search minimizing the
+   Laplacian-variance gap before any comparison.
+3. **Nothing is ever deleted.** Of 1404 analysed boxes, 842 are additions and 558 are modifications
+   of existing content — and exactly 0 are deletions. That licenses a polarity filter discarding any
+   candidate that is inked in the template and blank in the photo.
+
+Inference tiles each page at 768 px with 25% overlap, then merges candidates with Weighted Boxes
+Fusion rather than NMS — with boxes this small, averaging the coordinates beats picking one.
+
+## Loading the model
+
+```python
+import torch
+from pmdm.model import SiamCenterNet
+
+model = SiamCenterNet(backbone="convnext_tiny")
+ck = torch.load("checkpoints/stage1_fold0_convnext_tiny/best.pt", map_location="cpu")
+model.load_state_dict(ck["model"])   # all keys match
+model.eval()
+```
+
+`ck["metric"]` carries the evaluation that selected this checkpoint, including the 0.31 threshold.
+Full tiled inference over a page is `pmdm.infer`; scoring is `pmdm.metric.global_f1`.
+
+## Reproducing
+
+```bash
+uv venv --python 3.12 .venv
+uv pip install --python .venv/bin/python -e . torch torchvision timm \
+    opencv-python-headless "numpy<2" pandas
+
+# CPU pre-flight over the whole pipeline, ~2 min
+PMDM_DATA=Task1/PackagingMaterialDifferenceMiningDataset \
+PMDM_WORK=/tmp/pmdm_work PMDM_CKPT=/tmp/pmdm_ckpt \
+.venv/bin/python scripts/local_smoke.py
+
+# every dataset claim above
+PMDM_DATA=Task1/PackagingMaterialDifferenceMiningDataset \
+.venv/bin/python scripts/analyze_dataset.py
+
+# the error breakdown, from the archived out-of-fold predictions
+.venv/bin/python scripts/error_analysis.py checkpoints/oof/fold0_convnext_tiny.npz
+```
+
+Training runs either on Modal (`modal run --detach modal_app.py::train --fold 0 --epochs 40`,
+~45 min on an A100-40GB) or on any GPU box with no Modal account
+(`python scripts/train_local.py --fold 0 --epochs 40`). Same loop, same checkpoints.
+
+## Where the remaining errors are
+
+Of 268 ground-truth boxes across the validation fold: 252 were proposed and matched, 5 were proposed
+but localized too loosely to clear IoU 0.5, and 11 were never proposed at all — a recall ceiling of
+0.959 for the current proposal stage.
+
+By box size, the picture is lopsided: boxes above 24 px match 97.5% of the time, 12–24 px match
+97.9%, and boxes under 12 px match 82.8%. **Ten of the eleven complete misses are sub-12px marks.**
+Everything else is solved. That is why the next step is synthetic data weighted toward tiny marks
+(`src/pmdm/synth.py`, written and smoke-tested but never run at scale) rather than more box
+refinement or a stronger verifier.
+
+## License
+
+The dataset in `Task1/` belongs to the CyberAI Cup 2026 organizers and is included here only so this
+private repository is self-contained for the team. Do not redistribute it.