Programs · FSL
midtrans
midtrans finds the transform from a template space to the “middle” of several transforms into that space.
- Original
- FSL 6.0.7.23
- Command line
larmorx fsl midtrans- Python
lx.fsl.midtrans- 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
The middle is FSL’s Procrustes average of the transforms, about the MNI origin or about
the centre of gravity of a template image (--template). With --separate, each transform
composed with it is written too.
Command line
larmorx fsl midtrans [options] transform1 transform2 ... transformNEverything after larmorx fsl midtrans is the original’s command line: the arguments of FSL 6.0.7.23’s midtrans, 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 midtrans ...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.
midtrans's usage text, as the clean room prints it
Part of FSL (ID: 2412.6-dirty)
midtrans
Copyright(c) 2010, University of Oxford (Mark Jenkinson)
Usage:
midtrans [options] transform1 transform2 ... transformN
e.g. midtrans -o temp2mid.mat A2temp.mat B2temp.mat C2temp.mat
midtrans -o C2mid.mat A2C.mat B2C.mat ident.mat
Optional arguments (You may optionally specify one or more of):
-o,--out output filename for matrix
--template input filename for template image (needed for fix origin)
--separate basename for output of separate matrices (final name includes a number; e.g. img2mid0001.mat)
--debug switch on debugging output
-v,--verbose switch on diagnostic messages
-h,--help display this messagePython
lx.fsl.midtrans(
transforms: list[Any],
*,
template: Any = None,
separate: str | None = None,
n_threads: int = 1,
implementation: ImplementationName = "auto",
upstream_defects: UpstreamDefectsName = "fix",
) -> np.ndarrayWhere 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 midtrans: the 4 x 4 transform from the template space of transforms (4 x 4 arrays or files, at least two) to their “middle” (FSL’s Procrustes average about the MNI origin, or about the centre of gravity of template). With separate (a path prefix) each transform composed with it is also written to <separate>0001.mat and so on.
template is a path or an lx.Image.
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 midtrans accepts (crates/larmorx-fsl/src/cli/midtrans.rs) and the arguments of lx.fsl.midtrans (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.
midtrans option |
Python | Default | Notes |
|---|---|---|---|
transform1 transform2 ... |
transforms |
at least two | |
-o, --out |
the result | FSL: “output filename for matrix” | |
--template |
template |
None |
an image: the average about its centre of gravity (about the MNI origin without one)FSL: “input filename for template image (needed for fix origin)” |
--separate |
separate |
None |
a basename: each transform composed with the middle, written to <basename>0001.mat and onFSL: “basename for output of separate matrices (final name includes a number; e.g. img2mid0001.mat)” |
--debug, -v, --verbose, -h, --help |
command line only | -v and --debug print every stageFSL: “switch on debugging output”FSL: “switch on diagnostic messages”FSL: “display this message” |
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 midtrans ...) and are arguments of lx.fsl.midtrans. 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|reproduceupstream_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: A2temp.mat (the identity as a 4 × 4 text matrix), B2temp.mat (the identity as a 4 × 4 text matrix), C2temp.mat (the identity as a 4 × 4 text matrix). The command lines run as python -m larmorx.
import larmorx as lx
mid = lx.fsl.midtrans(["A2temp.mat", "B2temp.mat", "C2temp.mat"])
mid.shape # -> (4, 4)larmorx fsl midtrans -o temp2mid.mat A2temp.mat B2temp.mat C2temp.matPorts
midtrans 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 (specs/flirt.md §15.5), with every stage that -v and --debug print. An error after the
arguments exits with status 1 (FSL exits 0: FSL-78, corrected by default and named). The clean
room uses a transform whose determinant is not finite (FSL’s test is |det| < 1e-6), and refuses
transforms whose averages reach beyond double precision, such as a scale of 1e200 or a translation
of 1e300, with exit status 1 in both modes (FSL-241: FSL writes rows of NaN, or reports its
failed decomposition as a matrix-size error, and exits 0).
The replica’s record holds 12 cases of midtrans: 8 identical to FSL, 4 where both refuse alike.
The clean room’s holds 14: 8 within its thresholds, 4 refused alike, and the 2 of FSL-241.
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 midtrans’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 midtrans shares with the page’s other programs: