# Endpoint-guided fiber tracing: initial feasibility experiment

Goal: reduce manual work when creating accurate same-winding constraints, following the organizer recommendation to improve tracing rather than detect sheet switches after the fact. This is an experiment, not a prize submission.

## Research scope

An independently developed experimental tool for reviewing endpoint-guided traces on public Vesuvius Challenge data. No affiliation, endorsement, award, or production readiness is claimed.

## Reproduction

Use Python 3.14, create a virtual environment, install requirements.txt, download the two files listed in data/manifest.json into data/, then run benchmark.py. Each file has a SHA256 provenance record. Dependencies come from PyPI; no GitHub access is required. No external model/API or paid compute is used.

The initial cube is 256 cubed voxels from Scroll 1. Its global ZYX origin [497,1497,3997] is read from the NML Full Cube bounding box. TIFF arrays are ZYX; NML XYZ points are reversed and translated. The scan scale is 7.91 micrometers. Nodes outside the cube are excluded.

The benchmark compares a straight line with shortest-path baselines using smoothed CT brightness/darkness and multiscale Sato ridge response. It builds non-overlapping annotation segments of at least 60 voxels along unbranched fiber chains, requires at least four labeled nodes, and excludes segments outside the cube. Inputs to tracing are only the two endpoints and CT intensities. Interior annotation nodes are used solely for scoring. Search regions are endpoint bounding boxes with a fixed 12-voxel margin. Additional corridor variants add 0.15 times squared distance to the endpoint chord to the path cost. This geometric prior uses no interior labels. All variants are exploratory development comparisons.

The development split contains tree IDs not divisible by 3. The remaining 61 cases were initially reserved; after choosing bright_corridor on development data, they were scored once with that frozen method. Reproduce that result with evaluate_heldout.py. No further tuning on these cases is permitted without relabeling them development data. This split prevents different portions of the same fiber appearing in both groups, but does not establish cross-region or cross-scroll generalization.

Metrics compare densely sampled predicted paths against interpolated human annotation polylines: symmetric mean distance, symmetric directional 95th-percentile distance, and annotation coverage within three voxels. These are annotation-agreement measures, not direct proof of correct winding or zero sheet switches. Sparse and imperfect labels limit accuracy. Bright/dark alternatives are explicit development comparisons, not a retrospectively selected held-out result.

## Data attribution and release boundary

Data: EduceLab-Scrolls; Parsons, S., Parker, C. S., Chapman, C., Hayashida, M., & Seales, W. B. (2023), EduceLab-Scrolls: Verifiable Recovery of Text from Herculaneum Papyri using X-ray CT. https://doi.org/10.48550/arXiv.2304.02084

Fiber annotations distributed by Vesuvius Challenge (NML metadata identifies Eric Thvedt). The portal lists CC-BY-NC 4.0 and additional EduceLab attribution requirements. This work uses the data for local noncommercial research; data are not offered for sale or relicensed as code. The fiber dataset is explicitly archived by the current portal. A successful first experiment still needs current-pipeline integration, broader independent validation, and an inspectable demonstration before it merits a submission.

## Next decision

Inspect initial metrics and coordinate overlays. If image guidance fails to outperform the straight-line baseline, improve the signal/cost or reject the approach; do not submit an unhelpful tool. If useful, evaluate a frozen method on held-out trees and a separate cube, add uncertainty/abstention, standard-format export, and a reviewer-ready demo. Original source is MIT licensed; data and derived scan illustrations retain their separate CC-BY-NC 4.0 terms.

## First held-out result — September 22, 2026

On 61 previously reserved segments, mean symmetric annotation distance improved from 3.449 to 2.900 voxels (15.9%). Mean annotation coverage within three voxels rose from 52.9% to 66.1%. Mean per-case symmetric 95th-percentile distance improved from 6.502 to 5.653 voxels. Results and method hash are in heldout-results.json. Three coordinate/metric/endpoint tests passed. The reviewed projection in coordinate-review.png shows the initial unconstrained bright-path failure, not the improved method.

These results compare against straight-line interpolation, not current Vesuvius tracing software. Cases share a scan cube, annotations are sparse, and no full sheet-switch claim is supported. Next: freeze parameters and evaluate a separate scan cube, inspect improved paths and worst failures in raw cross-sections, then determine whether an interactive sparse-annotation tool offers a meaningful practical benefit. Do not submit merely on this baseline comparison.

## Independent-region check and usable prototype

The same frozen method was applied to every eligible chain in two preselected additional 256-cubes. No parameters were tuned on these cubes:

| Cube | Segments | Mean error: straight → proposed | Coverage within 3 voxels | Improved cases |
|---|---:|---:|---:|---:|
| Scroll 1, ZYX 497/2497/2997 | 275 | 2.410 → 2.020 | 70.1% → 82.7% | 199/275 |
| Scroll 5, ZYX 3997/1497/3997 | 142 | 3.206 → 2.682 | 56.4% → 70.7% | 106/142 |

