Differences between revisions 3 and 12 (spanning 9 versions)

Index

Contents

Name
Description
Synopsis
Arguments
1. Required Flagged Arguments
  1. Exactly one input is required
  2. Exactly one output is required
2. Optional Flagged Arguments
Examples
Notes on Freesurfer 3D Morph MGZ Format
See Also
Reporting Bugs

Name

mri_warp_convert

Description

Converts non-linear deformation warp fields between different file formats. Some formats may require you to pass an image if the geometry information is missing from the transform file.

Synopsis

mri_warp_convert <input-type> <output-type> [options]

Arguments

Required Flagged Arguments

Exactly one input is required

Flag	Description
--inm3z <in.m3z>	input Freesurfer 3D morph in M3Z format
--inmgzwarp <inwarp.mgz>	input Freesurfer 3D morph in mgz format
--infsl <in.nii.gz>	input FSL warp (recommend to use with --insrcgeom)
--inspm <y_rinput.nii>	input SPM warp (use with --insrcgeom). Use --inwarpformat <> to specify the data format, which is either abs-ras (default) or abs-crs.
--inlps, --initk <in.nii.gz>	input LPS-to-LPS displacement field (e.g. ITK, ANTs)
--inras <in.nii.gz>	input RAS-to-RAS displacement field (e.g. NiftyReg)
--invox <in.mgz>	input displacement field in source-voxel space

Exactly one output is required

Flag	Description
--outm3z <out.m3z>	output Freesurfer 3D morph in M3Z format
--outmgzwarp <outwarp.mgz>	output Freesurfer 3D morph in mgz format
--outfsl <out.nii.gz>	output warp in FSL format
--outlps, --outitk <out.nii.gz>	output LPS-to-LPS displacement field (e.g. ITK, ANTs)
--outras <out.nii.gz>	output RAS-to-RAS displacement field (e.g. NiftyReg)
--outvox <out.mgz>	output displacement field in source-voxel space

Optional Flagged Arguments

Flag	Description
-g, --insrcgeom <geom.mgz>	specify volume geometry of the input to the warp space, i.e., srcgeom shares an RAS space with the warp volume. Usually this is identical to the geom of the warp volume itself (if the warp input is in a format that has such info). This also allows the input to the warp to have a different geometry than the warp itself, though this is probably better handled with -lta1.
-d, --downsample	downsample output M3Z to spacing of 2.
-lta1 LTA (or -lta1-inv)	create composite morph for warping a source image -> LTA1 -> GCAM -> LTA2 -> atlas/destination image
-lta2 LTA (or -lta2-inv)	create composite morph for warping a source image -> LTA1 -> GCAM -> LTA2 -> atlas/destination image
--inwarpformat <format>	specify warp data format: abs-crs, disp-crs, abs-ras, or disp-ras (default is abs-crs). This option only works with '--inspm <>'.
--outwarpformat <format>	specify warp data format: abs-crs, disp-crs, abs-ras, or disp-ras (default is abs-crs)
--vg-thresh <vgthresh>	specify threshold for testing diffs in volume geom

Examples

Example 1

Convert FSL warp to M3Z (FreeSurfer):

mri_warp_convert --infsl fsl.nii.gz --outm3z out.m3z --insrcgeom src.nii.gz

Example 2

Convert ITK warp (e.g. ANTs) to M3Z (FreeSurfer):

mri_warp_convert --initk itk.nii.gz --outm3z out.m3z --insrcgeom src.nii.gz

Example 3

Convert ANTS antsRegistrationSyN.sh or antsRegistrationSyNQuick.sh output to M3Z (FreeSurfer):

antsRegistrationSyNQuick.sh -d 3 -m mov.mgz -f targ.mgz -o reg.

ConvertTransformFile 3 ants.reg0GenericAffine.mat ants.reg0GenericAffine.txt --hm --ras

lta_convert --src mov.mgz --trg targ.mgz --inniftyreg ants.reg0GenericAffine.txt --outlta ants.reg0GenericAffine.lta

mri_warp_convert --lta1-inv ants.reg0GenericAffine.lta --initk ants.reg1Warp.nii.gz --outm3z out.m3z --insrcgeom targ.mgz

Note that the insrcgeom is the target, not the mov; this is needed to work with --lta1-inv.

Example 4

Convert M3Z (FreeSurfer) to ITK warp (e.g. ANTs):

mri_warp_convert --inm3z in.m3z --outitk out.nii.gz

Example 5

Convert M3Z (FreeSurfer) to mgz warp (FreeSurfer) in absolute CRS:

mri_warp_convert --inm3z in.m3z --outmgzwarp outwarp.mgz --outwarpformat abs-crs

Notes on Freesurfer 3D Morph MGZ Format

