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), data format is either abs-ras (default) or abs-crs. use --inwarpformat <> to specify the data format.
--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

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 file with displacements 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.
-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

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.shboutput 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

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 3 as of 2026-02-09 23:22:19 → ⇥
  Size: 4100
  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 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.
 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 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), data format is either abs-ras (default) or abs-crs. use --inwarpformat <> to specify the data format. ||
||--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 ||
 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 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 file with displacements 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. ||
||-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 ||
-Line 43:
+Line 44:
+= 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.shboutput 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
}}}

= See Also =
[[mri_convert]] [[lta_convert]]