Name

mri_warp_convert

Description

Converts non-linear deformation 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 (Deprecated), data interpretation is either abs-ras or abs-crs as encoded in TAG_GCAMORPH_TYPE
--inmgzwarp <inwarp.mgz>	input Freesurfer 3D morph in MGZ format, data interpretation is either abs-crs, disp-crs, abs-ras, or disp-ras as encoded in TAG_GCAMORPH_META
--infsl <in.nii.gz>	input FSL warp (recommend to use with --insrcgeom), data interpretation is disp in FSL RAS
--inspm <y_rinput.nii>	input SPM warp (use with --insrcgeom). Use --inwarpformat <> to specify the data interpretation, 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 (Deprecated), data interpretation is either abs-ras or abs-crs as encoded in TAG_GCAMORPH_TYPE
--outmgzwarp <outwarp.mgz>	output Freesurfer 3D morph in MGZ format, data interpretation is either abs-crs, disp-crs, abs-ras, or disp-ras as encoded in TAG_GCAMORPH_META
--outfsl <out.nii.gz>	output FSL warp (not implemented)
--outlps, --outitk <out.nii.gz>	output LPS-to-LPS displacement field (e.g. ITK, ANTs), Nifti with intent code NIFTI_INTENT_VECTOR
--outras <out.nii.gz>	output RAS-to-RAS displacement field (e.g. NiftyReg), Nifti with intent code NIFTI_INTENT_VECTOR
--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 interpretation: abs-crs, disp-crs, abs-ras, or disp-ras (default is abs-crs). This option only works with '--inspm <>'.
--outwarpformat <format>	specify warp data interpretation: 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 warp from FSL to FreeSurfer:

mri_warp_convert --infsl fsl.nii.gz --outmgzwarp out.mgz --insrcgeom src.nii.gz

Example 2

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

mri_warp_convert --initk itk.nii.gz --outmgzwarp out.mgz --insrcgeom src.nii.gz

Example 3

Convert ANTS antsRegistrationSyN.sh or antsRegistrationSyNQuick.sh output to FreeSurfer warp:

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 --outmgzwarp out.mgz --insrcgeom targ.mgz

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

Example 4

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

mri_warp_convert --inmgzwarp in.mgz --outitk out.nii.gz

Freesurfer 3D Morph

Freesurfer supports 3D morph in both M3Z and MGZ file formats. The M3Z is deprecated. The following sections describe the MGZ file format Freesurfer 3D morph.

The MGZ files supporting four data interpretations follow Freesurfer MGZ format with intent MGZ_INTENT_WARPMAP and specific TAG attributes.

TAG Attributes

3D morph metadata:

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 Interpretations

The data interpretation is encoded in TAG attribute TAG_GCAMORPH_META.

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

Deformation Field Vector

