README.md

---
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).