nispace.transforms.compute_transform_displacement
- nispace.transforms.compute_transform_displacement(mni_from, mni_to, nispace_data_dir=None, hash_check=True, verbose=True)[source]
Compute a voxel-wise displacement magnitude map for a MNI space transform.
For each voxel in the
fwd_fielddeformation field (estimated with EasyReg [17], built on SynthMorph [18] and SynthSeg [19]; the field used for pull resampling — see Notes inmni_to_mni()), computes the Euclidean distance in mm between the voxel’s RAS position inmni_tospace and the storedmni_fromRAS coordinates. The result visualises how much each location is displaced between the two spaces and is useful for registration quality control.- Parameters:
mni_from (str) – Source MNI space. Accepts the same canonical names, partial names, and aliases as
mni_to_mni().mni_to (str) – Target MNI space. Same options as
mni_from.nispace_data_dir (str or Path, optional) – Override for the NiSpace data directory. Defaults to the
NISPACE_DATA_DIRenvironment variable or the standard download cache.hash_check (bool) – Verify the downloaded field file against the expected hash. Default
True.verbose (bool) – Emit log messages. Default
True.
- Returns:
Float32 scalar image in
mni_tospace at 1 mm isotropic resolution (the native resolution of the deformation field). Each voxel value is the displacement magnitude in mm. Near-zero values indicate little warping between the two spaces; large values indicate strong local deformation. Expected range for closely related MNI variants is roughly 0–6 mm; values > 20 mm outside the brain mask are normal field extrapolation artefacts.- Return type:
nibabel.Nifti1Image
Notes
The displacement at voxel v is computed as:
||field[v] - ras(v)||₂
where
field[v]is the storedmni_fromRAS coordinate andras(v)is themni_toRAS coordinate of voxel v derived from the field affine. The output image is inmni_tospace because thefwd_fieldis defined on the reference (target) grid.References