Scrolls: Vesuvius Challenge workbench

Concept illustration. Artwork notes.

Open tools, public-data benchmarks and research notes for the Vesuvius Challenge: reading the carbonized Herculaneum papyri from X-ray CT scans. The tools plan, check, score and record runs of the official open-source pipeline, ScrollPrize/villa; they do not replace it.

Important

This repository does not claim that any letters have been found in any scroll. An ink map is model output, not a reading.

Start here

• New to the challenge? Start Here goes from a browser tour to one small task with the official tools, for macOS, Linux and Windows. You can begin without a GPU or programming experience.
• Look first: Unroll shows scroll scans in 3D in your browser, and the picture guide shows the toolbox with real screenshots.
• Practice offline: Scrolls Starter has a synthetic exercise and a setup check.
• Look up a word: the glossary.

Released tools

Every released tool, one line each; each name opens its guide. Generated from docs/releases.json.

Apps, packages and datasets

Tool	What it does
AutoPipeline	Runs villa's VC3D tools and ink detection on a released scan, from surface checks to ink maps scored with controls (package, 0.1.11).
Unroll (interactive 3D scroll viewer)	Virtually unrolls scroll scans in 3D in your browser, with ink layers, CT tools and an Ink Bench for comparing ink models (Space).
Fiber stop score (two opt-in settings for villa's beam fiber tracer)	Ends a beam fiber trace before it slides onto the next fiber; with the sheet-plane penalty it was tested with. villa draft PRs #2377 and #2265.
Ringleader (winding labels for every sheet in a z-slice, in one solve)	Labels every m7 sheet pixel of a z-slice with its winding in one solve; 1.1.0 hands its surest labels to villa's spiral fit as relative windings.
Umbilici (center lines of 35 Herculaneum scans)	Every public center line (umbilicus) we know of for 35 scans, 91 lines from seven sources, in 3D over the CT, with line ends outside the scroll hidden (Space).
Parting (same layer or next layer where two papyrus layers touch)	Scores whether a point where two papyrus layers touch lies on the same layer or the next, against base dinovol's cosine; code and model file.
Vesuvius Radar (new papers, code and data for the scrolls)	New papers, code, models and data that could help read the scrolls, from public sources around the clock, scored, with an API and MCP (Space).
Crackle Check (is there ink crackle in this patch?)	Asks one ink model whether a small patch of a segment shows ink crackle, with the reversed layer order as its control (Space, API and MCP).
Snapped Labels (published surface labels moved onto the papyrus)	Every published surface label of PHerc0139, PHerc0814, PHerc0841 and PHerc0172, moved onto the papyrus recto face, as tifxyz meshes with a viewer on live CT.
AFV Fibers (papyrus fiber curves for six whole scans)	Papyrus fiber curves from Qual's AFV V2 for six whole scans, as .afv files VC3D opens, with a Space to explore any box and a fiber-set catalog.
Ink Atlas (seven ink models on the First Letters surfaces)	Seven public ink models on the same First Letters surfaces, one 9.6 um canvas: a dataset, a Space with a loupe and compare, and an MCP server.
Lasagnetta (fast preview of villa's lasagna field)	A fast preview of villa's lasagna field, about 5 times faster than villa predict3d (6.6 times with larger tiles), with a built-in self-check against villa.
Fiber Checker (are papyrus fibers visible on a traced surface?)	A free per-patch fiber map of any traced segment or your own tifxyz, with a self-check on every run, as a Space and a command line tool.
Lasagna Fields	Find 56 published fields across 35 scrolls, copy normals URLs, download data and preview the selected acquisition.
Segment Lens (published segment geometry viewer)	Shows published segment meshes with geometry warnings and the Segment Atlas table, with an API and MCP server for agents (Space).
dinovol embeddings of PHerc0841	Precomputed dinovol embeddings of the whole PHerc0841 scan, to search, cluster or segment by feature similarity without a GPU.
Headless VC3D for agents	An MCP server and shell command that let an AI agent run villa's VC3D tools with no display, checks built in (package, 1.1.1).
Ink Lens (control-checked ink on your own VC3D region)	Checks one region of your own VC3D segment for ink in seconds, keeping only ink above its own reversed-depth control (Space).
Scrolls Starter: a beginner path into the tools	A beginner path in your browser: a synthetic practice exercise with a control, a setup checker and a Scroll Text Reader command builder.
Inkfilter: fixed surface-volume filters	Makes model-free maps from a surface-volume window, each with a reversed-depth control; not a trained reader (package).
Scroll Lens (3D DINO, ink and surface models on scan cubes)	Shows what the organizers' 3D models (dinovol, 3D ink, recto surface) see inside a cube of a public scan (Space).

Scrolls kit

Command-line tools, benchmarks and script folders that run from a clone of this repository. Guide. Open an area to see its tools.

Pipeline and agents (3)

Tool	What it does
Scan catalog and batch plans	Lists released scan volumes, makes resumable batch plans and watches for new or changed inputs.
Scroll to ink in one command (experimental)	Experimental: one command from a public scan and a seed point to an ink map with its reverse-depth control, stopping at a failed check.
Swap any stage by name	Lists every option for each stage of reading a scroll, with its maker, license and maturity, so a workflow can swap any stage by name.

Viewers and apps (5)

Tool	What it does
Offline ink map comparison viewer	Builds one offline HTML page to compare ink maps, their differences, labels and the mask.
Terminal look and mouse viewer	Gives every kit command and script one styled terminal look, plain for pipes and --json, with a full-screen mouse viewer.
Tool connection instructions	Writes and checks connection instructions and code examples for the public tools' hosted pages.
Volume on a sheet in Neuroglancer	Samples a CT or prediction volume on a tifxyz surface and writes a mesh and Neuroglancer view.
Volume overlay links	Creates Neuroglancer overlay links from supplied volume metadata.

Surfaces and tracing (16)

Tool	What it does
Autocrop: good regions of a spiral fit	Keeps the regions of a villa spiral fit most likely on the right winding and writes them as relative windings, with controls.
Bounded surface correction (experimental)	Suggests bounded surface shifts using agreement between maps from two traces and keeps only shifts that pass its controls.
Label snap on a finer registered scan	Snaps a label traced on a coarse scan onto the recto face seen in a finer, per-site registered scan of the same scroll.
Label snap onto the recto face	Moves a tifxyz surface label along its normals onto the recto face of its papyrus band, with an abstain mask and VC3D review points.
Mesh and cross-scan audit	Checks cross-scan transforms, mesh canvases and rendering depth against public catalog geometry.
Planted defect generator	Plants sheet switches, holes and other defects into synthetic tifxyz surfaces with a known answer, to test checkers against.
Published segment coverage	Shows the heights and winding angles covered by published meshes and the gaps between them.
Relative winding consistency check	Passes relative winding counts only when every one is an integer and all of them can hold at once.
Relative windings in a box	Grows chains of sheet crossings around a point and writes villa's relative_windings.json for a spiral fit, with a VC3D plugin.
Scroll center (umbilicus) finder and coverage polish	Finds a scroll's winding center line (umbilicus) in its CT scan with two small U-Nets and writes umbilicus.json for VC3D.
Segment Atlas	Measures published segment meshes with the same geometry checks and builds a searchable table.
Segment stack check	Checks a stack of consecutive tifxyz segments against the umbilicus from geometry alone: winding order, spacing, gaps and overlaps.
Segments without VC3D	Reads a tifxyz segment, local or from the open-data bucket, and reports its true area, grid, holes and folds, with numpy and tifffile only.
Surface overlap and map comparison	Checks whether traced surfaces cover the same sheet and compares their labels or ink maps with controls.
Touching-sheets benchmark	Plants sheet hops at real contacts between PHerc0139's hand-traced windings and measures how often a one-sheet check misses them.
UV overlap gate	Checks a flattened sheet's UV triangles for any overlap, with exact arithmetic, plus coverage.

Ink maps and models (4)

Tool	What it does
Checkpoint averaging	Averages compatible model checkpoints from one training run and refuses a mixture of different seeds.
Ink map ensemble	Combines ink maps of the same surface by weighted score or pixel rank, keeping only pixels predicted by every input.
Mac ink inference and verification scripts	Runs public ink-model checks on a Mac with reverse-depth controls.
v8in ink model runner	Runs the released v8in ink model on layer images, including an optional reduced-precision Mac GPU mode.

Scoring and controls (12)

Tool	What it does
Acquisition recipe fidelity against a finer reference scan	Compares two CT acquisitions of one scroll region by region against a finer reference scan; one frozen PASS on PHerc0332, CT against CT.
Controlled benchmark gate	Checks recorded benchmark scores against the declared pass rules and required controls.
Controlled ink AUC scoring	Scores an ink map against labeled ink and background inside a supervision mask, alongside a reverse-depth control.
Ink map agreement check	Checks whether two ink maps of the same input agree while requiring a deliberately different control to fail.
Ink map self-check (neighbor-sheet test)	Checks without labels whether an ink map reads the traced sheet, comparing it with the same model one and two sheets away.
Ink offset diagnostic (AUC against surface offsets along the normal)	Measures how much an ink model's AUC changes when a segment's surface moves along its normal, and tests a lasagna sheet-center snap against same-size controls.
Letter-scale ink score	Compares an ink map with published labels after removing broad brightness changes, with displaced-label and reverse-depth controls.
Research integrity checks for Vesuvius claims	Checks a claim before it goes out: controls on the same pixels, held-out status, number sources, preregistration and wording.
Seam-aware winding switches	Counts how often a spiral fit puts touching vertices of one traced sheet on different windings, allowing for the fit's seam.
StrokeNet text-likeness score	Scores how much a window of an ink map looks like lines of text, with rotation and IAAFT controls, using only NumPy.
Synthetic map controls	Creates known-answer synthetic inputs for checking ink-map scoring and controls.
Text-row pattern score	Measures repeating bands in forward and reverse ink maps as a triage aid, without interpreting text.

Letters and titles (4)

Tool	What it does
Greek character language model	Builds and scores a character language model from public Greek text for the letter reader.
Greek gap restoration benchmark	Hides letters in public Greek text and scores hosted text models against a Kneser-Ney letter model under a frozen rule.
Greek letter classifier and line reader for agents	Names Greek capital letters in given boxes on papyrus photographs and reads lines of boxes, as a JSON command and an MCP server.
Scroll Text Reader	Proposes Greek capital letters with boxes and confidences on ink maps, drawn labels and photographs, on a CPU, with null and orientation controls.

Data and downloads (8)

Tool	What it does
AFV fiber streaming	Streams the AFV fibers in one box of a scan without the whole download: the same fibers and .afv bytes as filtering the full file.
False-404 test relay	Replays selected false missing-file responses through a local relay so cache handling can be tested.
Fast public label downloads	Downloads a folder of the organizers' public Hugging Face datasets bucket fast, fetching each distinct file once.
Find, center line, cite and villa helpers	Lists everything public for one scroll, fetches its best center line, prints credit lines, and checks villa PR timing and text.
Layer extraction and shuffle control	Exports surface-volume layers as images and creates a shuffled-depth control.
Public bucket downloader	Copies files under a public data bucket prefix to a local folder and skips complete files when resuming.
Published ink labels and model exposure	Lists published ink label sets and the recorded training exposure of public ink models.
VC3D false-404 relay and cache repair	Runs VC3D through a relay that retries false missing-file responses and checks its empty-chunk cache.

Training (3)

Tool	What it does
Label suggestions from reader disagreement	Ranks tiles by where readers' ink maps disagree, so a person labels there first; beat random tiles on two scrolls, not shown to beat simple picks.
Segmentation model comparison tools (experimental)	Lists segmentation model families and provides training and controlled scoring scripts.
Training-run comparison for label suggestions	Tests whether fine-tuning on suggested tiles beats random tiles; on three fragments it did not.

Planning and prizes (4)

Tool	What it does
Local setup checker	Checks the machine and installed tools before a pipeline run.
Pipeline planning and cost estimates	Prints the official pipeline commands for a scroll without running them.
Public prize snapshot	Lists public prize requirements from a dated local snapshot.
Submission folder check	Checks a submission folder against published file requirements and lists the remaining checks for a person.

Compute and cost (4)

Tool	What it does
Hugging Face Jobs ledger importer	Adds finished Hugging Face Jobs to a cost ledger with the cost from Hugging Face's own bill, once per Job, and restricts public ledgers to generic work.
Local run time and cost log	Runs a local command and records its elapsed time and estimated electricity cost, or adds records of past runs.
Modal ledger row importer	Adds a recorded job to a cost ledger once and restricts public ledgers to rows marked generic.
Run time and energy summary	Summarizes machine time from run provenance records, with an optional energy estimate.

Records and provenance (2)

Tool	What it does
Experiment ledger	Keeps a run record with a fixed readout rule, status, costs, file fingerprints and checks.
Run provenance records	Records run settings and file fingerprints, then checks the record and its files for changes.

Releases and repository (4)

Tool	What it does
Recurring repository checks	Lists and runs the registered recurring repository checks and records their status locally.
Release list and README generator	Keeps the public release list, compact tool inventory and generated README section in step.
Stale repository reference check	Checks live documentation and registries for outdated references and pending work.
Villa port check for your scripts	Says which references to villa's Python packages in your scripts break at a villa commit, and what replaces each.

Quick start

Python 3.10 or newer. Most kit commands need only the standard library; the map tools add numpy and tifffile, and the heavy pipeline (VC3D, PyTorch, ink models) comes from villa. python -m kit doctor says what is missing.

git clone --depth 1 https://github.com/ChaseHendrick/Scrolls.git
cd Scrolls
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[all]"
# open prizes, deadlines and eligible scrolls, from a dated snapshot
python -m kit prizes
# what this machine has and lacks for a run
python -m kit doctor
# the official commands for one eligible scroll, printed and never run
python -m kit plan PHerc0826
# score an ink map against its labels, with the reverse-depth map as control
python -m kit auc MAP.tif --control MAP_reverse.tif --labels L/inklabels.zarr --mask L/supervision.zarr
# Scroll Text Reader on synthetic letters
scrolls-letterdemo
python -m unittest discover -s tests

Every command is in docs/tools/cli.md, and every tool has a page in docs/tools/. Install AutoPipeline in its own environment, since both install kit.

Open prizes (snapshot 2026-11-03)

Prize	Money	Deadline	What wins
2027 Grand Prize	$800k / $100k / $50k / $50k	25 Jun 2027	Fully unroll one of 13 sealed scrolls; at least 70% of each counted column's preserved characters legible
First Letters	$50k per scroll, 8 more ($400k remaining; two already used, PHerc. 343 and PHerc. 306B)	25 Jun 2027	First team to show 10 legible letters in a single 4 cm² area of one of 20 eligible scrolls
PHerc. Paris 4 title	$50k	25 Jun 2027	A papyrologist-readable image of Scroll 1's title
Progress Prizes	$20k best of month, plus $250 to $20k awards	monthly, several entries a month allowed (on 3 Nov 2026 the page still named 31 Oct 2026 as the next deadline)	Open-source tools, models, datasets, fixes, reports that help read the scrolls

Important

All prizes require open-sourcing your method (permissive license) to accept the money. Details, submission contents and the eligible-scroll lists: docs/prizes.md.

Novel findings

Note

Reviewed 4 November 2026. One line per finding, newest group first. Each keeps its number, so "finding N" elsewhere still points at the right one. The full text of each, with its controls, limits, corrections and links, is in docs/FINDINGS.md; every number with its settings and source is in docs/results.json. Public labeled data only; an ink map is model output, not a reading.

Tool results (details)

15. Center Finder: 0.73 mm median from the 13 published lines with each scroll held out, and level with villa's vc_gen_umbilicus on two sealed lines (0.56 against 0.81 mm; closer on PHerc0139 only) (13 and 22 October 2026, model output).
16. StrokeNet tells text from the same text turned 90 degrees far better than any simple score (AUC 0.994 against 0.865, six held-out PHerc. Paris 4 tracings, 14 October 2026, model output); it passed 7 of the 9 bars of that first test, plain ink density matched it at text against blank papyrus, and part of its sense of orientation may come from the direction of the papyrus rather than the writing.
17. Inkfilter's face mix scored mean AUC 0.736 against 0.704 for alpha compositing on 56 confirmation windows, from the segments it was developed on; not a trained-reader comparison (17 October 2026).
18. StrokeNet's two-density score, with no network, came out ahead of ink density inside segments on PHerc0500P2 with ink_9um (mean within-segment AUC 0.701 against 0.662, ahead in all 11 segments, both controls passed; 22 October 2026, model output; ink_9um reads this scroll weakly).
19. Three hosted text models restored hidden Greek letters in Philodemus, De Musica, less often than a Kneser-Ney letter model (gap letter accuracy 0.181, 0.181 and 0.118 against 0.331, single letters 0.447 at best against 0.895, no recall detected (probe about 0.08); public text, 22 October 2026, model output).
20. Our letter classifier, trained on Hell-Char only, named Greek letters on fresh papyrus photographs better than Hell-Char ConvNeXt-V2 (error 0.291 against 0.340 on the 8,479 ICDAR 2023 test boxes, boxes given, every control passed; as lines with a no-Homer Greek letter model it was level with Hell-Char given the same model; 24 October 2026, model output; photographs, not ink maps).
21. windlabel-box's automatic relative windings passed a held-out test on a third scroll and were slightly more often right than two community winding tools (0.955 of 32,411 judged steps on fresh PHerc0172 boxes, against 0.944 for constraint-gauge's E1 on the same steps and 0.934 for winding-phase at matched coverage, leads with lower bounds +0.009 and +0.005; rules fixed before any box had a prediction; 29 October 2026, model output against the published hand windings).
22. labelsnap moved published surface labels closer to the papyrus recto face than the published labels and seven community snaps (mean +2.153 voxels closer than the published label, +1.892 closer than VC3D's vc_objrefine tuned on PHerc0139, 71 fresh PHerc0814 and PHerc0841 sites scored against a finer scan; within 1 voxel 55 to 66 % against 19 %; finesnap, on a finer registered scan, 85 % on PHerc0814 and 91 % on PHerc0139; 25 to 29 October 2026, model output; geometry, not a reading). Scored against a finer scan's face found with labelsnap's own band rule; with a face rule sharing neither, the lead held at about half the size (+1.04, +1.23 voxels).
23. Parting, a contact classifier on base dinovol features, told same-layer from next-layer points at touching layers better than dinovol alone on a fragment it never saw (AUC 0.895 against 0.839, gain +0.056 with bound +0.037, 150 sites over 5 layer pairs of PHercParis1Fr34; one pass in three fragments: misses on a PHerc1667 fragment, +0.045 against a bar of +0.05, and on a PHerc. Paris 2 fragment, +0.010, where dinovol alone scored 0.965; little gain where layers are fused; rule frozen before any of the test's 3D CT was read; 29 October 2026, model output; code released under Apache-2.0, model file on Hugging Face as SharpMeow/parting-v1: tool page).
24. Ringleader labeled every m7 sheet pixel of held-out PHerc0139 slices with its winding far more often right than villa's spiral fit at its defaults, and passed a second scroll (on-winding E0 0.902 against 0.149 to 0.179 on 41 slices at z 3,240 to 3,400, bar 0.85; on PHerc0332 0.659 against 0.349 to 0.398 for the fit and 0.445 for a constant labeling, bar 0.595, against one organizer mesh; two later tries on other scrolls read VOID, so claimed on two scrolls; PHerc0139 held out by band only, PHerc0332 not fully held out (m7 may have trained on it), and the margin is over villa's default fit, which is not built to label every sheet; rules frozen before the read, each read once; 30 October 2026, model output; code released under Apache-2.0: tool page).
25. sqrecipe: on PHerc0332, a finer DLS scan brought down to the 7.910 um grid kept more sheet structure than the scan taken at 7.910 um (sheet fidelity higher in 0.925 of 120 fresh regions, median +0.042, against an independent ESRF 2.399 um scan, every control held; rule frozen before the read; 30 October 2026, Measurement of the CT; one acquisition pair on one scroll, not ink and not readability: tool page).
26. villa's flow-gradient smoothing cut its spiral fit's seam switches on held-out PHerc0172 but not on PHerc0332, and the PHerc0172 gain came with a misplaced center line (-7.5 to -15.4 switches per 1000 sheet neighbor pairs at three of three seeds, bar -7.5, exact share kept; on PHerc0332 it added 0.3 to 14.0 per 1000 and failed; the PHerc0172 fits used our released umbilicus-lines-v1 line, later found 3.9 to 12.6 mm off the hand windings' center in that band; rules frozen before each read; 30 October 2026, model output; not a general switch cut).

29. Ringleader's ladders made villa's spiral fit put more sheet pixels on the right winding on two scrolls (on PHerc0172 z 9,680 to 9,904, on-winding E0 0.288 with the ladders against 0.069 alone and 0.037 for a plus-one control, bar +0.10, got +0.219; on PHerc0139 0.409 against 0.227; a test on a third scroll in between missed its bar, and the PHerc0172 band was picked after that miss; the taught fit stays below Ringleader's own labels; rules frozen before each read, each read once; 4 and 6 November 2026, model output; code released under Apache-2.0: tool page).

Pipeline and reader checks (details)

12. A transient S3 404 becomes a permanent hole of zeros in VC3D's renders and traces (villa #2058; our fix, villa #2060, was closed unmerged on 30 October because VC3D's rendering is moving to vc_reader; 8 to 12 October 2026).
13. villa's tracer did not hold an explicit seed, so a trace could start on the next winding (villa #2059; one seed on PHerc0139, 11 and 12 October 2026); fixed by our seed_anchor_xyz option, merged in villa #2063 on 30 October.
14. A traced surface's render comes out turned, and ink_9um reads it much worse until it is turned upright (one trace, development data, 13 October 2026); Reader v2 did not replicate it cleanly, so ink.orient stays opt in.

28. villa's released sheet tracer does not record which bands of PHerc0139 and PHerc1667 it held out, and fine-tuning it on a small patch set stopped before the first step (villa #2444, fix in villa #2445, open; 4 November 2026); PHerc0841 is not in its training config, so it is the clean scroll to score it on.

Earlier measurements and corrections (details)

1. On w045, v8in scores below ink_9um, but ink_9um trained on that surface, so the test cannot say which reads an unseen surface better (corrected 8 and 9 October 2026).
2. Scoring a crop needs an edge margin: a 64 px edge makes bare-crop and whole-map scores agree.
3. A threshold taken from a training segment misses about 96 % of real ink on an unseen scroll.
4. Averaging depth windows matches the best window chosen with labels on PHerc0841 (related prior work is cited).
5. Two of PHerc0841's three labeled segments, w00 and ag896, are the same papyrus.
6. Raw CT brightness alone carries almost no ink signal on PHerc0841.
7. Ink-map agreement between two traces falls with their distance (model output; the maps are probably in-sample).
8. PHerc0841 has 3.4 cm² of supervision, so its AUCs need intervals.
9. Cross-trace agreement suggests a label-free triage experiment (untested idea).
10. Every published surface volume matches a published mesh, but the stored PHerc1667 matrix contradicts its own landmarks (reported earlier by kadenpool in villa #1843; our CT check agrees with the landmarks).
11. PHerc1667's 1.129 um renders appear misplaced (post hoc; the preregistered version failed its control, so it needs a calibrated rerun).

Follow-up tests, partial results, the adaptive-geometry experiment and the CPU speed checks are listed after finding 11 in docs/FINDINGS.md.

Documentation

• docs/README.md: the docs index, one home per topic.
• docs/MAP.md: the repository map, one row per module and script.
• docs/engine.md: what villa does, what kit/ adds, and what this repository does not do.
• docs/prizes.md, docs/state-of-play.md, docs/pipeline.md: the prizes, what has been tried, and how a scan becomes text.
• AGENTS.md and docs/AI-AGENTS.md: rules for AI agents and for people; docs/QUALITY.md, docs/NOVELTY.md and docs/TESTING.md: the bar for claims and tests.
• CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md and SUPPORT.md.

Private plans, candidate outputs and submission material live in Scrolls-private (access required).

License

Code and documentation: Apache-2.0, copyright 2026 Chase Hendrick and Scrolls contributors; see NOTICE. Cite with CITATION.cff.

Third-party software, data, labels, renders and model weights keep their own licenses, which the code license does not cover. Scroll Text Reader's Greek weights are CC BY 4.0 (letters-v2-ccby) and CC BY-NC 4.0 (letters-v2-real, trained with ICDAR 2023 Greek letters); the Center Finder's weights (umbilicus-v1) are CC BY-NC 4.0, because the CT they learned from is. Local OCR language packs keep their source licenses. Check each source's terms, including the Vesuvius data browser, before use or redistribution.

Warning

Do not commit scroll data, renders or ink maps to this public repository.