The Freesurfer 3D morph MGZ files follow Freesurfer MGZ format with intent MGZ_INTENT_WARPMAP and specific TAG attributes.

TAG Attributes

TAG	Comment
TAG_GCAMORPH_GEOM	gcamorph image (source) geom gcamorph atlas (target) geom
TAG_GCAMORPH_GEOM_PLUSSHEAR	gcamorph image (source) geom with shears gcamorph atlas (target) geom with shears
TAG_GCAMORPH_META	1. WARPFIELD_DTFMT_ABS_CRS, WARPFIELD_DTFMT_DISP_CRS, WARPFIELD_DTFMT_ABS_RAS, or WARPFIELD_DTFMT_DISP_RAS 2. spacing (int) 3. exp_k (double)
TAG_GCAMORPH_LABELS	gcamorph label data
TAG_GCAMORPH_AFFINE	gcamorph m_affine matrix

Data Array

The data array (width x height x depth x nframes) is indexed by atlas CRS:

frame 0 : image voxel ABS coordinate C, voxel DISP coordinate C, image RAS ABS coordinate X, or RAS DISP coordinate X
frame 1 : image voxel ABS coordinate R, voxel DISP coordinate R, image RAS ABS coordinate Y, or RAS DISP coordinate Y
frame 2 : image voxel ABS coordinate S, voxel DISP coordinate S, image RAS ABS coordinate Z, or RAS DISP coordinate Z

Data Formats

WARPFIELD_DTFMT_ABS_CRS	CRS coordinates in image space
WARPFIELD_DTFMT_DISP_CRS	displacement CRS, delta = image_CRS - atlas_CRS
WARPFIELD_DTFMT_ABS_RAS	RAS coordinates in image space
WARPFIELD_DTFMT_DISP_RAS	displacement RAS, delta = image_RAS - atlas_RAS

MGZ to Nifti Conversion

The Freesurfer 3D morph MGZ files (MGZ_INTENT_WARPMAP) can be converted to Nifti with intent code NIFTI_INTENT_DISPVECT.

NIFTI_INTENT_DISPVECT has shape [5, c, r, s, 1, 3], and the displacement field vector is in RAS space. Freesurfer reads the 5th dimensions as extra frames in MRI struct.

Reporting Bugs

Report bugs to < analysis-bugs@nmr.mgh.harvard.edu >

-  ⇤ ← Revision 3 as of 2026-02-09 23:22:19 → 
  Size: 4100
  Editor: YujingHuang
  Comment:
+   ← Revision 12 as of 2026-02-10 18:06:34 → ⇥
  Size: 6249
  Editor: YujingHuang
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 15:
-||Flag ||Description ||
+||'''Flag''' ||'''Description''' ||
 Line 19:
-||--inspm <y_rinput.nii> ||input SPM warp (use with --insrcgeom), data format is either abs-ras (default) or abs-crs. use --inwarpformat <> to specify the data format. ||
+||--inspm <y_rinput.nii> ||input SPM warp (use with --insrcgeom). Use --inwarpformat <> to specify the data format, which is either abs-ras (default) or abs-crs. ||
 Line 22:
-||--invox <in.mgz> ||input file with displacements in source-voxel space ||
+||--invox <in.mgz> ||input displacement field in source-voxel space ||
 Line 26:
-||Flag ||Description ||
+||'''Flag''' ||'''Description''' ||
 Line 32:
-||--outvox <out.mgz> ||output file with displacements in source-voxel space ||
+||--outvox <out.mgz> ||output displacement field in source-voxel space ||
 Line 36:
