Tutorial: Spiral Fitting
Last updated: September 16, 2026
Most of our segmentation tools work bottom-up. GrowPatch, lasagna, and manual segmentation in VC3D all produce patches β pieces of papyrus surface that you grow bigger and bigger until they hit a tricky region and stall. Other tools trace individual fibers. Either way you end up with a big pile of small pieces: segments, fibers, point annotations. What we really want is the whole scroll β one surface covering every winding of the original papyrus sheet, from the center to the outer shell. However, gluing the pieces together directly is hard, especially where there are gaps between them. 1
That is what the spiral fit does. It takes the whole pile of partial evidence β surface patches, traced lines, winding annotations, volumetric predictions β and fits a single, globally coherent surface for the entire scroll that agrees with as much of that evidence as possible. Where the evidence is dense, the fitted surface follows it closely; where there are gaps, the spiral bridges them smoothly instead of stopping or leaving a gap.

The core idea: we know the scroll was originally one long rectangular sheet, rolled up into a neat spiral. The eruption of Vesuvius deformed that spiral into the crushed shape we see in the CT scan. Instead of reconstructing the surface piece by piece, we search for the combination of ideal scroll shape and smooth deformation that best explains everything we observe. Once we have those, virtual unrolling comes almost for free: any point in the scan can be mapped back onto the original flat sheet.
The last section of this tutorial goes into how it works internally; first, the practical part β what goes in, what comes out, and how to run it.
What goes inβ
The spiral is flexible about its inputs: it consumes many kinds of evidence, in almost any combination, and each kind can be created manually or automatically.
- Surface patches β small pieces of scroll surface, stored as
tifxyzmeshes (the grid-of-3D-points format used by VC3D). These can come from GrowPatch, lasagna (direct growth, or growth around fibers), neural Copy In/Out, or any other segmentation method. Only human-checked (verified) patches are recommended; they are also used to calculate evaluation metrics. - Strips and lines of points that follow the surface of a single sheet β either point collections drawn in VC3D, or fibers traced in VC3D.
- Relative winding annotations β sets of points lying on different windings, annotated with how many windings apart they are (e.g. "these two points are exactly one wrap apart"). Represented as VC3D point collections with relative-winding annotations.
- Absolute winding annotations β points annotated with the absolute winding number they lie on (e.g. "this patch is on winding 20"). Also VC3D point collections.
- Coarser volumetric guidance derived from machine-learning predictions: predicted surface normals (from lasagna, stored as zarr volumes), predicted gradient magnitude (which captures the local radial density of windings), and skeletonised surface-prediction tracks (created with
extract_surface_tracks.py). - Scroll-level structure: the umbilicus (the scroll's central axis, as a function of z β required), and optionally a mesh of the scroll's outermost surface, which pins down where the spiral must end.


None of these individually needs to cover the scroll. Sparse, scattered evidence β a patch in one region, a fiber in another, a few relative-winding annotations in an ambiguous area β is combined by the fit into one consistent global solution, and annotations placed where the scroll is most damaged contribute the most.
What comes outβ
The output is one tifxyz mesh per winding of the scroll β a full set of surfaces that conform to the input constraints, covering the whole fitted region including places no patch ever reached. Two variants are written for each winding: wNNN, the pure fitted spiral surface, and wNNN_spliced, where the geometry of verified patches is spliced into the fitted surface wherever the fit and the patch agree β more locally accurate wherever trusted geometry exists.
Since these are ordinary tifxyz meshes, everything downstream works as usual: you can load them in VC3D, flatten them, and render surface volumes for ink detection. The repo also includes a tool (render_ink.py) that concatenates the windings into fixed-width chunks, flattens them, and renders ink predictions as a series of horizontal strips β more on that below.
Alongside the meshes, a fit writes a model checkpoint, satisfaction metrics β per-input-type statistics of how much of the evidence the final surface actually honors β and, optionally, overlay images showing the fitted windings drawn over scan slices.
How to run itβ
The code lives in the villa repository under spiral-fitting; the main entry point is fit_spiral.py. You'll need Python β₯ 3.14 and an NVIDIA GPU.
git clone https://github.com/ScrollPrize/villa.git
cd villa/spiral-fitting
uv sync
Everything the fit needs is declared in the project's own pyproject.toml, torch included β on Linux it comes from the CUDA 12.8 wheel index, so there is no separate torch install to get right. uv sync also builds vc_spiral, a small C++ extension the fit uses to link point annotations to patch surfaces, so the machine needs cmake and a C++ toolchain; you no longer need a volume-cartographer Python install.
On Windows, uv sync also installs triton-windows, a community build of Triton, because PyTorch publishes no triton wheel there and the fit's fused kernels need one. The first run compiles those kernels once.
If you do not install through the pyproject.toml, ensure your torch version is <2.13 versions >= 2.13 will require significantly more vram due to internal torch changes
Get the datasetβ
Ready-made inputs are published in the spiral-input dataset, which lives on the dl.ash2txt.org data server : Spiral Datasets (~90 GB):
rclone copy :http: ./spiral_datasets/phercparis4 \
--http-url https://dl.ash2txt.org/datasets/spiral_datasets/PHercParis4/ \
--transfers 32 -P
Note that re-running rclone resumes interrupted downloads. For PHerc. Paris. 4, the dataset contains verified and unverified patches, tracks, fibers, the outer shell, winding annotation JSONs, the umbilicus, and the volume inputs β see the dataset README for the exact layout.
Generating missing inputsβ
The published dataset ships ready-made inputs, but for a new scroll β or a new region of one β some of them may not exist yet. This section covers the four machine-generated inputs that most often need to be built from scratch: tracks, graph patches, fiber directions, and winding inference. Build them in roughly that order: graph patches are grown from tracks, and winding inference needs an existing spiral fit to seed from.
Unless noted, commands run from villa/spiral-fitting inside its uv environment. Every input has to be in the fit's own voxel frame (the same frame as the umbilicus, patches and z_begin/z_end), and should cover at least the z range you plan to fit β inputs outside the fit window are dropped at load.
Tracksβ
Tracks are skeletonized 2D curves through a binarized surface prediction, cut on regularly spaced horizontal (h:) and vertical (vy:/vx:) slabs. They live in a stdlib dbm database under tracks/.
1. Get a surface prediction. Published surface predictions for each scroll are listed in the data browser (look for surface-prediction), e.g. the thresholded surface_m7 predictions under s3://vesuvius-challenge-open-data/<scroll>/representations/predictions/surfaces/. To make your own, run vesuvius.predict β vesuvius.blend_logits β vesuvius.finalize_outputs --mode binary --threshold (see the vesuvius inference docs). The extractor treats any value > 0 as surface, so the prediction must be thresholded, and it expects a 3D (Z, Y, X) array.
2. Extract the tracks:
.venv/bin/python extract_surface_tracks.py \
--predictions /path/to/surface-prediction.zarr/0 \
--out /path/to/dataset/tracks/<name>.dbm \
--z-min 4000 --z-max 17000
With a supported NVIDIA GPU (Linux x86-64, compute capability β₯ 8.0) this uses a fast GPU backend β a 4000-slice range takes seconds on a few H100s β and otherwise falls back to a much slower CPU skeletonizer (--backend, --gpus to choose). It also writes the packed <name>.dbm.vctracks/ store the fit loads fastest. Runs resume: slabs already in the database are skipped.
3. Optionally, cache the track crossings (the fit otherwise computes them in memory):
.venv/bin/python build_track_crossings.py /path/to/dataset/tracks/<name>.dbm
Fits read tracks only from the object store: ingest the database there (see the inputs); its filename doesn't matter. Tracks are off by default; enable them with input_use_tracks (see the fit configuration). The spiral-fitting README has GPU requirements and timings.
Graph patchesβ
Graph patches are tifxyz patches grown automatically from the tracks by grow_track_graph.py: starting from a seed track, it grows a sheet across track crossings, accepting a step only where enough crossing tracks agree. They need both track sidecars from above β the .vctracks store and the .crossings.npz cache β built from the same database:
.venv/bin/python grow_track_graph.py \
/path/to/dataset/tracks/<name>.dbm.vctracks \
/path/to/dataset/tracks/<name>.dbm.crossings.npz \
/path/to/dataset/graph_patches \
--random-count 1000 --workers 16
--random-count N grows N patches from random long seed tracks (or pass explicit track rows with --seeds). Re-running into the same folder adds new patches and skips seeds already used. The same tool is available in VC3D under Actions β Grow Track Patches..., which runs the script for you and loads the results.
Graph patches are machine-generated, not human-checked, but the fit has no separate input for them: they are read through the patches input, exactly like verified patches. Point the Verified patches path (paths.verified_patches) at the graph_patches/ folder, or at a folder containing both sets.
Fiber directionsβ
fiber_directions.npz holds sampled fiber orientations from a 3D fiber prediction. The loss only asks that the fitted sheet lie along the local fiber direction; it doesn't tie samples to a particular winding.
From an existing fiber prediction. Fiber predictions for several scrolls are already published on the open-data bucket, under <scroll>/representations/predictions/fibers/ (listed in the data browser). Each prediction folder contains a .lasagna.json manifest, which is all the extractor needs. For PHerc. Paris 4:
aws s3 ls --no-sign-request \
s3://vesuvius-challenge-open-data/PHercParis4/representations/predictions/fibers/20260411134726-fibers-20260801084232-L1/
Pass the manifest's HTTPS URL to fiber_direction_samples.py, from villa/spiral-fitting. It downloads only the chunks that intersect the z range and writes the samples to the file you name (then name that file as fiber_directions in the input manifest):
.venv/bin/python fiber_direction_samples.py \
https://vesuvius-challenge-open-data.s3.us-east-1.amazonaws.com/PHercParis4/representations/predictions/fibers/20260411134726-fibers-20260801084232-L1/PHercParis4-20260411134726-las-sd1-d74cca79.lasagna.json \
/path/to/dataset/fiber_directions.npz \
--z-roi 4000,17000 --output-scale 4 \
--presence-threshold 160 --cell-size 2
The manifest must be reachable over HTTP(S); a local path won't work. --z-roi is half-open and in fit coordinates, and --output-scale is the number of full-resolution scan voxels per fit voxel (4 for a fit at pyramid level /2, as for PHerc. Paris 4). Getting either wrong silently misplaces the samples, or leaves none inside the fit window. The fiber loss is off by default: set input_use_fiber_directions to true and loss_weight_fiber_directions above 0.
If no fiber prediction exists, run inference with the scrollprize/lasagna-fiber model. It writes presence, nx and ny channels plus a .lasagna.json manifest, and runs from the lasagna environment:
cd villa/lasagna
python3 scripts/bootstrap_venv.py --venv .venv --backend cu128
source .venv/bin/activate
hf download scrollprize/lasagna-fiber \
s1a_128_1_single_8x8_20260801_084232_best91_5k.pt --local-dir models/lasagna-fiber
python -m vesuvius.neural_tracing.fiber_trace_3d.infer \
--input /path/to/volume.zarr/1 \
--output /path/to/predictions/fiber.lasagna.json \
--checkpoint models/lasagna-fiber/s1a_128_1_single_8x8_20260801_084232_best91_5k.pt \
--devices all --tile-size 512 --overlap 96 --border 32 \
--inference-scaledown-power 2
The repository holds two variants, and each must be paired with the input pyramid level it was trained on: the SD1 checkpoint above takes group 1 of a 2.4 Β΅m scan, while the SD2 checkpoint (s1a_128_2_single_..._best_25_9k.pt) takes group 2. On a ~9 Β΅m scan, use the SD2 checkpoint on group 0. The model card has the details, including how to fetch input volumes with lasagna-download.
Then serve the prediction folder over HTTP (e.g. python3 -m http.server in /path/to/predictions, or upload it to a bucket) and run fiber_direction_samples.py on its manifest URL exactly as above.
Winding inferenceβ
winding_inference/ is a compact store of winding crossings predicted by a neural winding model along rays through the scroll. It drives the default dense-spacing mode (dense_spacing_mode: "winding_model"), so a fit whose input manifest names no winding_inference is refused under the default settings. To fit without it, set "dense_spacing_mode": "grad_mag" (which uses the gradient-magnitude volume instead) or "input_use_winding_inference": false.
Generating it takes a winding model and an existing spiral fit, since the rays are seeded on that fit's windings β so a first fit in grad_mag mode is the usual starting point. A trained model is published as scrollprize/winding_model_9um:
hf download scrollprize/winding_model_9um ckpt_final.pth config.json --local-dir models/winding_model_9um
It was trained on ~9.6 Β΅m volumes (2.4 Β΅m scans at pyramid level 2) from PHerc. 0139, PHerc. 1667 and PHerc. Paris 4, so run it on a volume at roughly that resolution. The tools live in vesuvius/src/vesuvius/neural_tracing/winding_models and run from a vesuvius environment.
1. Run the winding model along the fit, writing a native phase cache:
python infer_winding_volume.py \
/path/to/run/checkpoint_fitted.ckpt winding_native_phase.zarr \
--model-ckpt models/winding_model_9um/ckpt_final.pth \
--reference-zarr /path/to/volume.zarr --volume-scale 0 \
--z-range 4000 17000 --winding-step 3 --seed-spacing 60 \
--gpus 0,1 --native-phase-only
The reference zarr's scale-0 grid defines the output coordinates, so use the volume the fit runs on. --z-range and --winding-range default to the fitted checkpoint's ranges. It also needs the scroll's umbilicus.json (--umbilicus, or found from the checkpoint's dataset). The cache is large: it keeps the model's full float32 phase for every slab, 128 Γ 128 Γ 384 values or 25.2 MB per slab before compression for this model, so the ~1.56 million slabs behind the published PHerc. Paris 4 store come to about 39 TB of raw phase.
2. Export the compact store (and name its directory as winding_inference in the input manifest):
python export_spiral_supervision.py winding_native_phase.zarr \
/path/to/dataset/winding_inference --workers 32
The export is restartable, refuses to overwrite an existing store, and --validate /path/to/dataset/winding_inference checks a finished one. NATIVE_PHASE_CACHE.md documents both steps and the store format.
Without the cache. If the compact store is all you need, replace --native-phase-only with --spiral-supervision-only and give the store directory as the output; step 2 is then skipped:
python infer_winding_volume.py \
/path/to/run/checkpoint_fitted.ckpt /path/to/dataset/winding_inference \
--model-ckpt models/winding_model_9um/ckpt_final.pth \
--reference-zarr /path/to/volume.zarr --volume-scale 0 \
--z-range 4000 17000 --winding-step 3 --seed-spacing 60 \
--gpus 0,1 --spiral-supervision-only
Each slab's centre ray is decoded in memory by the exporter's own code, so the store holds the same arrays that steps 1 and 2 produce from the same model output, without the cache on disk. An interrupted run resumes from winding_inference.partial when you repeat the command. Keep the cache if you also want the --phase-cache reconstructions (points, winding volume, crossing_prob).
To train your own winding model, run train_winding_model.py <config.json> on volumes paired with existing segments or spiral fits; the published model's config.json is a working example.
Configureβ
Two separate things configure a run: where the data is β an object store and an input manifest, both named on the command line β and how to fit it, a flat set of named settings.
The inputsβ
Nothing is discovered from a directory layout: every input is named explicitly.
- Geometry β patches, point collections (
abs_winding.json,relative_windings.json,same_windings.json), fibers, tracks and the outer shell β is read only from an object store (--object-store scroll.vcobj). Import the downloaded files into one once withvc_object_ingest, as described under One-time dataset ingest; the outer shell is the store surface taggedspiral-outer-shell. Every ingested object declares the reference volume its coordinates are in (--volume-uuid). - Everything else is named in a JSON input manifest (
--inputs spiral-inputs.json). Relative paths resolve against the manifest's own directory, so the files can be called anything and live anywhere:
{
"schema_version": 1,
"volume_uuid": "<the --volume-uuid you ingested the store with>",
"scroll": {
"name": "PHercParis4",
"voxel_size_um": 9.6,
"spiral_outward_sense": "CW"
},
"umbilicus": {"path": "umbilicus.json"},
"lasagna": {"manifest": "lasagna_inputs/<name>.lasagna.json"},
"fiber_directions": "fiber_directions.npz",
"winding_inference": "winding_inference"
}
volume_uuid, scroll and umbilicus are required; volume_uuid must be the volume the selected store objects declare, or the fit is refused. name is free-form and is what appears in the generated run-folder name. spiral_outward_sense ("CW" or "ACW") says which way the spiral turns as it winds outward. No automated method determines it: it is read off the CT data by a person in VC3D, or taken from an already-fitted spiral (alternatively state the volume's catalog flags z_direction_is_top_to_bottom and left_handed_coordinates, which decide it). The scroll block can also carry the fit volume's base_shape_zyx, num_windings (a default for the winding-count settings), and lasagna_scale, the lasagna arrays' downsampling relative to the fit volume. When both the scroll block and the lasagna manifest state a base_shape_zyx, the fit derives the scale itself (the two grids must cover the same aligned volume extent) and a stated lasagna_scale only cross-checks it; otherwise lasagna_scale is required, so read it off the arrays' own .zattrs rather than copying another scroll's value.
lasagna, fiber_directions and winding_inference are optional, but a configuration whose losses read one refuses to start without it, listing every missing input. lasagna.manifest must be a local file; if it is a local copy of a remote Lasagna dataset, add "original_url": "<its https URL>" so the fit shares that dataset's prepared cache (nothing is downloaded). An optional scroll_zarr names the CT volume for visualization and may be a URL. Older spiral-scroll.json files are not read: move their facts into the scroll block, and the --dataset, --scroll-spec and --lasagna-url flags are refused. The spiral-fitting README documents the full schema.
Running the fitβ
There are two ways to run the spiral fitting, either through the CLI or through an interactive fit session in the VC3D spiral workspace. Both run the same fit_spiral.py script. They differ in two ways:
- The VC3D workspace can be configured to render a flatten view at an interval or on the fits completion
- The VC3D workspace supports adding inputs to "live" fits, interactively
- VC3D Workspace
- CLI
Starting a fit sessionβ
Open VC3D, select the scroll's volume package in VC3D, then select the Spiral workspace tab. It uses the same scan as the main workspace, with a flattened preview and CT slice views beside it. If you are planning on running the spiral service on the machine you're opening VC3D with , ensure you have the venv activated in the terminal before opening VC3D.
The spiral workspace runs through a service whether you're using it on the machine you're viewing VC3D through or over a network connection (internet or local LAN).
Navigating the UIβ
The spiral workspace is composed of two "windows": the configuration dock, on the left-side of the UI, and the flattened spiral view, which occupies the majority of the view. When no fit has returned a "preview", the flattened view is just a black rectangle.
The configuration dock for the most part should be used top-to-bottom, and all fits begin with a session "connection"

Connecting to a sessionβ
In Spiral Service, choose a connection:

- Local: set Output (and optionally Winding inference, the directory of a winding-inference store, needed only for winding-model supervision), then Connect. VC3D launches the service locally; its Python environment must have the spiral-fitting dependencies installed. The service has no dataset: the scroll's facts, umbilicus, Lasagna and fiber-inference datasets come from the open VC3D project, and geometry from the service's object store.
- Remote (SSH): start the service on the GPU machine using the command below, then click +SSH in VC3D. Enter
[user@]host(an SSH-config alias also works) and port8765, then Connect. Use SSH keys or an agent; if the host is new, connect once withssh user@hostin a terminal to accept its host key. VC3D creates the tunnel and retrieves the API key automatically. - Remote (LAN): start the same service with
--bind 0.0.0.0, then click +LAN. Set Endpoint tohttp://HOST:8765and paste the API key printed by the service. Direct HTTP is unencrypted; use it on a trusted network, or use SSH.
For either remote connection, run this on the GPU host from villa/spiral-fitting with dependencies installed (add --bind 0.0.0.0 for LAN):
uv run python spiral_service.py --port 8765 \
--object-store /data/scrolls/s1.vcobj --output /data/spiral-output/s1 \
--winding-inference /data/scrolls/s1/winding_inference \
--gpus 0 --session-name my-fit
--winding-inference is optional; VC3D shows whether winding-model supervision can run, and changing it means restarting the service. Keep this process running in a persistent terminal such as tmux. Remote fits continue when VC3D disconnects. Previews and checkpoints transfer automatically; a shared filesystem is unnecessary. A remote service needs its own replica of the same object-store hub VC3D uses; see the service README for the hub options.
Configuring and running the initial fitβ
The default parameters used by fit_spiral.py also apply to fit sessions run through the workspace. The only fields necessary for you to fill in are Output Directory, z begin and z end. If you'd like to override the defaults, click Open Spiral Configuration... and edit the fields. Hovering the mouse over the text for each field will show a brief description of what it does.

Set z begin / z end in Fit and output; start with a small range. Click Initialize Fit, choose Iterations, then Run. Stop after iteration pauses at the next completed step; another Run continues the fit. Initialization becomes Rebuild Fit once a fit exists. To resume a saved model, select it under Checkpoint and click Load.
Once the configured number of steps completes, or on the interval set by Background preview every.. spinbox when enabled, a flattened spiral surface will display in the viewer.
Navigation in the spiral preview surface and the volume views is similar to the rest of VC3D
right-click + dragto pan,- mouse-wheel to zoom,
- shift+wheel to move through slices on the flattened view,
Randctrl+cover a point to show that area in all views,Xrecenters the views on that focus if you have panned away
The spiral surface also contains a "minimap". Click the winding minimap below the flattened view to jump along the scroll. Use Min winding / Max winding limit the displayed windings (-1 means through the last).
Within the display section of the configuration dock is the Volume combobox, which allows you to select the primary displayed volume (Overlays are managed like regular VC3D, via the Overlay toolbar item). The spiral preview surface also has many additional overlays available. Use Display β to toggle output, input patches, fibers and point collections, surface intersections, winding boundaries, patch overlap, and run differences. Loss overlays require Compute loss overlays with the next preview, which roughly doubles preview cost. The fixed status area shows fit progress and preview age; Logs opens service messages.

Annotate and apply changesβ
When fitting a spiral using the spiral workspace, you can add constraints to a running fit.
| Key or gesture | Action |
|---|---|
| Tap Ctrl | Toggle patch painting; left-drag paints, right-drag erases |
| Ctrl+wheel | Change brush size |
| Shift+right-drag | Draw a freehand control-point line |
| Ctrl + right-click -> 2d line annotation | place control points to use in the fiber annotation, press E to optimize and display the line annotation window |
| Hold V + left-clicks | Draw a control-point line through chosen points; release V to finish |
| Q, then left-clicks | Place points belonging to the same winding |
| E, then left-clicks | Place relative-winding points numbered 0, 1, 2, β¦; click successive windings in order |
| F | Reverse the active point collection and its relative-winding ordering |
| Escape | Exit the current drawing/point-placement mode |
| Shift+E | Prepare drawing drafts for submission |

Use Add/Apply changes to submit ready drafts to the fit, including while it is running. Commit persists the selected changes into the object store; applying alone does not. For existing inputs, enable Show original store inputs, then right-click an entry and choose Edit. Patch and fiber editors save working copies; use Add/Apply afterward. Remove stages a removal, Restore reverses it before Commit, and committing the removal deletes the object from the store.

Preview intervals and renderingβ
Enable Background preview every and choose an interval in iterations before clicking Run (default interval: 100). The service captures the fit at an iteration boundary, exports its surface, and flattens it through Lasagna; fitting resumes while flattening continues. VC3D downloads the finished geometry and displays the scan on that surface. This is a geometry preview; ink strips are produced separately by Rendering ink.
A preview is also requested when a connected run finishes or is stopped. Exporting and flattening can take minutes, so the displayed preview may trail the fit; check its iteration and lag in the status area. Until a new preview succeeds, the previous one stays visible.
Where files liveβ
Generated files live on the service machine, under its Output root; the example above uses /data/spiral-output/s1/my-fit/. This holds fit run directories, previews, uploads, and checkpoints, including checkpoint_autosave.ckpt. For local services, an empty Output field uses a directory per object store in VC3D's application-data folder; set it explicitly for an easy-to-find location. The derived cache defaults to ~/.cache/vc3d/spiral.
Checkpoint β Save on Service saves remotely; Downloadβ¦ copies a checkpoint to your computer. VC3D also caches downloaded display artifacts locally. Only Commit writes your annotation changes back into the object store. See the service README for connection and storage details.
Improving the fit "interactively"β
Once the spiral surface is shown in VC3D you can inspect it for mistakes. Mistakes can be grouped into a few types, and the "fixes" for these mistakes can come from many different kinds of constraints.
Sheet Switches are areas where the spiral fit has started on one winding, lets call it winding A, and departs from it and continues along an adjacent winding B. You can fix these by either telling the spiral fit "this point continues this way" (patches, fibers), or "these two points are not the same winding" (relative winding annotations). For the most part unless relative winding annotations fall on patches (and produce links), you get more "bang for your buck" with patches or fibers in resolving these types of errors
Wandering is when the spiral fit shifts back and forth along the normal of the surface, never adhering quite to the proper sheet and occasionally (but only briefly) falling onto an adjacent winding. These are best resolved with patches, but fibers could suffice if there is simply just a complete lack of annotation in this area.
When you identify one of these areas, and you've added your fix (in the form of some new constraint, see the keybinds above) to the live fit, it's typically good pratice to disable the "DT" losses temporarily. These losses have a tendency to make the spiral "stick" to an annotation, making it hard for it to adjust to your new annotations. The VC3D spiral workspace makes this easy, by checking the box Restrict DT losses to final... and entering a percentage. In this example, the fit will run for 2000 additional iterations (extending its polynomial LR decay to account for the longer horizon), with the first 75% of those iterations having its "DT" losses disabled.

The fit configurationβ
Everything else β the fitted z-range, which inputs participate, loss weights, resolutions, step counts β is a flat dictionary of named settings defined in config.py: one attribute of the Config class per knob, each with its default. You can pass overrides as JSON:
FIT_SPIRAL_CONFIG_OVERRIDES='{"z_begin": 10500, "z_end": 11500, "optimizer_num_training_steps": 10000}' \
python fit_spiral.py --inputs spiral-inputs.json --object-store phercparis4.vcobj \
--object-store-author "$USER"
The settings you are most likely to touch:
-
z_begin,z_endβ the slice range (in full-resolution voxels) to fit; the defaults, 4,000 and 17,000, span the whole written region of Scroll 1. Consider starting with a small range: fitting all of it needs a lot of GPU memory and time, and a ~1,000-slice range is a good first run on a smaller GPU. Per-step sample counts are scaled automatically to the size of the z-range, so the other hyperparameters don't need retuning when you change it. -
input_use_*β whether an input that is present is actually used. Each optional input source has its own toggle, independent of whether its file is there:input_use_verified_patches,input_use_tracks,input_use_fibers,input_use_fiber_directions,input_use_normals,input_use_gradient_magnitude,input_use_winding_inference,input_use_outer_shell, plus one per annotation role βinput_use_pcl_absolute,input_use_pcl_relative,input_use_pcl_same_winding,input_use_pcl_drawn_control_points.Note thatinput_use_tracksdefaults tofalse, so a store that holds tracks will not use them unless you turn it on:FIT_SPIRAL_CONFIG_OVERRIDES='{"input_use_tracks": true, ...}'A few ready-made override files live in
configs/.
A few environment variables control the run itself rather than the fit:
| Variable | Effect |
|---|---|
FIT_SPIRAL_CONFIG_OVERRIDES | JSON dict of Config overrides, e.g. '{"optimizer_num_training_steps": 10000}' |
FIT_SPIRAL_OUT_DIR | Parent directory for the generated run folder (default ./out) |
FIT_SPIRAL_RUN_DIR | Use this exact directory as the run folder, instead of generating a name |
FIT_SPIRAL_RUN_TAG | Tag appended to the output folder and mesh names |
FIT_SPIRAL_RESUME_PATH / FIT_SPIRAL_RESUME_STEP | Resume from a checkpoint |
WANDB_MODE | Set to online to log losses and visualizations to Weights & Biases (default disabled) |
The cache of preprocessed inputs β which speeds up subsequent runs a lot β defaults to ~/.cache/vc3d/spiral, shared across scrolls since its entries are content-addressed; --cache DIR (or FIT_SPIRAL_CACHE_DIR) moves it elsewhere.
Fitβ
python fit_spiral.py --inputs spiral-inputs.json --object-store phercparis4.vcobj \
--object-store-author "$USER"
That's it β the script loads the inputs (caching the expensive preprocessing), then runs 30,000 optimization steps, printing the loss breakdown every 200 steps. Multi-GPU is supported via torchrun --nproc-per-node=N fit_spiral.py --inputs ... --object-store ..., which splits each step's work across GPUs.
To run the whole pipeline in one command β fit, then render ink, then score it β use runners/run_single.py instead. It takes the same --inputs and --object-store, plus an --ink-volume, and accepts the same configuration overrides as a --config JSON file; runners/run_sweep.py runs a whole folder of such configs concurrently across GPUs.
When it finishes, you get a self-contained run folder:
out/2026-07-08_s1_slice-10500-11500_27399-patch_<run-name>/
βββ checkpoint_fitted.ckpt # fitted model (resumable)
βββ satisfied_fitted.json # which individual inputs the fit honors
βββ satisfaction_metrics_fitted.json # and the summary of those, per input type
βββ spiral_on_*_fitted.png # fitted windings overlaid on inputs