Programs · FSL
avscale
avscale takes a FLIRT matrix apart: its rotation and translation, angles, scales, skews, determinant and half transforms.
- Original
- FSL 6.0.7.23
- Command line
larmorx fsl avscale- Python
lx.fsl.avscale- 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 angles and translations are about the volume’s centre of
gravity, the half transforms are the matrix’s square root, and the scales’ average and the
left-right order come with them; with --inverteddies it also prints the eddy-current
inversion’s matrices.
Command line
larmorx fsl avscale [--allparams/--inverteddies] matrixfile [non-reference-volume]Everything after larmorx fsl avscale is the original’s command line: the arguments of FSL 6.0.7.23’s avscale, 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 avscale ...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.
avscale's usage text, as the clean room prints it
Usage: avscale [--allparams/--inverteddies] matrixfile [non-reference-volume]Python
lx.fsl.avscale(
matrix: Any,
volume: Any = None,
*,
all_params: bool = False,
inverted_eddies: bool = False,
n_threads: int = 1,
implementation: ImplementationName = "auto",
) -> AvscaleResultWhere ImplementationName is one of "auto", "replica", "clean-room", "original" (0.1.0rc1’s spelling of "clean-room").
FSL’s avscale: matrix (4 x 4 array or file) decomposed, its translations about the centre of gravity of volume (a path or Image; the origin without one). all_params also returns the rotation angles and translations; inverted_eddies the eddy-current inversion (the two options are exclusive, as on the command line).
Its result, AvscaleResult, holds avscale’s decomposition of matrix (matrix = rotation * skew * scale), as it prints them (6 decimals, or 6 significant digits where FSL prints those).
| Field | Type | What it holds |
|---|---|---|
rotation_translation |
np.ndarray |
The rotation-and-translation matrix (4 x 4). |
rotations |
np.ndarray | None |
The rotation’s angles about x, y and z, in radians (all_params; else None). |
translations |
np.ndarray | None |
The translation about the centre of gravity of volume, or about the origin without one (all_params; else None). |
scales |
np.ndarray |
The scales along x, y and z. |
skews |
np.ndarray |
The skews. |
average_scale |
float |
The scales’ average. |
determinant |
float |
The matrix’s determinant. |
left_right_preserved |
bool |
Whether the left-right order is kept. |
forward_half |
np.ndarray |
The forward half transform (the matrix’s square root). |
backward_half |
np.ndarray |
The backward half transform. |
matrix_check |
np.ndarray | None |
The check matrix (inverted_eddies; else None). |
inverted_eddy |
np.ndarray | None |
The inverted eddy-current matrix (inverted_eddies; else None). |
stdout |
str |
The program’s text. |
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 avscale accepts (crates/larmorx-fsl/src/cli/avscale.rs) and the arguments of lx.fsl.avscale (python/larmorx/fsl/flirt_tools.py), whose defaults and descriptions are taken from it. Under each option, in grey, FSL’s own help for it.
avscale option |
Python | Default | Notes |
|---|---|---|---|
matrixfile [non-reference-volume] |
matrix, volume |
volume=None |
|
--allparams |
all_params=True |
False |
also the rotation angles and translations |
--inverteddies |
inverted_eddies=True |
False |
the eddy-current inversion; exclusive with --allparams |
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 avscale ...); lx.fsl.avscale 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.avscale 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: bold2t1.mat (the identity as a 4 × 4 text matrix), boldref.nii.gz (a synthetic head of 40 × 48 × 40 voxels of 4 mm). The command lines run as python -m larmorx.
import larmorx as lx
d = lx.fsl.avscale("bold2t1.mat", "boldref.nii.gz", all_params=True)
d.scales, d.rotations, d.determinant, d.forward_halflarmorx fsl avscale --allparams bold2t1.mat boldref.nii.gzPorts
avscale 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.1); where FSL aborts, they print the same lines and
exit with status 1. A matrix of 4 rows that is not 4 × 4, where FSL aborts at a determinant, an
inverse or a product, is refused (FSL prints part of its output first). One more matrix, from
random testing (a reflection’s --inverteddies check), differs in the sign of a 1e-10 residual.
The replica’s record holds 9 cases of avscale: 5 identical to FSL, 4 where both refuse or abort
alike. The clean room’s holds 9: 5 identical to FSL in every byte of text and file, 4 where both
refuse or abort alike.
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 avscale’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 avscale shares with the page’s other programs: