Skip to main content

๐Ÿ“œ Awesome Scroll Tools Awesome

Here are all the awesome awarded open source contributions from our community that will allow us to read the scrolls! ๐Ÿ“šโœจ

Contributions are divided into four categories: Data access/visualization, Segmentation, Ink Detection, and Other.

Every category is subdivided in classes: ๐ŸŒŸ Highlighted (for popular contributions), โš™๏ธ Tools, ๐Ÿ“ฆ Materials, ๐Ÿ“ Reports, and ๐Ÿ“Š Visualization.

Some highlighted contributions are added to this repository as submodules.

We keep this repository updated as much as we can, but research moves fast! ๐Ÿƒ๐Ÿ’จ

For state-of-the-art updates join our Discord server ๐Ÿ’ฌโฐ

๐Ÿ“Š Data access/visualizationโ€‹

๐ŸŒŸ Highlightedโ€‹

  • vesuvius: Python library for accessing Vesuvius Challenge data. Allows direct access to scroll data without managing download scripts or storing terabytes of CT scans locally.

  • VC3D: the teamโ€™s interactive tool for viewing, segmenting, and virtually unwrapping scroll volumes.

  • Segment browser is a web-based tool to browse layers and open source ink detection results of all released segments. By Johannes Rudolph

๐Ÿ› ๏ธ Toolsโ€‹

  • vesuvius-c: C library for accessing Vesuvius Challenge data (deprecated โ€” prefer the vesuvius Python library or VC3D).

  • vesuvius-gui is a single binary GUI to render volumes and segments on-the-fly. By Johannes Rudolph

  • vesuvius-phalanx: Python library / CLI for accessing Vesuvius data. Allows flexible access to volume and fragment scroll data. By Marcel Roth

  • llfio-chunkloader: A method to access data in chunks of (x,y,z) that is much faster and more compute-efficient than Zarr. (Written in C++ but it is possible to integrate in Python).

  • preprocessed-data: Data preprocessing code and a fully processed version of the dataset in .zarr format to allow for faster training of ink detection models.

  • scroll-data-audit by Matteo Bulloni. Integrity auditor for the open-data: reconciles the catalog (metadata.json) against the actual Zarr arrays, filenames and scan metadata, and verifies multiscale pyramid value-correctness. Reported a Scroll 5 (PHerc0172) catalog shape error (#1211) and certified the rest of the open-data consistent.

  • Region-of-interest inference for vesuvius.predict: --bbox "z0:z1,y0:y1,x0:x1" restricts inference to one region of a volume, in global voxel coordinates, so blend_logits and finalize_outputs stay aligned. Only the chunks intersecting the region are streamed โ€” on PHerc. Paris 4 a 200ยณ region reads 27 chunks (56.6 MB) instead of 10,368 (21.7 GB). By TAUIL Abd Elillah

Segmentationโ€‹

๐ŸŒŸ Highlightedโ€‹

  • Khartes by Chuck is a tool to manually create and visualize segment meshes, while also visualizing a preview of the rendered segment.

๐Ÿ› ๏ธ Toolsโ€‹

  • Volume Cartographer: the OG virtual unwrapping toolkit. Includes a graphical interface to annotate scroll segments. First built by EduceLab; an active fork by Philip Allgaier contains many community contributions and is currently used by the segmentation team.

  • Thaumato Anakalyptor is an automatic tool that combines classical methods such as threshold gradient operator based edge detectors and Deep Learning based instance segmentation of point clouds to detect, merge and render segments. It was built by Julian Schilliger (part of Grand Prize winning submission).

  • Fast Segment Rendering by Julian Schilliger. Fast rendering of segments with GPU acceleration. Capable of saving the surface volume to multiple file formats.

  • Volumetric Vesuvius Labelling by James Darby. Provide custom tooling the napari 3d viewer that will help manually annotate volumetric masks of the scrolls to train ML models for 3D segmentation.

  • Autosegmentation preprocessing pipeline (work in progress) collection of scripts to pre-process volumes for autosegmentation. By Giorgio Angelotti

  • Segment2Voxel by Giorgio Angelotti. Tool to create 1-voxel thick volumetric segment labels starting from mesh .obj files.

  • Volumetric Instance Labels to obj by James Darby. Tools to create .obj mesh files from volumetric instance labels.

  • Hraun is a collection of python tools for handling volumetric scroll data by Forrest McDonald.

  • Scroll compression and masking by Olivier Daubney. Script to compress and mask scroll data, greatly reducing storage requirements!

  • Mesh merging by Julian Schilliger. Merges multiple overlapping meshes into one continuous mesh. Flattening not included.

    • Mesh merging prototype by Giorgio Angelotti. Different attempt to merge existing mesh of segments by projecting them in 2D and retriangulating in the plane.

  • Meshing and chunking by Santiago Pelufo

  • Volumetric segmentation model with labels, deep learning 3D model to separate papyrus from air, by Tim Skinner

  • Superpixels and cells by Santiago Pelufo

  • Segment Flattening by Julian Schilliger and Giorgio Angelotti. Improved flattening of scroll segments.

    • Slim-Flatboi previous implementation of the SLIM algorithm with minimization of isometric distortion to flatten scroll segments. Later included in ThaumatoAnakalyptor. By Giorgio Angelotti.

  • Single Sheet Segmentation attempt by Brett Olsen

  • vesuvius-blender by Santiago Pelufo. Explore the X-ray scans in Blender.

  • vesuvius-build by Santiago Pelufo. Scripts to build files for progressive loading of the data. Convert the tif stack to grid cells or to h5 format that can be used by Ilastik.

  • Volume Annotate A partial reimplementation of Volume Cartographer in Python by Moshe Levy.

  • vesuvius-image by Brett Olsen. Tool for storing and viewing data, including efficient Zarr loading of stack of tif images later included in Khartes.

  • Quick Segment Created by EduceLab for annotating a large air gap in Scroll 1, and then projecting from that gap to either side to create two large segments, colloquially referred to as the โ€œMonster Segmentโ€. Hasnโ€™t been used for more segmentation, since it was the only large air gap we could find.

  • scrollreading by Will Stevens. Experiments with using algorithms based on flood-fill to extract non-intersecting surfaces from scrolls.

  • VC with OME-Zarr & more by Hendrik Schilling:

    • fast interactive OME-Zarr access and live slicing & flattening thread
    • instant flattening from VC segments without meshing (10s for one slice) thread
    • segment surface refinement (also works on obj segments) thread
    • fiber based segmentation efforts using an optimizing physics inspired surface meshing approach based on ceres-solver thread
    • non-destructive large scale interactive segment viewing and editing thread
    • automatic patch generation pipeline: vc_grow_seg_from_seed, vc_render_tifxyz, vc_tifxyz2obj: thread
    • segment tagging, segment masking, POIs, segment filters (all/filter by focus point/filter by POIs), display intersections scaling to thousands of segments message
    • low memory tiled rendering to enable GP-sized an full scroll rendering https://github.com/hendrikschilling/volume-cartographer/blob/dev-zarr/apps/src/vc_render_tifxyz.cpp
    • large segment tracing based on patch consensus: vc_grow_seg_from_segments, as documented in the FASP submission
    • consistent winding number estimation by winding number diffusion: vc_tifxyz_winding
    • segment fusion & inpainting: vc_fill_quadmesh

  • fast and low memory inference for the GP ink detection 1/5 the memory consumption and 20x the speed compared to the baseline GP ink detection for large segments to allow GP and full scroll size ink detection and fast preview.

  • vesuvius-render by Johannes Rudolph:

    • Fast self-contained CPU-based rendering of segments from obj files downloading data on-the-fly.

  • segmata by Stephane Gouttebroze:

    • Improve the segmentation process by sharpening the layers rendering, this is based on optimizing the layer 32, a further objective is to link this optimization on a inference loop (optimizing on the detected ink instead of only layers)

  • Synthetic instance labels and volume generation by lcparker

    • Generate artificial 3D volumes with corresponding instance labels for use in pretraining instance segmentation networks

  • Mask3D for instance segmentation on scroll volumes by lcparker

  • Affinity Prediction with Unet by Ayush Mishra

    • Unet trained on affinity labels using pytorch_connectomics and experiments with watershed

  • Gabor Filter for surface prediction by Ayush Mishra

  • ScrollFiesta -- virtual meshing & unwrapping for the Herculaneum papyri by HariSeldon and friends

  • Scroll-specific augmentations by pscamillo. GPU-native training augmentations modeling real scroll/CT distortions: Squeeze (#997), Decohesion + Warp (#999), Ring (#1020), Streak (#1021), Warp edge-padding fix (#1025) (#201), each validated with ablation + benchmark.

  • winding-ruler by pscamillo. Measures winding evidence for the spiral fit: where human annotations matter, why generation fails at the published resolution, and a collection-wide winding-pitch atlas (36 scrolls). Includes qa_holescan, a content-level detector for silent z-slice loss in predict3d output (#1183).

  • HIP/ROCm port of ScrollFiesta's MLS for AMD GPUs by Alan Thompson (altommo) โ€” clean-room HIP port of the MLS-midpoint kernel, validated on RX 9070 / gfx1201: ~16.8x kernel, ~5.8x multi-cube, topology-equivalent weld-safe mesh. (upstream PR)

  • CubeCL port of ScrollFiesta's MLS (portable GPU: AMD/NVIDIA/WGPU) by Alan Thompson (altommo) โ€” Rust/CubeCL reimplementation of the same MLS kernel from a single source; validated on RX 9070 / gfx1201 against the HIP port, passing the 0.25-voxel weld-safety gate and 5-pass strict parity vs clean HIP.

  • vesuvius-automesh by spencerdavis-tx. Fully automated, QC-gated surface harvest: masks the public surface predictions against the CT, seed-sweeps the villa tracer, and accepts output per 25 mm window under a two-part quality gate plus an independent topology check - 279 cm2 of verified Scroll 3 surface with zero manual annotation, CPU only. Ships per-window QC records for all 157 windows (passes and failures) as a labeled set of tracer failure modes.

  • Herculaneum Scroll Tools by axiosdevs โ€” CT-consistency QA for the published m7 surface predictions: voxel-exact phantom fractions measured for all 36 samples incl. all 13 grand-prize scrolls (43.3% of positives sit outside the masked CT), with a one-pass clean mode (villa#1114); plus cross-scan registration (2023โ†’2025 rescan, MAD 29 ยตm), a winding-constraint annotator/verifier in native spiral-input format, and dual-energy high-Z ink-candidate rendering.

๐Ÿ“ฆ Materialsโ€‹

๐ŸŒŸ Highlightedโ€‹

Scroll Surface Predictionsโ€‹

๐Ÿ“œ Segmentsโ€‹

-Large Autosegmentation of Scroll5 by Hendrik Schilling and Sean Johnson -- Unsupervised, many switches -- check readme.md

๐Ÿท๏ธ Volumetric Labelsโ€‹

๐Ÿ“ Reportsโ€‹

๐Ÿ“Š Visualizationโ€‹

Ink Detectionโ€‹

๐Ÿ† 3D Ink Detectionโ€‹

๐ŸŒŸ Highlightedโ€‹

โš™๏ธ Toolsโ€‹

  • Large Scroll Model is a 3D Unet pretrained on scroll data, by Ryan Chesler

  • UV predictions visualizer by Giorgio Angelotti. Script to quickly visualize the ink predictions output by Ryan Chesler's 3D model as a scatter pkot on segments. Needs the predictions Zarr for the full scroll.

  • Volumetric ink detection attempt by Jorge Villaescusa

  • Inkalyzer by Youssef Nader. XAI package for Ink models to explain predictions and generate volumetric labels.

๐Ÿ“ฆ Materialsโ€‹

๐Ÿ–‹๏ธ Scroll segments-based Ink Detectionโ€‹

๐ŸŒŸ Highlightedโ€‹

โš™๏ธ Toolsโ€‹

  • ScrollMAE by Jorge Garcรญa. Contains the necessary code to pretrain a 3D ResNet on unlabeled data and then finetune it to perform ink detection.

  • Unsupervised Ink Detection with DINO by Jorge Garcรญa. Contains experiments related to detecting ink without labels, including a Colab notebook.

  • Vesuvius AutoResearch by mojomast. Autonomous, evidence-gated experiment search for Vesuvius ink-detection research, with reproducible configs, metric contracts, synthetic demo data, and promotion checks.

  • Vesuvius GP+ by Jared Landau. Updated version of the Grand Prize Ink Detection script with extra features.

  • Segment-to-segment label mapping by Oliver Daubney

  • Runner Up Models, December, 2023

    • Ink detection model by SQ Mah

    • Ink detection model by Lou Schlessinger and Arefeh Sherafati

    • Ink detection model by lian Rafael Dal Prรก, Sean Johnson, Leonardo Scabini, Raรญ Fernando Dal Prรก, Joรฃo Vitor Brentigani Torezan, Daniel Baldin Franceschini, Bruno Pereira Kellm, Marcelo Soccol Gris, Odemir Martinez Bruno

  • Vesuvius Kintsugi is a tool to label floodfill surface volumes of rendered segments, by Giorgio Angelotti

  • Omit is a pipeline that tries to detect ink with classical approaches (not deep learning) by Timo Meireman

  • First Letters winning models, October 2023

  • Crackle Viewer is a tool to browse and annotate surface volumes of rendered segments, by Julian Schilliger

  • Fourth placed Kaggle model finetuning on scroll data by Luke Farritor

  • Scroll pretraining by Youssef Nader. Youssefโ€™s original idea for pretraining on the scrolls and finetuning on the fragments, which led him to winning the First Letters Prize.

  • pre-trained DINOv2 models by Sergei Pnev. Self-supervised model pre-trained on scrolls 1-5 with predictions.

๐Ÿ“ฆ Materialsโ€‹

๐Ÿ“ Reportsโ€‹

๐Ÿ“Š Visualizationโ€‹

  • Segment viewer. Used by the segmentation team primarily to see which segments they have worked on already. Hosted here By Yao Hsiao and Dalufishe

๐Ÿ“œ Fragment-based Ink Detectionโ€‹

๐ŸŒŸ Highlightedโ€‹

๐Ÿ“ Reportsโ€‹

Otherโ€‹

โš™๏ธ Toolsโ€‹

๐Ÿ“ฆ Materialsโ€‹

  • CT scanning campfire scrolls Ahron Wayne replicated the carbonization process of a papyrus scroll and scanned it with his personal CT scanner

๐Ÿ“ Reportsโ€‹

Contributions

If you want to contribute and add any resource please submit a PR! ๐Ÿ˜Š๐Ÿš€