Tree-cluster bootstrap 95% intervals for mean error difference (proposed minus straight) are [-0.479,-0.301] and [-0.680,-0.368] voxels respectively. These intervals describe these cubes, not the population of all scrolls. Some paths worsen. Case selection used annotated arc length and in-bounds criteria; this is an annotation-assisted task, not autonomous discovery. Endpoint localization and manual inspection effort have not been measured.

Reproduce with evaluate_independent.py after downloading the files in data-independent/manifest.json. Open review.html locally for raw orthogonal CT slice sliders. The six examples are the largest improvement, median change, and largest regression in each cube, chosen mechanically. Overlay dots display only within 0.75 voxels of each slice. The largest Scroll 5 regression visibly follows a neighboring structure across a strongly curved true fiber. This must remain a reviewed proposal, never an automatically trusted same-winding annotation.

The CLI accepts an uncompressed TIFF ZYX stack or a local Zarr resolution array. It slices a bounded region (maximum 2 million voxels); it does not load a whole Zarr volume. Supply two endpoints in global XYZ voxel coordinates, the array origin, and isotropic scan voxel size. It exports a proposal JSON and WEBKNOSSOS-style NML. Native VC3D import has not been verified. It refuses to overwrite outputs. Example on the first development cube:

```sh
python trace_cli.py data/s1_00497_01497_03997_256_0000.tif --start-xyz 4144 1739 741 --end-xyz 4154 1732 508 --origin-xyz 3997 1497 497 --voxel-size-um 7.91 --output proposal.json
```

That long trace is an input example, not a validated successful annotation. Strong curvature needs extra user-selected waypoints, supported in one invocation with repeated --waypoint-xyz arguments. Never accept a proposed path without inspecting raw slices. This prototype does not estimate calibrated confidence or prevent all sheet switches.

Tests: test_benchmark.py validates coordinate transforms, metric units and endpoint preservation. test_cli.py checks equivalent TIFF/Zarr exports, global coordinate preservation, NML node count, and overwrite refusal. Source/evaluation produced entirely with an autonomous AI coding assistant; no human annotation-time experiment or organizer acceptance is claimed.

## Release verification

Run `python download_data.py --verify-only` to verify existing input files or `python download_data.py` to fetch missing files from their recorded official URLs (about 53 MB total). Downloads are hash-checked before use; existing mismatched inputs are never replaced. Then run `python -m unittest discover -p 'test_*.py'`, `python evaluate_heldout.py`, and `python evaluate_independent.py`. The generated results overwrite the included result JSON files; preserve those files if you want to compare runs. `python review_report.py` rebuilds the review with the downloaded public data.

This release includes source and evaluation records. Original full scan volumes and annotations are downloaded separately. The public review contains small cropped, attributed scan slices under CC-BY-NC 4.0. No private correspondence is included.

## Version 1.1: ordered waypoints and equal-input diagnostic

Repeat `--waypoint-xyz X Y Z` between the supplied start and end to trace one continuous proposal through ordered controls. All controls are global XYZ voxel coordinates; the output records them. Consecutive controls must be distinct rounded voxels at least one voxel apart, and each control-pair ROI must remain under two million voxels. A single JSON/NML pair is produced, without duplicate join points. Five tests pass, including multiple waypoint ordering, global coordinate preservation and no output on an invalid waypoint.

`python evaluate_annotation_budget.py` compares straight and image-guided paths with either two or three supplied controls. The third is always the middle annotation node, not chosen by looking at prediction errors. The same dense reference queries are used across all four methods, excluding three-voxel neighborhoods of all supplied controls. These are previously evaluated cubes, not new held-out data. Existing annotation nodes stand in for correctly placed human controls; human input time and accuracy are not measured.

| Region | Three controls, straight query error | Three controls, image query error | Paired delta, tree-bootstrap 95% interval |
| --- | ---: | ---: | --- |
| Scroll 1 second cube, 275 segments | 1.416 | 1.194 | -0.223 [-0.282, -0.167] |
| Scroll 5 first cube, 142 segments | 1.769 | 1.376 | -0.394 [-0.480, -0.312] |

Errors are mean reference-to-path distances in voxels outside control neighborhoods. Full symmetric metrics are also in the result JSON, because one-way distance alone can miss extraneous detours. The three-control image method improves this query metric in 312/417 cases; 105 cases do not improve. Three-control straight interpolation is substantially better on average than two-control image tracing. This supports a waypoint-assisted interface, not a claim that image guidance replaces manual controls or saves annotation time.

The official VC3D tutorial describes manual line controls with lasagna-normal interpolation/extrapolation assistance (https://scrollprize.org/tutorial_VC3D). This implementation has not been compared against that tool, and its NML export has not been verified in VC3D.