The deformation field (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

Nifti Conversion

The Freesurfer 3D morph can be output as 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 (disp-ras). Freesurfer reads the 5th dimensions as extra frames in its MRI struct.

Reporting Bugs

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

-  ⇤ ← Revision 2 as of 2026-02-09 13:01:06 → 
  Size: 2657
  Editor: YujingHuang
  Comment:
+   ← Revision 27 as of 2026-02-19 14:36:44 → ⇥
  Size: 6991
  Editor: YujingHuang
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 7:
-mri_warp_convert converts non-linear deformation field warp file formats. Some formats may require you to pass an image if the geometry information is missing form the transform file.
+Converts non-linear deformation fields between different file formats. Some formats may require you to pass an image if the geometry information is missing from the transform file.
 Line 10:
-mri_warp_convert [options]
+mri_warp_convert <input-type> <output-type> [options]
 Line 13:
-Line 16:
+Line 15:
-|| Flag || Description||
||--inm3z <in.m3z> || input M3Z warp ||
||--inmgzwarp <inwarp.mgz> || input mgz warp (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 use with --insrcgeom), data format is either abs-ras (default) or abs-crs (use --inwarpformat to specify) ||
||--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 file with displacements in source-voxel space ||
+||'''Flag''' ||'''Description''' ||
||--inm3z <in.m3z> ||input [[#Freesurfer 3D Morph|Freesurfer 3D morph]] in M3Z format (Deprecated), data interpretation is either abs-ras or abs-crs as encoded in TAG_GCAMORPH_TYPE ||
||--inmgzwarp <inwarp.mgz> ||input [[#Freesurfer 3D Morph|Freesurfer 3D morph]] in MGZ format, data interpretation is either abs-crs, disp-crs, abs-ras, or disp-ras as encoded in TAG_GCAMORPH_META ||
||--infsl <in.nii.gz> ||input FSL warp (recommend to use with --insrcgeom), data interpretation is disp in FSL RAS ||
||--inspm <y_rinput.nii> ||input SPM warp (use with --insrcgeom). Use --inwarpformat <> to specify the data interpretation, 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 ||
 Line 26:
-|| Flag || Description||
||--outm3z <out.m3z> || output warp (M3Z Freesurfer format) ||
||--outmgzwarp <outwarp.mgz> || output mgz warp (Freesurfer 3D morph in mgz format) ||
||--outfsl <out.nii.gz> || output warp (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 file with displacements in source-voxel space ||
+||'''Flag''' ||'''Description''' ||
||--outm3z <out.m3z> ||output [[#Freesurfer 3D Morph|Freesurfer 3D morph]] in M3Z format (Deprecated), data interpretation is either abs-ras or abs-crs as encoded in TAG_GCAMORPH_TYPE ||
||--outmgzwarp <outwarp.mgz> ||output [[#Freesurfer 3D Morph|Freesurfer 3D morph]] in MGZ format, data interpretation is either abs-crs, disp-crs, abs-ras, or disp-ras as encoded in TAG_GCAMORPH_META ||
||--outfsl <out.nii.gz> ||output FSL warp (not implemented) ||
||--outlps, --outitk <out.nii.gz> ||output LPS-to-LPS displacement field (e.g. ITK, ANTs), Nifti with intent code NIFTI_INTENT_VECTOR ||
||--outras <out.nii.gz> ||output RAS-to-RAS displacement field (e.g. NiftyReg), Nifti with intent code NIFTI_INTENT_VECTOR ||
||--outvox <out.mgz> ||output displacement field in source-voxel space ||
-Line 35:
+Line 36:
-|| Flag || Description||
||-g or --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 or ---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 inwarp-format || specify warp data format: abs-crs, disp-crs, abs-ras, or disp-ras (default is abs-crs) ||
||--outwarpformat outwarp-format || specify warp data format: abs-crs, disp-crs, abs-ras, or disp-ras (default is abs-crs) ||
||--vg-thresh vgthresh || 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 interpretation: abs-crs, disp-crs, abs-ras, or disp-ras (default is abs-crs). This option only works with '--inspm <>'. ||
||--outwarpformat <format> ||specify warp data interpretation: 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 43:
+Line 45:
+= Examples =
== Example 1 ==
Convert warp from FSL to FreeSurfer:

{{{
mri_warp_convert --infsl fsl.nii.gz --outmgzwarp out.mgz --insrcgeom src.nii.gz
}}}
== Example 2 ==
Convert warp from ITK (e.g. ANTs) to FreeSurfer:

{{{
mri_warp_convert --initk itk.nii.gz --outmgzwarp out.mgz --insrcgeom src.nii.gz
}}}
== Example 3 ==
Convert ANTS antsRegistrationSyN.sh or antsRegistrationSyNQuick.sh output to FreeSurfer warp:

{{{
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 --outmgzwarp out.mgz --insrcgeom targ.mgz
}}}
Note that the insrcgeom is the target, not the mov; this is needed to work with --lta1-inv.

== Example 4 ==
Convert warp from FreeSurfer to ITK (e.g. ANTs):

{{{
mri_warp_convert --inmgzwarp in.mgz --outitk out.nii.gz
}}}

= Freesurfer 3D Morph =
Freesurfer supports 3D morph in both M3Z and MGZ file formats. The M3Z is deprecated. The following sections describe the MGZ file format Freesurfer 3D morph.

The MGZ files supporting four data interpretations follow Freesurfer MGZ format with intent MGZ_INTENT_WARPMAP and specific TAG attributes.
=== TAG Attributes ===
3D morph metadata:
||'''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 Interpretations ===
The data interpretation is encoded in TAG attribute TAG_GCAMORPH_META.
||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 ||

=== Deformation Field Vector ===
The deformation field (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

=== Nifti Conversion ===
The Freesurfer 3D morph can be output as 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 (disp-ras). Freesurfer reads the 5th dimensions as extra frames in its MRI struct.

= See Also =
[[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)