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-ncFSL Licence: non-commercial use only experimental - clean room
larmorxApache-2.0 experimental
- replica
- 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
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):
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
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)
-helpPython
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.ndarrayWhere 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 Nn_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-roomimplementation="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.
import larmorx as lx
# The inverse of a FLIRT matrix.
inv = lx.fsl.convert_xfm("epi2t1.mat", inverse=True)
inv.shape # -> (4, 4)larmorx fsl convert_xfm -omat t12epi.mat -inverse epi2t1.matPorts
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-ncholds it (crates-nc/), under the FSL Licence’s terms, andlarmorxruns it as a separate program,larmorx-nc fsl <program>, whenlarmorx-ncis installed (pip install larmorx-nc). - The clean room is written from
specs/flirt.mdby an implementer who never read FSL’s source or the replica. It is part oflarmorx, 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: