Programs · FSL

aff2rigid

aff2rigid is a script that turns FLIRT’s 12-parameter matrix from an image to standard space into a 6-parameter (rigid) one.

Original
FSL 6.0.7.23
Command line
larmorx fsl aff2rigid
Python
lx.fsl.aff2rigid
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

The rigid matrix keeps, in order of decreasing accuracy, the anterior commissure, the AC-PC line and the mid-sagittal plane.

Command line

text
larmorx fsl aff2rigid <input2standard mat> <output mat>

Everything after larmorx fsl aff2rigid is the original’s command line: the arguments of FSL 6.0.7.23’s aff2rigid, 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 aff2rigid ...

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.

aff2rigid's usage text, as the clean room prints it
text
Usage: aff2rigid <input2standard mat> <output mat>
 
       First argument is the FLIRT transform (12 DOF) from the input image to standard
       Second argument is the output matrix which will go from the input image to standard space (6 DOF)
          aligning the AC, the AC-PC line and the mid-sagittal plane (in order of decreasing accuracy)

Python

python
lx.fsl.aff2rigid(
    matrix: Any,
    *,
    n_threads: int = 1,
    implementation: ImplementationName = "auto",
    upstream_defects: UpstreamDefectsName = "fix",
) -> np.ndarray

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

FSL’s aff2rigid: the rigid (6-parameter) 4 x 4 matrix that keeps the anterior commissure, the AC-PC line and the mid-sagittal plane of the 12-parameter input-to-standard matrix (array or file). FSL 6.0.7.23’s script stops before writing it (FSL-81); the replica and the clean room compute it as the script defines it (upstream_defects="reproduce" fails as FSL).

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 aff2rigid accepts (crates/larmorx-fsl/src/cli/aff2rigid.rs) and the arguments of lx.fsl.aff2rigid (python/larmorx/fsl/flirt_more.py), whose defaults and descriptions are taken from it. Under each option, in grey, FSL’s own help for it.

aff2rigid arguments Python Default Notes
<input2standard mat> matrix FLIRT’s matrix from the image to standard space
<output mat> the result

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 aff2rigid ...) and are arguments of lx.fsl.aff2rigid. 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
upstream_defects="fix"
"fix" (default) or "reproduce": FSL’s defects corrected, or FSL’s behaviour (docs/api/fsl-flirt.md, “Defects of the original, corrected by default”). 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: T1w2MNI.mat (the identity as a 4 × 4 text matrix). The command lines run as python -m larmorx.

python
import larmorx as lx

rigid = lx.fsl.aff2rigid("T1w2MNI.mat")
rigid.shape  # -> (4, 4)
bash
larmorx fsl aff2rigid T1w2MNI.mat T1w2MNI_rigid.mat

Ports

aff2rigid 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

FSL 6.0.7.23’s script stops with a Python NameError under NumPy 2, before it writes the matrix (FSL-81). Both ports compute the matrix as the script defines it by default, and stop with FSL’s traceback with upstream_defects="reproduce"; the clean room’s matrix is identical to the replica’s. Each record holds 3 cases of aff2rigid: its usage, and two matrices (fMRIPrep’s initial one among them) on which the ports, with reproduce, stop as FSL 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 aff2rigid’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 aff2rigid shares with the page’s other programs: