vesuvius-nnunet-model

Vesuvius Challenge — nnU-Net Surface Detection Model

A 3D segmentation model for detecting papyrus sheet surfaces in micro-CT scans of the Herculaneum scrolls, trained for the Vesuvius Challenge Surface Detection competition on Kaggle.

Model Description

This model uses nnU-Net v2, the self-configuring deep learning framework for biomedical image segmentation. nnU-Net automatically determines the optimal network architecture, preprocessing, and training strategy from the dataset properties.

The model segments 3D micro-CT volumes into three classes:

• Background (0) — empty space / non-papyrus
• Surface (1) — the outer surface of the papyrus sheet
• Interior (2) — the interior of the papyrus sheet

Architecture

Training Details

Training Metrics

Kaggle Leaderboard

Note: The Kaggle submission used our V2 pipeline model (custom UNet3D), not this nnU-Net model directly. This nnU-Net model is intended for future ensemble submissions and as a standalone alternative.

Dataset

The Vesuvius Challenge Surface Detection dataset consists of 3D micro-CT scans of carbonized papyrus scrolls from Herculaneum, buried by the eruption of Mount Vesuvius in 79 AD.

• 704 training + 82 validation volumes (786 total)
• Volume shape: 320 × 314 × 314 voxels
• Voxel spacing: 7.91 μm isotropic
• File format: 3D TIFF
• Intensity range: 0–255 (CT values)
• Validation split: Scroll ID 26002

Intensity Statistics (foreground)

How to Use

Prerequisites

pip install nnunetv2 torch

Inference with nnU-Net

from huggingface_hub import snapshot_download

# Download model
model_dir = snapshot_download("bshepp/vesuvius-nnunet-model")

# Set nnU-Net environment variables
import os
os.environ["nnUNet_results"] = model_dir

# Run prediction using nnU-Net CLI
# nnUNetv2_predict -i INPUT_FOLDER -o OUTPUT_FOLDER -d 011 -c 3d_fullres -tr nnUNetTrainer_200epochs -f all

Loading checkpoint directly

import torch

checkpoint = torch.load("checkpoint_best.pth", map_location="cpu")
# checkpoint contains: network_weights, optimizer_state, epoch, etc.

Files

Post-Processing

For best results, apply the 1st-place post-processing pipeline after inference:

1. Binary closing with spherical footprint (radius 2)
2. Height-map patching with bilinear interpolation
3. LUT-based 1-voxel hole plugging (6-connectivity)
4. Global binary_fill_holes

See 1st place writeup for details.

Citation

If you use this model, please cite nnU-Net:

@article{isensee2021nnu,
  title={nnU-Net: a self-configuring method for deep learning-based biomedical image segmentation},
  author={Isensee, Fabian and Jaeger, Paul F and Kohl, Simon AA and Petersen, Jens and Maier-Hein, Klaus H},
  journal={Nature methods},
  volume={18},
  number={2},
  pages={203--211},
  year={2021},
  publisher={Nature Publishing Group}
}

License

MIT

Author

Brian Sheppard (@bshepp)