neural_tracing: add opt-in displacement scaling across voxel sizes

[Nieuwlaar]

neural_tracing: add opt-in displacement scaling across voxel sizes

Refs #1149.

This implements the three changes @LimeGS proposed in #1149. The analysis, the benchmark, and the interface are theirs; I wrote the patch because the issue has had no maintainer reply in sixteen days and I wanted the option available. Happy to close this in favour of their own PR, or to co-author, whichever they prefer.

Background

Per #1149, copy_displacement_latest was trained at 4.8 µm, and infer_rowcol_triplet_wraps.py applies predicted displacement vectors directly (world + slot_*_disp) with no resolution conversion. On one 7.91 µm Scroll 3 window, a post-hoc 4.8 / 7.91 = 0.6068 scale changed wrong-hop rates from 63.17% to 5.90% (front, n=4,697) and 56.28% to 7.73% (back, n=8,697).

@LimeGS is explicit that this is a local geometric benchmark rather than ground truth: it shows a magnitude-calibration problem in that window, and does not establish that automatic 4.8 / input_pitch scaling is universally correct. The underlying question in the issue, what the intended output-unit contract is for non-4.8 µm inputs, is still unanswered, so nothing here changes behaviour unless you ask it to.

What this adds

--displacement-scale, accepting either a positive number or auto:

# explicit, the value from the issue
--displacement-scale 0.6068
# derive training_voxel_size_um / inference voxel size from the checkpoint
--displacement-scale auto

It is also exposed as a trace-service copy arg through _COPY_ARG_TO_CLI.

Default behaviour is unchanged. With no flag, displacements are applied unscaled exactly as before. This deliberately follows the issue's request to keep scaling opt-in and not enable automatic scaling before the semantics are confirmed.

A warning, but only for a genuine mismatch. When the checkpoint config carries training_voxel_size_um and it differs from the inference voxel size, a warning names both values and suggests the flag. Checkpoints without that key stay completely silent, so nobody gets new noise for an unchanged setup. No published checkpoint carries the key today, so in practice this is inert until someone adds it.

Provenance. displacement_scale and displacement_scale_source (cli, auto, or default) are recorded in the run and tifxyz metadata, so a rendered surface says which scale produced it.

Implementation notes

The scale multiplies the six displacement channels once, immediately after prediction and before accumulation, in _run_triplet_inference. Side assignment uses the sign of displacement dotted with the normal, which is invariant under positive scaling, so it is unaffected.

The inference voxel size is the volume's meta.json voxelsize (or --tifxyz-voxel-size-um) multiplied by 2**volume_scale, reusing the same retarget_factor already used to retarget the surface grid. The unrelated 8.24 µm fallback in resolve_tifxyz_params is deliberately not used for scaling: guessing a voxel size and silently rescaling geometry from it would be worse than doing nothing.

Tests

vesuvius/tests/neural_tracing/test_displacement_scale.py covers the unscaled default (silent, and with the mismatch warning), auto derivation and each of its failure modes, explicit overrides including disagreement with checkpoint metadata, invalid inputs, and the auto predicate itself.

python -m pytest tests/neural_tracing/ -q
119 passed

Open question for maintainers

The issue's actual question still stands: should displacements on non-4.8 µm volumes be interpreted in training-grid or inference-grid voxels? If the answer is training-grid, then auto is arguably the right default and I am happy to flip it. This PR does not presume that answer.

[vercel]

@nieuwlaar42 is attempting to deploy a commit to the scroll Team on Vercel.

A member of the Team first needs to authorize it.