Add Allen RAS+ alignment + 3D rigid registration (linumpy.reference)

[FIrgolitsch]

Summary

Extends linumpy.reference.allen with RAS+ alignment of the Allen CCF template and a 3D rigid registration routine that aligns a mouse-brain volume to that template. Adds a full offline test suite (the Allen download is monkey-patched) covering orientation, numpy↔SimpleITK conversion, end-to-end self-registration, and downsampling/cropping behaviour.

Land after #141.

What changed

• numpy_to_sitk_image(volume, spacing, cast_dtype=None) — converts a (Z, Y, X) numpy array to a SimpleITK image with correct (X, Y, Z) spacing; optional dtype cast without mutating the input.
• download_template_ras_aligned(resolution, ...) — downloads the Allen average template and reorients it from its native PIR (== Allen-documented "ASL") layout to RAS+ (+X=Right, +Y=Anterior, +Z=Superior) via PermuteAxes((2,0,1)) + Y/Z flips. The anatomical reasoning (olfactory-bulb / DV-band / ML-symmetry landmarks) is documented inline.
• register_3d_rigid_to_allen(...) — multi-resolution Euler3DTransform registration against the RAS template with several robustness measures:
  • Atlas downsampling when the moving image is coarser than the Allen template (keeps the cost dominated by real information).
  • Tissue bounding-box crop with a 10-voxel margin so motor-drift canvas padding doesn't clip brain tissue during resampling; the crop offset is restored into the final translation so the transform stays valid for the original volume.
  • Smart initialization — uses the resampled brain-tissue centroid (not the full-canvas geometric centre) after resampling, since the latter can lie tens of mm outside the Allen domain and break the optimizer.
  • Configurable metric (MI/MSE/CC/AntsCC), optional iteration callback, optional initial rotation.
• Minor: download_template now uses Path(...).open() + writelines(tqdm(...)).

Tests (test_io_allen.py, new)

• Orientation — synthetic PIR template → asserts the RAS output has +X=Right, +Y=Anterior, +Z=Superior via per-axis gradient checks; size reflects the permutation.
• numpy_to_sitk_image — round-trip value/spacing/dtype preservation, input not mutated.
• Real-NRRD regression — gated on a cached .data/allen_template_100um.nrrd; locks the PIR/ASL layout and the RAS result against silent upstream changes.
• Registration — self-registration recovers ~identity; atlas downsampling triggers (or not) based on moving spacing; crop-offset restoration produces the expected translation log.

Reviewer focus

• The PIR→RAS recipe and its reasoning (download_template_ras_aligned) are the scientifically load-bearing part — the inline derivation and the synthetic + real-NRRD landmark tests are the place to confirm correctness.
• register_3d_rigid_to_allen is long; the highest-risk logic is the centroid re-initialization after resampling and the crop-offset restoration into the SITK (X,Y,Z) translation. Both have explicit tests; worth a close read.
• The registration can be slow on large volumes; the default 25% metric sampling and 4-level pyramid are the knobs to scrutinize for the speed/accuracy trade-off.

How to verify

uv run ruff check linumpy/reference/allen.py linumpy/tests/test_io_allen.py
uv run ty check linumpy/reference/allen.py linumpy/tests/test_io_allen.py
uv run pytest linumpy/tests/test_io_allen.py -x -v