Fix(io): formats bound to RAS/LPS validate their endpoints; a transformation is never relabelled as a format (#343)

[balbasty]

Since #315, t.to(SomeFormat) relabelled any family member as the format. For example, a Scaling from LPS to LPS became a NiftiVoxelToRAS that was still labelled LPS→LPS, and io.save wrote it.

This PR follows the decision in #343 and its review: no priority. Classes bound to semantic axes validate their endpoints, so a wrong relabel fails when the object is built. Explicit converters remain only where they bridge exactly, or where no validator can decide.

Validators

Each class bound to a system has an explicit __post_init__ that checks its endpoints with check_endpoint(t, side, expected), a new module-level helper in io/transformations/base/affines.py.

• Classes: VoxelToRAS, RASToVoxel, VoxelToLPS, LPSToVoxel, RASToRAS (inherited by the NIfTI and NiftyReg affines), RASCoordinatesField, LPSCoordinatesField (inherited by NiftiRASCoordinatesField), RASToWarpField/WarpFieldToRAS, and FlirtTransform.

• Compatible, not a subclass: an endpoint passes if it is compatible with the bound system. None, unknown axes and open systems are accepted.

• ⚠️ Two allowances beyond CoordinateSystem.compatible_with, which otherwise rejects systems that are clearly the same:

  • Axis names are ignored. RASmm names its axes x/y/z while RASCoordinateSystem names them by orientation, and VoxelCoordinateSystem uses dim0… while FVoxelCoordinateSystem uses i/j/k.
  • A system with fewer axes is compared with the first axes of the template, so a 2-D ITK world in L/P matches.

  This is done in io by rebuilding the axes without their names. Your call: a name-insensitive option in the datamodel's compatible_with might be the better home.

• The error is brainhops.errors.IncompatibleSystemError(ConversionError). Building a class directly with the wrong endpoints raises it. Because it is a ConversionError, t.to(...) also raises it (or returns False with error=False), and io.save lists it as a reason. convert needs no change.

Converters

Format	t.to(Format)
NiftiVoxelToRAS / NiftiRASToVoxel	Exact for every affine family, through affine_between: LPS is bridged into RAS, and unknown systems are taken as the format's. An LPS→LPS Scaling is still refused.
NiftyRegAffine	Exact through RAS→RAS, now also for unknown systems. Voxel systems are refused.
VoxelToRAS, RASToRAS, … (not formats)	Relabelled only if the endpoints are compatible, otherwise IncompatibleSystemError.
NIfTI fields, SPM	Exact (#314, unchanged).
MatrixAffine (all containers)	Relabel allowed: a bare matrix keeps the affine's own endpoints, so the map is unchanged. Txt→Csv is allowed.
ITK TFM/H5/MAT	A chain may be relabelled; anything else is refused by the generic fallback.
FLIRT	Refused: its matrix depends on the raw matrix and the two images.
LTA, NiftyReg fields, ITK NIfTI fields, FNIRT, M3Z, OME-Zarr	Refused, citing #312. For each, a relabel would build a wrong object or one that cannot be built.
X5, elastix	Refused by the generic fallback (as on main).

• Kept:
  • the exact bridging converters for NIfTI and NiftyReg, with their family source keys, because the family converter doesn't flip LPS to RAS;
  • the Feat(io): convert general transformations exactly into the NIfTI and SPM formats (#120) #314 field and chain converters;
  • converters from a format to its own class, where a converter on the format's family would otherwise catch that case. They defer to the family rebuild (_convert_withlog, _convert_withsplines, smart_replace), never replace.
• Removed: the refusals that the validators now make redundant, the refusals for MatrixAffine and ITK chains, and NiftyReg's refusal of undeclared systems.
• Converting a format to its own class works for every format: .to(matrix=...), inverse() and .to(log=False). This fixes NiftyRegAffine(...).inverse(), .to(matrix=...) and .to(log=False), which raised on main.

⚠️ Behaviour changes to review

• A plain Affine with no declared systems is now saved as NiftyReg to .txt, consistent with "unknown means the format's systems". Main's test_plain_affine_is_not_saved_as_niftyreg became test_plain_affine_is_saved_as_niftyreg, which also checks the round trip, and a new test_a_voxel_affine_is_not_saved_as_niftyreg is added. Say if NiftyReg should instead keep refusing undeclared endpoints.
• MatrixAffine and ITK chains accept relabels, as described above.
• io.save of a voxel→voxel transformation to .nii or .txt is refused; main wrote it relabelled.
• Open: whether the FSL scaled-mm classes should get validators that know the image geometry later. Their systems depend on the image.

Tests

• Restored: the [scaling] case of test_a_transformation_no_nifti_format_holds_is_refused, an LPS→LPS Scaling. It fails on main.
• tests/test_io_into_formats.py (251 tests):
  • validators reject incompatible endpoints on direct construction (10 affine classes, both coordinates fields, FLIRT);
  • compatible endpoints are accepted (unknown, other names, unknown axes, open systems, 2-D LPS);
  • a relabel into a bound class raises ConversionError, and error=False returns False;
  • refusals across 12 families × 12 formats, the [FEAT] Exact converters into the remaining transformation formats (ITK, NiftyReg, LTA, M3Z, X5, Elastix) #312 refusals, and the FLIRT reason;
  • MatrixAffine and ITK relabels are allowed, and NiftyReg accepts unknown endpoints;
  • the exact bridges, a format converted to its own class, and variants of one format;
  • io.save refusals.

Checks

• Full suite (Python 3.8): 5340 passed, 91 skipped, 1 xpassed. Main (56190e3): 5087 passed.
• ruff check, ruff format --check and codespell (with CI's ignore-words file) are clean.
• Main (56190e3) is merged into the branch.

Closes #343

🤖 Generated with Claude Code

https://claude.ai/code/session_01M3KmPTJ2CihFMCFaJ4twx8