Differences between revisions 3 and 30 (spanning 27 versions)
⇤ ← Revision 3 as of 2026-02-09 23:22:19 →
Size: 4100
Editor: YujingHuang
Comment:
← Revision 30 as of 2026-02-20 17:20:42 → ⇥
Size: 7722
Editor: YujingHuang
Comment:
Deletions are marked like this. Additions are marked like this.
Line 7: Line 7:
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. This program 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.

The deformation field vector (width x height x depth x nframes) is indexed by atlas CRS with one frame for each dimension. The data interpretation at each voxel is one of the following:
||'''data interpretation''' || '''value at each voxel''' ||
||absolute CRS (abs-crs) || image CRS ||
||displacement CRS (disp-crs) || delta = image CRS - atlas CRS ||
||absolute RAS (abs-ras) || image RAS ||
||displacement RAS (disp-ras) || delta = image RAS - atlas RAS ||
||displacement LPS (disp-lps) || delta = image LPS - atlas LPS ||

Notes: 'image' refers to the source (moving) volume; 'atlas' refers to the target (fixed) volume.
Line 15: Line 25:
||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 ||		 ||'''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 displacement in FSL RAS (the implementation is not fully test) ||
||--inspm <y_rinput.nii> ||input SPM warp (use with --insrcgeom). Use --in-interp <> 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 (disp-lps) (e.g. ITK, ANTs) ||
||--inras <in.nii.gz> ||input RAS-to-RAS displacement field (disp-ras) (e.g. NiftyReg) ||
||--invox <in.mgz> ||input displacement field in source-voxel space (the implementation is not fully test) ||
Line 26: Line 36:
||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 ||		 ||'''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 ||
||--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 (the implementation is not fully test) ||
Line 36: Line 45:
||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 ||
||--in-interp <in-interp> ||specify input warp data interpretation: abs-crs, disp-crs, abs-ras, or disp-ras (default is abs-crs). This option only works with '--inspm <>'. ||
||--out-interp <out-interp> ||specify output 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 47: Line 57:
Convert FSL warp to M3Z (FreeSurfer): Convert warp from FSL to FreeSurfer:
Line 49: Line 60:
mri_warp_convert --infsl fsl.nii.gz --outm3z out.m3z --insrcgeom src.nii.gz mri_warp_convert --infsl fsl.nii.gz --outmgzwarp out.mgz --insrcgeom src.nii.gz
Line 51: Line 62:
== Example 2 ==
Convert warp from ITK (e.g. ANTs) to FreeSurfer:
Line 52: Line 65:
== Example 2 ==
Convert ITK warp (e.g. ANTs) to M3Z (FreeSurfer):
Line 55: Line 66:
mri_warp_convert --initk itk.nii.gz --outm3z out.m3z --insrcgeom src.nii.gz mri_warp_convert --initk itk.nii.gz --outmgzwarp out.mgz --insrcgeom src.nii.gz
Line 57: Line 68:
== Example 3 ==
Convert ANTS antsRegistrationSyN.sh or antsRegistrationSyNQuick.sh output to FreeSurfer warp:
Line 58: Line 71:
== Example 3 ==
Convert ANTS antsRegistrationSyN.sh or antsRegistrationSyNQuick.shboutput to M3Z (FreeSurfer):
Line 70: Line 81:
mri_warp_convert --lta1-inv ants.reg0GenericAffine.lta --initk ants.reg1Warp.nii.gz --outm3z out.m3z --insrcgeom targ.mgz mri_warp_convert --lta1-inv ants.reg0GenericAffine.lta --initk ants.reg1Warp.nii.gz --outmgzwarp out.mgz --insrcgeom targ.mgz
Line 72: Line 83:
* 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 75: Line 86:
Convert M3Z (FreeSurfer) to ITK warp (e.g. ANTs): Convert warp from FreeSurfer to ITK (e.g. ANTs):
Line 77: Line 89:
mri_warp_convert --inm3z in.m3z --outitk out.nii.gz mri_warp_convert --inmgzwarp in.mgz --outitk out.nii.gz
Line 80: Line 92:
== Example 5 ==
Convert M3Z (FreeSurfer) to mgz warp (FreeSurfer) in absolute CRS:
{{{
mri_warp_convert --inm3z in.m3z --outmgzwarp outwarp.mgz --outwarpformat abs-crs
}}}		 = Freesurfer 3D Morph =
Freesurfer supports 3D morph in both M3Z and MGZ file formats. The M3Z is deprecated. The following describes the MGZ file format Freesurfer 3D morph.

