Differences between revisions 1 and 4 (spanning 3 versions)
⇤ ← Revision 1 as of 2026-02-10 11:28:05 →
Size: 4100
Editor: LiamrSennott
Comment:
← Revision 4 as of 2026-02-10 18:34:15 → ⇥
Size: 5976
Editor: YujingHuang
Comment:
Deletions are marked like this. Additions are marked like this.
Line 4: Line 4:
mri_warp_convert lta_convert
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. Converts between different linear transform formats.

Some formats may require you to pass an image if the geometry information is missing from the transform file format.

Formats called "inverse" below transform coordinates from the space of the target image to the space of the source image.
Line 10: Line 14:
mri_warp_convert <input-type> <output-type> [options] lta_convert [options]
Line 15: Line 19:
||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''' ||
||--inlta <in.lta> || input transform of LTA type ||
||--infsl <in.fslmat> || input transform of FSL type ||
||--inmni <in.xfm> || input transform of MNI / XFM type ||
||--inreg <inreg.dat> || input transform of TK REG type (deprecated format) ||
||--inniftyreg, --inras <inniftyreg.dat> || input transform of NiftyReg type (inverse RAS2RAS)||
||--inniftyreg2d <inniftyreg2d.dat> || input transform of NiftyReg type for an image (2D) ||
||--initk, --inlps <initk.txt> || input ITK transform (inverse LPS2LPS). Convert ANTS .mat binary to ITK format with ConvertTransformFile (in ANTS). ||
||--invox <invox.txt> || input transform in source image space (inverse VOX2VOX) ||
Line 26: Line 30:
||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''' ||
||--outlta <out.lta> || output linear transform (LTA FreeSurfer format) ||
||--outfsl <out.mat> || output transform in FSL format (set FSLOUTPUTTYPE env var to, e.g., "NIFTI" or "ANALYZE" to determine type of flipping) ||
||--outmni <out.xfm> || output transform in mni/xfm format ||
||--outreg <reg.dat> || output transform in reg dat format ||
||--outniftyreg, --outras <outniftyreg.txt> || output transform in NiftyReg format (inverse RAS2RAS) ||
||--outitk, --outlps <outitk.txt> || output transform in ITK txt format (inverse LPS2LPS) ||
||--outvox <outvox.txt> || output transform in source image space (inverse VOX2VOX) ||
Line 36: Line 40:
||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 ||		 ||--invert || inverts transform ||
||--ltavox2vox || (with --ltaout) output type VOX2VOX (default RAS2RAS) ||
||--ltatkreg || (with --ltaout) output type REGISTER_DAT (default RAS2RAS) ||
Line 44: Line 44:
While LTA contains src and trg information, other file formats are missing this information and you need to explicitly pass it via --src and/or --trg.

You can also use this if you want to inform the transform to reslice your image differently (i.e. to modify the geometry information without changing RAS coordinates).

For TKREG/register.dat type matrices, src=mov and trg=ref/targ.
||--src || specify src image geometry (mov volume for TKREG/register.dat) ||
||--trg ||specify trg image geometry ||
||--subject || specify subject name (overrides if input has subject name defined). ||

=== LTA src/trg geometry options ===
LTA is converted to SCANNER_RAS to SCANNER_RAS. The source and/or target VOL_GEOM is changed depending upon the desired operation(s).

None of the operations will change the RAS2RAS matrix.
||--srcconform || conform src image geometry (COR standard). Will be done before inversion, if specified. ||
||--srcconform-dc || keep src image directional cosine ||
||--srcconform-min || conform src image geometry to min direction size ||
||--srcconform-size size_in_mm || conform src image geometry to the size given in mm ||
||--srcupsample N || upsample src image geometry by factor of N ||
||--srcdownsample N || downsample src image geometry by factor of N ||
||--trgconform || conform trg image geometry (COR standard). Will be done before inversion, if specified. ||
||--trgconform-dc || keep trg image directional cosine ||
||--trgconform-min || conform trg image geometry to min direction size ||
||--trgconform-size size_in_mm || conform trg image geometry to the size given in mm ||
||--trgupsample N || upsample trg image geometry by factor of N ||
||--trgdownsample N || downsample trg image geometry by factor of N ||
||--regheader || Same as --inlta identity.nofile (make lta from src and trg volumes) ||
Line 47: Line 73:
Convert FSL warp to M3Z (FreeSurfer): Convert FSL transform to LTA (FreeSurfer):
Line 49: Line 75:
mri_warp_convert --infsl fsl.nii.gz --outm3z out.m3z --insrcgeom src.nii.gz lta_convert --infsl fsl.mat --outlta my.lta --src src.nii --trg trg.nii
Line 51: Line 77:
Converts FSL matrix to FreeSurfer LTA, adding missing src and target geometry info (the images used when fsl.mat was created).
Line 53: Line 80:
Convert ITK warp (e.g. ANTs) to M3Z (FreeSurfer): Convert ANTS/ITK transform to LTA (FreeSurfer):

