Name

mri_concatenate_gcam

Description

Concatenates a combination of input LTAs (linear transform array) and GCAMs (Gaussian classifier atlas, M3Z).

The passed transforms are applied in the order specified on the command line, i.e. the first transform would be applied to images first - but to coordinates last, as transforms applied to coordinates are the inverse of those applied to images.

Note that binaries such as mri_convert or mri_vol2vol ignore source and target geometries of M3Zs. To morph an image from or to a different space, the M3Z geometry needs to be changed first.

Synopsis

mri_concatenate_gcam [options] <input 1> ... <output>

Arguments

Positional Arguments

input	Combination of LTAs and M3Zs
output	Concatenated output transform, saved as an LTA or M3Z depending on the input transforms

Optional Flagged Arguments

Flag	Description
-s, --change-source <source image>	Change source image geometry of output M3Z, useful e.g. for GCAM inversion if the path of the original source volume changed; the warp is modified accordingly
-t, --change-target <target image>	Change destination image geometry of output M3Z; the warp is modified accordingly
-r, --reduce	Reduce output LTA to single LT
-i, --invert	Invert the output transform
-d, --downsample	Downsample output M3Z to spacing of 2; by default, the output spacing is that of the rightmost input M3Z

Outputs

output

Composite LTA or M3Z transform, depending on input

Examples

Example 1

Reduce and invert LTA:

mri_concatenate_gcam -r -i in.lta out.lta

Example 2

Concatenate transforms:

mri_concatenate_gcam in1.fslmat in2.m3z in3.m3z in4.lta out.m3z

Example 3

Change M3Z to reflect different source image geometry:

mri_concatenate_gcam -s norm.nii in.m3z out.m3z

Reporting Bugs

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

-  ⇤ ← Revision 1 as of 2026-02-10 12:01:28 → 
  Size: 4100
  Editor: LiamrSennott
  Comment:
+   ← Revision 4 as of 2026-02-10 16:32:06 → ⇥
  Size: 2344
  Editor: YujingHuang
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 4:
-mri_warp_convert
+mri_concatenate_gcam
 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.
+Concatenates a combination of input LTAs (linear transform array) and GCAMs (Gaussian classifier atlas, M3Z).

The passed transforms are applied in the order specified on the command line, i.e. the first transform would be applied to images first - but to coordinates last, as transforms applied to coordinates are the inverse of those applied to images.

Note that binaries such as mri_convert or mri_vol2vol ignore source and target geometries of M3Zs. To morph an image from or to a different space, the M3Z geometry needs to be changed first.
-Line 10:
+Line 14:
-mri_warp_convert <input-type> <output-type> [options]
+mri_concatenate_gcam [options] <input 1> ... <output>
-Line 13:
+Line 17:
-== 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 ||
+== Positional Arguments ==
|| input  || Combination of LTAs and M3Zs ||
|| output || Concatenated output transform, saved as an LTA or M3Z depending on the input transforms ||
-Line 36:
+Line 22:
-||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''' ||
||-s, --change-source <source image> || Change source image geometry of output M3Z, useful e.g. for GCAM inversion if the path of the original source volume changed; the warp is modified accordingly ||
||-t, --change-target <target image> || Change destination image geometry of output M3Z; the warp is modified accordingly ||
||-r, --reduce || Reduce output LTA to single LT ||
||-i, --invert || Invert the output transform ||
||-d, --downsample || Downsample output M3Z to spacing of 2; by default, the output spacing is that of the rightmost input M3Z ||
-Line 44:
+Line 29:
+== Outputs ==
||output || Composite LTA or M3Z transform, depending on input ||
-Line 47:
+Line 34:
-Convert FSL warp to M3Z (FreeSurfer):
+Reduce and invert LTA:
-Line 49:
+Line 36:
-mri_warp_convert --infsl fsl.nii.gz --outm3z out.m3z --insrcgeom src.nii.gz
+mri_concatenate_gcam -r -i in.lta out.lta
-Line 53:
+Line 40:
-Convert ITK warp (e.g. ANTs) to M3Z (FreeSurfer):
+Concatenate transforms:
-Line 55:
+Line 42:
-mri_warp_convert --initk itk.nii.gz --outm3z out.m3z --insrcgeom src.nii.gz
+mri_concatenate_gcam in1.fslmat in2.m3z in3.m3z in4.lta out.m3z
-Line 59:
+Line 46:
-Convert ANTS antsRegistrationSyN.sh or antsRegistrationSyNQuick.shboutput to M3Z (FreeSurfer):
+Change M3Z to reflect different source image geometry:
-Line 61:
+Line 48:
-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
+mri_concatenate_gcam -s norm.nii in.m3z out.m3z
-Line 80:
+Line 51:
-== 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]]
-Line 91:
+Line 54:
+= See Also =
[[lta_convert]] (convert between different linear transform formats)

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

[[mri_warp_convert]] (similar functionality for warp fields)

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