HercUNet v0 — iterative surface (sheet) refiner for Herculaneum scrolls
HercUNet is a self-refining U-Net that detects the medial surfaces (sheets) of rolled papyrus in carbonised
Herculaneum scrolls from X-ray µCT. This is v0 (the run301 model): the iterative AffinityMalis +
online-DAgger refiner D(CT, prev) → surface, warm-started from the ScrollPrize m7 surface detector and
trained on our stage-1 ∇φ pseudo-labels plus a mined m7 rehearsal corpus.
- 📦 Code + docs: https://github.com/jimmylomro/hercUNet
- 🗂️ Training corpus: https://huggingface.co/datasets/jimmylomro/hercunet-corpus
Files (a standard nnU-Net trained-model folder)
| File | What |
|---|---|
plans.json |
nnUNetResEncUNetLPlans, patched to 5 input channels (CT + 4 candidate/prev crests). |
dataset.json |
channels {CT, cand0..3}, labels {background:0, surface:1, ignore:2}, Tiff3DIO. |
dataset_fingerprint.json |
nnU-Net fingerprint. |
fold_0/checkpoint_best.pth |
the champion weights (best EMA). |
fold_0/checkpoint_latest.pth |
last checkpoint (for --continue resume). |
fold_0/training_log_*.txt, progress.png |
training provenance. |
Use it
Install HercUNet (pip install -e ".[train]" from the repo), then warm-start / re-train / fine-tune from this
model — the checkpoint is pulled from this repo automatically:
hercunet train fit --dataset <NNN> --pretrained-hf jimmylomro/hercunet-v0
--pretrained-hf downloads checkpoint_best.pth and loads it (expanding the input stem as needed). See
docs/training.md.
⚠️ Inference is not nnUNetv2_predict
HercUNet's network is not a plain ResEncUNet: the trainer builds an 8-channel stem [CT, prev, orientation×6] + an affinity head, and inference is iterative (feed the previous pass's softmax back in,
Jacobi-blend). plans.json describes only the base geometry — the stem, the head, and the iteration live in
the hercunet code. So this checkpoint is loadable by anyone, but running it requires hercunet
inference, not stock nnUNetv2_predict (which would silently build the wrong network).
Recipe & provenance
Trainer nnUNetTrainer_AffinityMalis_IterDagger_500epochs, K=4 candidate channels. The exact
hyperparameters are the shipped recipe
hercunet/recipes/hercunet.yml
(run301). Methodology: the write-up in the repo (submission/writeup/).
License: see the GitHub repository.