First convert the ANTS binary mat file to ITK text file format and then to lta (adding src and trg geometry info, from images that were used to create the transform in ANTS):
Line 55: Line 84:
mri_warp_convert --initk itk.nii.gz --outm3z out.m3z --insrcgeom src.nii.gz $ANTSPATH/ConvertTransformFile 3 3D_antsAffine.mat 3D_antsAffine.txt
}}}
{{{
lta_convert --initk 3D_antsAffine.txt --outlta 3D_antsAffine.lta --src nsrc.nii --trg trg.nii
Line 59: Line 91:
Convert ANTS antsRegistrationSyN.sh or antsRegistrationSyNQuick.shboutput to M3Z (FreeSurfer): Invert transform:
Line 61: Line 93:
antsRegistrationSyNQuick.sh -d 3 -m mov.mgz -f targ.mgz -o reg. lta_convert --inlta in.lta --outlta out-inverse.lta --invert
}}}
Reads in.lta, inverts it and saves it as out-inverse.lta

== Example 4 ==
Conform target geometry:
{{{
lta_convert --inlta in.lta --outlta out-conform.lta --trgconform
}}}
Reads in.lta, conforms trg geometry and saves it as out-conform.lta

== Example 5 ==
Create transform from header geometries only:
{{{
lta_convert --regheader --src src.nii --trg trg.nii --outlta out.lta
Line 64: Line 110:
ConvertTransformFile 3 ants.reg0GenericAffine.mat ants.reg0GenericAffine.txt --hm --ras lta_convert --inlta identity.nofile --src src.nii --trg trg.nii --outlta out.lta
Line 66: Line 112:
{{{
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.		 Creates LTA from SRC and TRG header geometies, e.g. to convert SPM results to LTA (SPM stores its transforms in the header).
Line 74: Line 114:
== 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
}}}		 Similarly you can create a lta for conform reslicing when specifying --trgconform instead of --trg trg.nii.
Line 87: Line 117:
[[mri_convert]] [[lta_convert]] [[mri_warp_convert]] (convert non-linear deformation warp fields between different file 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
      1. LTA src/trg geometry options
  5. Examples
    1. Example 1
    2. Example 2
    3. Example 3
    4. Example 4
    5. Example 5
  6. See Also
  7. Reporting Bugs

Name

lta_convert

Description

Converts between different linear transform formats.

Some formats may require you to pass an image if the geometry information is missing from the transform file format.

Formats called "inverse" below transform coordinates from the space of the target image to the space of the source image.

Synopsis

lta_convert [options]

Arguments

Required Flagged Arguments

Exactly one input is required

Flag

Description

--inlta <in.lta>

input transform of LTA type

--infsl <in.fslmat>

input transform of FSL type

--inmni <in.xfm>

input transform of MNI / XFM type

--inreg <inreg.dat>

input transform of TK REG type (deprecated format)

--inniftyreg, --inras <inniftyreg.dat>

input transform of NiftyReg type (inverse RAS2RAS)

--inniftyreg2d <inniftyreg2d.dat>

input transform of NiftyReg type for an image (2D)

--initk, --inlps <initk.txt>

input ITK transform (inverse LPS2LPS). Convert ANTS .mat binary to ITK format with ConvertTransformFile (in ANTS).

--invox <invox.txt>

input transform in source image space (inverse VOX2VOX)

Exactly one output is required

Flag

Description

--outlta <out.lta>

output linear transform (LTA FreeSurfer format)

--outfsl <out.mat>

output transform in FSL format (set FSLOUTPUTTYPE env var to, e.g., "NIFTI" or "ANALYZE" to determine type of flipping)

--outmni <out.xfm>

output transform in mni/xfm format

--outreg <reg.dat>

output transform in reg dat format

--outniftyreg, --outras <outniftyreg.txt>

output transform in NiftyReg format (inverse RAS2RAS)

--outitk, --outlps <outitk.txt>

output transform in ITK txt format (inverse LPS2LPS)

--outvox <outvox.txt>

output transform in source image space (inverse VOX2VOX)

Optional Flagged Arguments

--invert

inverts transform

--ltavox2vox

(with --ltaout) output type VOX2VOX (default RAS2RAS)

--ltatkreg

(with --ltaout) output type REGISTER_DAT (default RAS2RAS)

While LTA contains src and trg information, other file formats are missing this information and you need to explicitly pass it via --src and/or --trg.

You can also use this if you want to inform the transform to reslice your image differently (i.e. to modify the geometry information without changing RAS coordinates).

For TKREG/register.dat type matrices, src=mov and trg=ref/targ.

--src

specify src image geometry (mov volume for TKREG/register.dat)

--trg

specify trg image geometry

--subject

specify subject name (overrides if input has subject name defined).

LTA src/trg geometry options

LTA is converted to SCANNER_RAS to SCANNER_RAS. The source and/or target VOL_GEOM is changed depending upon the desired operation(s).

None of the operations will change the RAS2RAS matrix.

--srcconform

conform src image geometry (COR standard). Will be done before inversion, if specified.

--srcconform-dc

keep src image directional cosine

--srcconform-min

conform src image geometry to min direction size

--srcconform-size size_in_mm

conform src image geometry to the size given in mm

--srcupsample N

upsample src image geometry by factor of N

--srcdownsample N

downsample src image geometry by factor of N

--trgconform

conform trg image geometry (COR standard). Will be done before inversion, if specified.

--trgconform-dc

keep trg image directional cosine

--trgconform-min

conform trg image geometry to min direction size

--trgconform-size size_in_mm

conform trg image geometry to the size given in mm

--trgupsample N

upsample trg image geometry by factor of N

--trgdownsample N

downsample trg image geometry by factor of N

--regheader

Same as --inlta identity.nofile (make lta from src and trg volumes)

Examples

Example 1

Convert FSL transform to LTA (FreeSurfer): 

lta_convert --infsl fsl.mat --outlta my.lta --src src.nii --trg trg.nii

Converts FSL matrix to FreeSurfer LTA, adding missing src and target geometry info (the images used when fsl.mat was created).

Example 2

Convert ANTS/ITK transform to LTA (FreeSurfer):

First convert the ANTS binary mat file to ITK text file format and then to lta (adding src and trg geometry info, from images that were used to create the transform in ANTS): 

$ANTSPATH/ConvertTransformFile 3 3D_antsAffine.mat 3D_antsAffine.txt

lta_convert --initk 3D_antsAffine.txt --outlta 3D_antsAffine.lta --src nsrc.nii --trg trg.nii

Example 3

Invert transform: 

lta_convert --inlta in.lta --outlta out-inverse.lta --invert

Reads in.lta, inverts it and saves it as out-inverse.lta

Example 4

Conform target geometry: 

lta_convert --inlta in.lta --outlta out-conform.lta --trgconform

Reads in.lta, conforms trg geometry and saves it as out-conform.lta

Example 5

Create transform from header geometries only: 

lta_convert --regheader --src src.nii --trg trg.nii --outlta out.lta

lta_convert --inlta identity.nofile --src src.nii --trg trg.nii --outlta out.lta

Creates LTA from SRC and TRG header geometies, e.g. to convert SPM results to LTA (SPM stores its transforms in the header).

Similarly you can create a lta for conform reslicing when specifying --trgconform instead of --trg trg.nii.

See Also

mri_warp_convert (convert non-linear deformation warp fields between different file 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 >

lta_convert (last edited 2026-02-10 18:34:15 by YujingHuang)