The MGZ file format Freesurfer 3D morph supporting four data interpretations follows the 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 Interpretations ===
The data interpretation is encoded in TAG attribute TAG_GCAMORPH_META.
||WARPFIELD_DTFMT_ABS_CRS || absolute image CRS ||
||WARPFIELD_DTFMT_DISP_CRS || displacement CRS, delta = image CRS - atlas CRS ||
||WARPFIELD_DTFMT_ABS_RAS || absolute image RAS ||
||WARPFIELD_DTFMT_DISP_RAS || displacement RAS, delta = image RAS - atlas RAS ||

=== Deformation Field Vector ===
The deformation field vector (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.
Line 87: Line 123:
[[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)

Index

Contents

  1. Name
  2. Description
  3. Synopsis
  4. Arguments
    1. Required Flagged Arguments
      1. Exactly one input is required
      2. Exactly one output is required
    2. Optional Flagged Arguments
  5. Examples
    1. Example 1
    2. Example 2
    3. Example 3
    4. Example 4
  6. Freesurfer 3D Morph
      1. TAG Attributes
      2. Data Interpretations
      3. Deformation Field Vector
      4. Nifti Conversion
  7. See Also
  8. Reporting Bugs

Name

mri_warp_convert

Description

This program 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.

The deformation field vector (width x height x depth x nframes) is indexed by atlas CRS with one frame for each dimension. The data interpretation at each voxel is one of the following:

data interpretation

value at each voxel

absolute CRS (abs-crs)

image CRS

displacement CRS (disp-crs)

delta = image CRS - atlas CRS

absolute RAS (abs-ras)

image RAS

displacement RAS (disp-ras)

delta = image RAS - atlas RAS

displacement LPS (disp-lps)

delta = image LPS - atlas LPS

Notes: 'image' refers to the source (moving) volume; 'atlas' refers to the target (fixed) volume.

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 displacement in FSL RAS (the implementation is not fully test)

--inspm <y_rinput.nii>

input SPM warp (use with --insrcgeom). Use --in-interp <> 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 (disp-lps) (e.g. ITK, ANTs)

--inras <in.nii.gz>

input RAS-to-RAS displacement field (disp-ras) (e.g. NiftyReg)

--invox <in.mgz>

input displacement field in source-voxel space (the implementation is not fully test)

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

--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 (the implementation is not fully test)

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

--in-interp <in-interp>

specify input warp data interpretation: abs-crs, disp-crs, abs-ras, or disp-ras (default is abs-crs). This option only works with '--inspm <>'.

--out-interp <out-interp>

specify output 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 describes the MGZ file format Freesurfer 3D morph.

The MGZ file format Freesurfer 3D morph supporting four data interpretations follows the 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 Interpretations

The data interpretation is encoded in TAG attribute TAG_GCAMORPH_META.

WARPFIELD_DTFMT_ABS_CRS

absolute image CRS

WARPFIELD_DTFMT_DISP_CRS

displacement CRS, delta = image CRS - atlas CRS

WARPFIELD_DTFMT_ABS_RAS

absolute image RAS

WARPFIELD_DTFMT_DISP_RAS

displacement RAS, delta = image RAS - atlas RAS

Deformation Field Vector

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

Reporting Bugs

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

mri_warp_convert (last edited 2026-02-20 17:20:42 by YujingHuang)