Recto-surface 3D segmentation U-Net (ps256) — checkpoints + model card (arXiv:2606.29085)

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,83 @@
+---
+license: mit
+tags:
+- arxiv:2606.29085
+- vesuvius-challenge
+- herculaneum
+- papyrology
+- computed-tomography
+- surface-detection
+- 3d-segmentation
+- resenc-unet
+- volumetric-imaging
+pipeline_tag: image-segmentation
+---
+
+# Recto-surface 3D segmentation U-Net (`ps256`)
+
+Volumetric **3D U-Net** that segments the **recto writing surface** of carbonized
+Herculaneum papyri directly in micro-CT volumes. It is the recto-surface predictor
+used in the pipeline behind *"Complete virtual unwrapping and reading of a rolled
+Herculaneum papyrus"* (Angelotti et al., **arXiv:2606.29085**, 2026).
+
+## Model details
+
+| | |
+|---|---|
+| Architecture | nnU-Net-style **3D residual-encoder U-Net** with concurrent spatial+channel squeeze-and-excitation (scSE) |
+| Instantiated via | `vesuvius` `NetworkFromConfig` (config bundled as `config.json`) |
+| `model_name` | `ps256_bs2_msr_default` |
+| Input | 1-channel CT, **256 × 256 × 256** patches, z-score normalised |
+| Output | 2 channels (surface vs background), `ignore_label = 2` |
+| Encoder | `features_per_stage` [32, 64, 128, 256, 320, 320, 320]; `n_blocks_per_stage` [1, 3, 4, 6, 6, 6, 6]; 3×3×3 kernels; stride-2 downsampling |
+| Loss | Medial Surface Recall (Skeleton-Recall-style) + Dice/CE |
+| Checkpoint | epoch 3504 · W&B run `d5jdo9n1` |
+
+## Training data
+
+Manually annotated recto surfaces (voxelised from surface meshes) of
+**PHerc. 0139, 1667, 0343P, 0500P2, MAN Bp** (~116.5k training / ~2.4k validation
+patches). Full training configuration is in **Supplementary Table 1** of the paper.
+
+## Files
+
+- `checkpoint_inference_ready.pth` — full checkpoint; network weights are under key `model` (808 tensors). The architecture config is embedded under `model_config` and mirrored in `config.json`.
+- `config.json` — architecture config for `NetworkFromConfig`.
+
+## How to load
+
+```python
+import torch
+ck    = torch.load("checkpoint_inference_ready.pth", map_location="cpu", weights_only=False)
+state = ck["model"]            # state_dict
+cfg   = ck["model_config"]     # == config.json
+# Build the network with the vesuvius package (NetworkFromConfig(cfg)), then:
+# net.load_state_dict(state)
+```
+The `vesuvius` package and inference code are in <https://github.com/ScrollPrize/villa>.
+
+## Links
+
+- **Paper:** Angelotti et al., *Complete virtual unwrapping and reading of a rolled Herculaneum papyrus.* arXiv:2606.29085 (2026). <https://arxiv.org/abs/2606.29085>
+- **Code:** <https://github.com/ScrollPrize/villa>
+- **Data:** <https://scrollprize.org/data_browser> · ESRF: <https://cultural-heritage.esrf.fr/tomo>
+- **Vesuvius Challenge:** <https://scrollprize.org>
+
+## Citation
+
+```bibtex
+@misc{angelotti2026unwrapping,
+  title         = {Complete virtual unwrapping and reading of a rolled Herculaneum papyrus},
+  author        = {Angelotti, Giorgio and others},
+  year          = {2026},
+  eprint        = {2606.29085},
+  archivePrefix = {arXiv},
+  primaryClass  = {eess.IV},
+  doi           = {10.48550/arXiv.2606.29085}
+}
+```
+
+## License
+
+**MIT** — released by the Vesuvius Challenge. Note: the underlying tomographic data
+are distributed under **CC BY-NC 4.0** (see the data links above).

checkpoint_inference_ready.pth

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

config.json

@@ -0,0 +1,163 @@
+{
+  "squeeze_excitation": true,
+  "squeeze_excitation_type": "scse",
+  "patch_size": [
+    256,
+    256,
+    256
+  ],
+  "train_patch_size": [
+    256,
+    256,
+    256
+  ],
+  "batch_size": 2,
+  "train_batch_size": 2,
+  "targets": {
+    "surface": {
+      "valid_patch_value": 1,
+      "activation": "none",
+      "ignore_label": 2,
+      "losses": [
+        {
+          "name": "MedialSurfaceRecall",
+          "weight": 1.0
+        }
+      ],
+      "out_channels": 2
+    }
+  },
+  "model_name": "ps256_bs2_msr_default",
+  "in_channels": 1,
+  "enable_deep_supervision": false,
+  "features_per_stage": [
+    32,
+    64,
+    128,
+    256,
+    320,
+    320,
+    320
+  ],
+  "n_blocks_per_stage": [
+    1,
+    3,
+    4,
+    6,
+    6,
+    6,
+    6
+  ],
+  "kernel_sizes": [
+    [
+      3,
+      3,
+      3
+    ],
+    [
+      3,
+      3,
+      3
+    ],
+    [
+      3,
+      3,
+      3
+    ],
+    [
+      3,
+      3,
+      3
+    ],
+    [
+      3,
+      3,
+      3
+    ],
+    [
+      3,
+      3,
+      3
+    ],
+    [
+      3,
+      3,
+      3
+    ]
+  ],
+  "strides": [
+    [
+      1,
+      1,
+      1
+    ],
+    [
+      2,
+      2,
+      2
+    ],
+    [
+      2,
+      2,
+      2
+    ],
+    [
+      2,
+      2,
+      2
+    ],
+    [
+      2,
+      2,
+      2
+    ],
+    [
+      2,
+      2,
+      2
+    ],
+    [
+      2,
+      2,
+      2
+    ]
+  ],
+  "pool_op_kernel_sizes": [
+    [
+      1,
+      1,
+      1
+    ],
+    [
+      2,
+      2,
+      2
+    ],
+    [
+      2,
+      2,
+      2
+    ],
+    [
+      2,
+      2,
+      2
+    ],
+    [
+      2,
+      2,
+      2
+    ],
+    [
+      2,
+      2,
+      2
+    ],
+    [
+      2,
+      2,
+      2
+    ]
+  ],
+  "separate_decoders": true
+}