-||Flag                         ||Description ||
||-g, --insrcgeom <geom.mgz>   ||specify volume geometry of the input to the warp space, i.e., srcgeom shares an RAS space with the warp volume. Usually this is identical to the geom of the warp volume itself (if the warp input is in a format that has such info). This also allows the input to the warp to have a different geometry than the warp itself, though this is probably better handled with -lta1. ||
||-d, --downsample             ||downsample output M3Z to spacing of 2. ||
||-lta2 LTA (or -lta2-inv)     ||create composite morph for warping a source image -> LTA1 -> GCAM -> LTA2 -> atlas/destination image ||
||--inwarpformat <format>      ||specify warp data format: abs-crs, disp-crs, abs-ras, or disp-ras (default is abs-crs). (Only --inspm <> uses this option.) ||
||--outwarpformat <format>     ||specify warp data format: abs-crs, disp-crs, abs-ras, or disp-ras (default is abs-crs) ||
||--vg-thresh <vgthresh>       ||specify threshold for testing diffs in volume geom ||
+||'''Flag''' ||'''Description''' ||
||-g, --insrcgeom <geom.mgz> ||specify volume geometry of the input to the warp space, i.e., srcgeom shares an RAS space with the warp volume. Usually this is identical to the geom of the warp volume itself (if the warp input is in a format that has such info). This also allows the input to the warp to have a different geometry than the warp itself, though this is probably better handled with -lta1. ||
||-d, --downsample ||downsample output M3Z to spacing of 2. ||
||-lta1 LTA (or -lta1-inv) ||create composite morph for warping a source image -> LTA1 -> GCAM -> LTA2 -> atlas/destination image ||
||-lta2 LTA (or -lta2-inv) ||create composite morph for warping a source image -> LTA1 -> GCAM -> LTA2 -> atlas/destination image ||
||--inwarpformat <format> ||specify warp data format: abs-crs, disp-crs, abs-ras, or disp-ras (default is abs-crs). This option only works with '--inspm <>'. ||
||--outwarpformat <format> ||specify warp data format: abs-crs, disp-crs, abs-ras, or disp-ras (default is abs-crs) ||
||--vg-thresh <vgthresh> ||specify threshold for testing diffs in volume geom ||
-Line 48:
+Line 49:
-Line 51:
+Line 53:
-Line 54:
+Line 55:
-Line 57:
+Line 59:
+== Example 3 ==
Convert ANTS antsRegistrationSyN.sh or antsRegistrationSyNQuick.sh output to M3Z (FreeSurfer):
-Line 58:
+Line 62:
-== Example 3 ==
Convert ANTS antsRegistrationSyN.sh or antsRegistrationSyNQuick.shboutput to M3Z (FreeSurfer):
-Line 72:
+Line 74:
-* Note that the insrcgeom is the target, not the mov; this is needed to work with --lta1-inv.
+Note that the insrcgeom is the target, not the mov; this is needed to work with --lta1-inv.
-Line 76:
+Line 78:
-Line 79:
+Line 82:
-Line 82:
+Line 84:
-Line 85:
+Line 88:
+= Notes on Freesurfer 3D Morph MGZ Format =
The Freesurfer 3D morph MGZ files follow Freesurfer MGZ format with intent MGZ_INTENT_WARPMAP and specific TAG attributes.
=== TAG Attributes ===
||'''TAG''' ||'''Comment''' ||
||TAG_GCAMORPH_GEOM ||gcamorph image (source) geom gcamorph atlas (target) geom ||
||TAG_GCAMORPH_GEOM_PLUSSHEAR ||gcamorph image (source) geom with shears gcamorph atlas (target) geom with shears ||
||TAG_GCAMORPH_META || 1. WARPFIELD_DTFMT_ABS_CRS, WARPFIELD_DTFMT_DISP_CRS, WARPFIELD_DTFMT_ABS_RAS, or WARPFIELD_DTFMT_DISP_RAS 2. spacing (int) 3. exp_k (double) ||
||TAG_GCAMORPH_LABELS || gcamorph label data ||
||TAG_GCAMORPH_AFFINE || gcamorph m_affine matrix ||

=== Data Array ===
The data array (width x height x depth x nframes) is indexed by atlas CRS:
 * frame 0 : image voxel ABS coordinate C, voxel DISP coordinate C, image RAS ABS coordinate X, or RAS DISP coordinate X
 * frame 1 : image voxel ABS coordinate R, voxel DISP coordinate R, image RAS ABS coordinate Y, or RAS DISP coordinate Y
 * frame 2 : image voxel ABS coordinate S, voxel DISP coordinate S, image RAS ABS coordinate Z, or RAS DISP coordinate Z

=== Data Formats ===
||WARPFIELD_DTFMT_ABS_CRS   || CRS coordinates in image space ||
||WARPFIELD_DTFMT_DISP_CRS  || displacement CRS, delta = image_CRS - atlas_CRS ||
||WARPFIELD_DTFMT_ABS_RAS   || RAS coordinates in image space ||
||WARPFIELD_DTFMT_DISP_RAS  || displacement RAS, delta = image_RAS - atlas_RAS ||

=== MGZ to Nifti Conversion ===
The Freesurfer 3D morph MGZ files (MGZ_INTENT_WARPMAP) can be converted to Nifti with intent code NIFTI_INTENT_DISPVECT.

NIFTI_INTENT_DISPVECT has shape [5, c, r, s, 1, 3], and the displacement field vector is in RAS space. Freesurfer reads the 5th dimensions as extra frames in MRI struct.
-Line 87:
+Line 116:
-[[mri_convert]] [[lta_convert]]
+[[lta_convert]] (convert between different linear transform formats)

[[mri_concatenate_lta]] (concatenate or invert LTA transforms)

[[mri_concatenate_gcam]] (concatenate or invert warp fields)

[[mri_convert]] -at or -ait (apply transforms to an image)