vesuvius-ladder

vesuvius-ladder is a geometry QA check for Vesuvius Challenge tifxyz surfaces. It exists to tell ordinary overlap between neighbouring segments apart from a more specific failure: one papyrus wrap traced and published twice as if it were two different segments. The detector itself reads geometry only, no volume, learned model, GPU or credentials; a separate script, raytest.py, adds a named surface-prediction volume as supporting evidence for one specific finding.

What it does not do

• It is a QA heuristic, not a general proof of physical sheet identity. A different corpus can violate its assumptions, for example if the closest published companion surface is not a neighbouring wrap, or coordinates are expressed in incompatible frames.
• It does not claim eligibility for, or predict, a particular prize tier; whether the check gets folded into the production validation workflow is a separate decision.
• Its ray-based evidence is model-based, not direct observation, and is not physical ground truth; the released 40 to 55 voxel subset was not preregistered.
• Its online catalogue scans depend on a mutable public bucket, so re-running the whole-corpus scan later is a new observation, not a guaranteed reproduction of the pinned 2026-08-19 snapshot.

Install

Python 3.10 or later.

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[test]"

requirements.txt records the exact Python 3.14 environment used for the 2026-08-20 release verification. If imagecodecs crashes decoding the LZW float32 TIFFs, force the Pillow reader:

export LADDER_TIFF_READER=pil

Use

.venv/bin/python check_duplicate.py ./check_data
.venv/bin/python ladder.py scan --sample PHerc0139
.venv/bin/python ladder.py scan --dir /path/to/tifxyz/directories
.venv/bin/python ladder.py scan --sample PHerc0139 \
  --json pairs.json --collection duplicate_sites.json

check_duplicate.py downloads 8.03 MB of manifest-pinned meshes and ink maps, verifies every size and SHA-256 digest, and recomputes the headline result; after a successful online run it repeats offline with --offline. Download failures are fatal, so an incomplete corpus cannot produce a clean report silently.

.venv/bin/python -m pytest -q

CI runs the synthetic test suite on Ubuntu and macOS with Python 3.11 and 3.13, and does not download the research dataset.

How it works

For every ordered pair of surfaces, each queried vertex of one is matched to its nearest vertex on the other; only the query side is subsampled, since subsampling the tree side would inflate the measured distances. The scroll-specific unit is the median, across surfaces, of each surface’s smallest median distance to a companion. A pair is classified as duplicate when more than half of either surface lies within 0.1 times that unit of the other, with an absolute floor of one voxel.

In the catalogue snapshot dated 2026-08-19, the scan covered 188 tifxyz surfaces out of 311 published segments across 12 scrolls, forming 5,142 ordered pairs, and classified one pair as duplicate: PHerc0139/20260325000000-w046_20260325 and 20260126000000-w045_2026012619. Of the 109,823 valid vertices compared, 89,503 (81.4975%) are bit-identical across all three float32 coordinate channels; the geometric coincident fraction is 0.818 against a largest non-duplicate score of 0.127 in that corpus; and the aligned published ink maps correlate at r = 0.810, against +0.008 and -0.051 for the two adjacent controls. The ray experiment finds a distinct interior high-response island in 85 of 86 (98.84%) rays of length 40 to 55 voxels between the two surfaces, against 2 of 28 (7.14%) for a one-sheet control and 94/95 and 102/102 for two two-sheet controls.

OpenAI Codex was used agentically to investigate, implement, test, audit and document the repository; the pinned manifests let the reported checks be audited independently rather than taken on trust.

vesuvius-ladder on GitHub, MIT licensed.