README.md

---
license: apache-2.0
library_name: nnunet
pipeline_tag: image-segmentation
tags:
  - vesuvius-challenge
  - surface-detection
  - nnunet
  - segmentation
  - papyrus
---

# surface_m7_nnunet

An [nnU-Net (v2)](https://github.com/MIC-DKFZ/nnUNet) model for **surface segmentation** of
Herculaneum papyrus CT volumes. This is the nnU-Net component (internally "m7") of the
**1st-place solution** to the Kaggle *Vesuvius Challenge – Surface Detection* competition.

> **Note:** This is a *partial component* of that solution — the standalone nnU-Net model — not
> the full ensemble/architecture described in the writeup.

**Source writeup:** [1st-place solution for the Vesuvius Challenge – Surface Detection](https://kaggle.com/competitions/vesuvius-challenge-surface-detection/writeups/1st-place-solution-for-the-vesuvius-challenge-su)

## Model details

- **Framework:** nnU-Net v2
- **Dataset:** `Dataset100_VesuviusSurface` (786 training volumes)
- **Input:** single channel `CT`, read from `.tif` via nnU-Net's `SimpleTiffIO`
- **Labels:** `background = 0`, `surface = 1`, `ignore = 2`
- **Plans:** `nnUNetResEncUNetLPlans` — Residual Encoder U-Net, "L" preset
  (`dynamic_network_architectures...ResidualEncoderUNet`)
- **Configurations defined in the plans:**
  - `2d` — patch size `320 × 320`
  - `3d_fullres` — patch size `192 × 192 × 192`, spacing `1.0³`
- **Checkpoint:** best checkpoint for a single fold (`fold_0`).

## Files

```
dataset.json                 # channels / labels / dataset metadata
dataset_fingerprint.json     # nnU-Net dataset fingerprint
plans.json                   # nnU-Net plans (2d + 3d_fullres configs)
fold_0/
  checkpoint_best.pth        # trained weights (best checkpoint), ~783 MB
```

The layout is the standard nnU-Net trained-model folder, so it can be used directly as an
`nnUNet_results` model directory.

## Usage

Download the repo and point nnU-Net v2 at it as a results directory:

```python
from huggingface_hub import snapshot_download

model_dir = snapshot_download(repo_id="scrollprize/surface_m7_nnunet")
# `model_dir` now contains dataset.json, plans.json, fold_0/checkpoint_best.pth
```

Then run inference with `nnUNetv2_predict` (or the `nnUNetPredictor` API), selecting the
configuration that matches this checkpoint (`3d_fullres` or `2d`) and `-f 0` for the single
provided fold. See the [nnU-Net v2 inference docs](https://github.com/MIC-DKFZ/nnUNet/blob/master/documentation/how_to_use_nnunet.md#run-inference).

## Attribution & license

The model originates from the 1st-place Kaggle *Vesuvius Challenge – Surface Detection* solution
(linked above); please credit the original authors. Released here under Apache-2.0 to match the
other Scroll Prize surface models. If the original authors specify different terms, those govern.