nispace.transforms.mni_to_mni

nispace.transforms.mni_to_mni(img, mni_from, mni_to, order=3, res=None, nispace_data_dir=None, hash_check=True, verbose=True)[source]

Transform a NIfTI image between MNI template spaces using EasyReg fields.

Deformation fields were estimated with EasyReg [17] (Freesurfer), which builds on the SynthMorph [18] registration and SynthSeg [19] segmentation networks, between each supported source space and both hub spaces (MNI152NLin2009cAsym and MNI152NLin6Asym). Transforms between two non-hub spaces (e.g. MNI305 → MNIColin27) are not directly supported.

Parameters:

  • img (str, Path, or nibabel.SpatialImage) – Input image to resample.

  • mni_from (str) –

    Source MNI space. Accepts canonical names, unambiguous prefixes or substrings (case-insensitive), and named aliases:

    Canonical name

    Notes

    MNI152NLin2009cAsym

    fMRIPrep / templateflow default

    MNI152NLin6Asym

    FSL / HCP standard

    MNI152Lin

    Linearly registered ICBM 152

    MNI305

    Original MNI template

    MNIColin27

    Colin Holmes single-subject average

    MNI152NLin2009cSym

    MNI152NLin6Sym

    Named aliases: SPM / SPM5 / SPM8 / SPM12 → MNI152Lin (all SPM versions normalise to the same linearly- registered ICBM 152 space); FSL / HCP → MNI152NLin6Asym; MNI152NLin2009a / MNI152NLin2009b → MNI152NLin2009cAsym.

    Unambiguous partial names are also accepted, e.g. "Colin" → MNIColin27, "MNI152Li" → MNI152Lin.

  • mni_to (str) – Target MNI space (same options and aliases as mni_from).

  • order (int or str) –

    Interpolation order for nitransforms. Accepts integers 0–5 or the strings "nearest" (→ 0), "linear" (→ 1), or "cubic"/"continuous" (→ 3). Default is 3 (cubic spline), which gives the best quality for continuous data. Use 0 / "nearest" for label or parcellation images to avoid interpolation artefacts.

    Comparison with other tools: neuromaps "linear" = this order=1; nilearn "continuous" ≈ this order=3.

  • res (int, str, or None) – Output voxel size in mm. Accepted forms: 1, 2, 3, 4 or "1mm", "2mm", "3mm", "4mm". If None (default), the nearest supported resolution to the input voxel size is used. A UserWarning is raised when res is finer than the input voxel size (the output grid is denser but effective resolution is still limited by the input).

  • nispace_data_dir (str or Path, optional) – Override for the NiSpace data directory. Defaults to the NISPACE_DATA_DIR environment variable or the standard download cache.

  • hash_check (bool) – Verify the downloaded field file against the expected hash. Default True. Set to False to skip integrity checks (e.g. when working with custom or locally estimated fields).

  • verbose (bool) – Emit log messages. Default True.

Returns:

Input image resampled into mni_to space at the requested resolution.

Return type:

nibabel.Nifti1Image

Notes

EasyReg field convention — why the forward field is used for resampling

EasyReg produces two coordinate-map fields (each voxel stores absolute RAS coordinates, not displacements):

  • fwd_field: defined on the reference (target) grid, stores the corresponding floating (source) RAS coordinates. This is the field needed for pull resampling: “for each output voxel, sample from the input at these coordinates.”

  • bak_field: defined on the floating (source) grid, stores the corresponding reference (target) RAS coordinates. This is a forward map used by EasyReg’s own mri_easywarp tool (push resampling), but it is not directly usable for pull resampling.

NiSpace uses nitransforms for pull resampling, so it loads the fwd_field — despite “forward” sounding counter-intuitive for a source→target transform. Using bak_field instead produces a systematic ~1–2 mm shift (visible as a slight left-hemisphere offset in standard radiological view) because the field is defined on the wrong grid.

References

[17] (EasyReg); [18] (SynthMorph); [19] (SynthSeg).