Programs · FSL

convert_xfm

convert_xfm is FLIRT’s matrix tool: it inverts a 4 × 4 matrix (-inverse), composes two (-concat) and gives a matrix another’s scales and skews (-fixscaleskew).

Original
FSL 6.0.7.23
Command line
larmorx fsl convert_xfm
Python
lx.fsl.convert_xfm
Ports
  • replica larmorx-nc FSL Licence: non-commercial use only experimental
  • clean room larmorx Apache-2.0 experimental
Evidence
every comparison with FSL
Source
made from docs/api/fsl-flirt.md and the code

What it does

It applies -fixscaleskew first, then -concat (that matrix times the input), then -inverse, and writes the result (-omat).

Command line

text
larmorx fsl convert_xfm [options] <input-matrix-filename>

Everything after larmorx fsl convert_xfm is the original’s command line: the arguments of FSL 6.0.7.23’s convert_xfm, as FSL takes them. LARMORX’s own options stand between larmorx and the family fsl, so they never meet the original’s (below):

text
larmorx
        [--n-threads N]
        [--implementation auto|replica|clean-room]
        [--upstream-defects fix|reproduce]
        fsl convert_xfm ...

From the next release. In 0.1.0rc1, set the variables instead: OMP_NUM_THREADS, LARMORX_IMPLEMENTATION (original for the clean room) and LARMORX_UPSTREAM_DEFECTS.

convert_xfm's usage text, as the clean room prints it
text
convert_xfm (Version 2.1)
Tool for manipulating FSL transformation matrices
Copyright(c) 1999-2007, University of Oxford (Mark Jenkinson)

Usage: convert_xfm [options] <input-matrix-filename>
  e.g. convert_xfm -omat <outmat> -inverse <inmat>
       convert_xfm -omat <outmat_AtoC> -concat <mat_BtoC> <mat_AtoB>

  Available options are:
        -omat <matrix-filename>            (4x4 ascii format)
        -concat <second-matrix-filename>
        -fixscaleskew <second-matrix-filename>
        -inverse                           (Reference image must be the one originally used)
        -help

Python

python
lx.fsl.convert_xfm(
    matrix: Any,
    *,
    concat: Any = None,
    fix_scale_skew: Any = None,
    inverse: bool = False,
    n_threads: int = 1,
    implementation: ImplementationName = "auto",
) -> np.ndarray

Where ImplementationName is one of "auto", "replica", "clean-room", "original" (0.1.0rc1’s spelling of "clean-room").

FSL’s convert_xfm: matrix (4 x 4 array or file) with fix_scale_skew’s scales and skews, then concat @ matrix, then inverted; returned as a 4 x 4 array (as FSL writes it: 10 significant digits).

Options

Each row joins an option of the original’s command line with the Python argument that does the same. The rows are checked against the code at every test run: the options convert_xfm accepts (crates/larmorx-fsl/src/cli/convert_xfm.rs) and the arguments of lx.fsl.convert_xfm (python/larmorx/fsl/flirt.py), whose defaults and descriptions are taken from it. Under each option, in grey, FSL’s own help for it.

convert_xfm option Python Default Notes
<input-matrix-filename> matrix a 4 × 4 array or a matrix file
-omat the result FSL: “(4x4 ascii format)”
-concat concat None
-fixscaleskew fix_scale_skew None
-inverse inverse=True False FSL: “(Reference image must be the one originally used)”
-v, -verbose, -help command line only

LARMORX’s own options

From the next release. In 0.1.0rc1, set the variables instead: OMP_NUM_THREADS, LARMORX_IMPLEMENTATION (original for the clean room) and LARMORX_UPSTREAM_DEFECTS.

They stand between larmorx and fsl on the command line (larmorx --n-threads 4 fsl convert_xfm ...); lx.fsl.convert_xfm takes n_threads and implementation as arguments, and the other is the command line’s only. Each one given wins over its environment variable, which keeps working.

Command line, then Python What it does
--n-threads N
n_threads=1
Threads (0 = all), given to the program as OMP_NUM_THREADS; the result does not depend on it. Default: every logical CPU on the command line (0), 1 in Python. The variable OMP_NUM_THREADS in 0.1.0rc1.
--implementation auto|replica|clean-room
implementation="auto"
"auto" (default): the replica when larmorx-nc is installed, else the clean room; "replica" or "clean-room" ("original", 0.1.0rc1’s spelling, still works). The variable LARMORX_IMPLEMENTATION in 0.1.0rc1.
--upstream-defects fix|reproduce
(no Python argument)
The command line’s only: lx.fsl.convert_xfm takes no upstream_defects. The variable LARMORX_UPSTREAM_DEFECTS in 0.1.0rc1.

Examples

The tests run every example below (validation/tests/test_reference.py), each section in a new folder where these inputs are made first: epi2t1.mat (the identity as a 4 × 4 text matrix). The command lines run as python -m larmorx.

python
import larmorx as lx

# The inverse of a FLIRT matrix.
inv = lx.fsl.convert_xfm("epi2t1.mat", inverse=True)
inv.shape  # -> (4, 4)
bash
larmorx fsl convert_xfm -omat t12epi.mat -inverse epi2t1.mat

Ports

convert_xfm has two ports: a replica and a clean room.

Port Package Licence Status Records
replica larmorx-nc FSL Licence: non-commercial use only experimental fsl-flirt-replica
clean room larmorx Apache-2.0 experimental fsl-flirt

Both ports are complete. The replica is translated from FSL 6.0.7.23’s source, giving FSL’s results byte for byte. In the clean room, convert_xfm’s messages are FSL’s, and -fixscaleskew aborts where its decomposition does not solve (a zero scale or a non-finite entry), as avscale does.

FSL’s licence allows non-commercial use only, so each of FLIRT’s programs has two ports, a replica and a clean room, in different packages (licensing says what each package holds):

  • The replica is translated from FSL’s source. The package larmorx-nc holds it (crates-nc/), under the FSL Licence’s terms, and larmorx runs it as a separate program, larmorx-nc fsl <program>, when larmorx-nc is installed (pip install larmorx-nc).
  • The clean room is written from specs/flirt.md by an implementer who never read FSL’s source or the replica. It is part of larmorx, under Apache-2.0 (crates/larmorx-fsl, with its PROVENANCE, section “FLIRT”), and runs on LARMORX’s clean-room registration engine, the head-motion correction’s (lx.mri.hmc).

implementation="auto" runs the replica when larmorx-nc is installed, and the clean room otherwise. "replica" and "clean-room" choose one ("original", 0.1.0rc1’s spelling of "clean-room", still works); "clean-room" runs the clean room in this process. On the command line, --implementation auto|replica|clean-room before the family chooses alike, from the next release; in 0.1.0rc1 the variable LARMORX_IMPLEMENTATION chooses (original for the clean room).

Evidence

How each of convert_xfm’s ports was measured against FSL, case by case: its evidence.

More in the repository

The API page docs/api/fsl-flirt.md holds what convert_xfm shares with the page’s other programs: