Programs · FSL
makerot
- Original
- FSL 6.0.7.23
- Command line
larmorx fsl makerot- Python
lx.fsl.makerot- 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
makerot writes the 4 × 4 matrix of a rotation by theta degrees about an axis through a centre
(or through the centre of an image).
Command line
larmorx fsl makerot [options] --theta=angleEverything after larmorx fsl makerot is the original’s command line: the arguments of FSL 6.0.7.23’s makerot, 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 makerot ...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.
makerot's usage text, as the clean room prints it
Part of FSL (ID: 2412.6-dirty)
makerot
Copyright(c) 2003, University of Oxford (Mark Jenkinson)
Usage:
makerot [options] --theta=angle
Compulsory arguments (You MUST set one or more of):
-t,--theta angle of rotation (in degrees)
Optional arguments (You may optionally specify one or more of):
-a,--axis <ax,ay,az> unnormalised axis vector (comma separated)
--cov image filename used for centre of volume
-c,--centre <cx,cy,cz> centre of rotation in mm (comma separated)
-o,--out output filename for matrix
-v,--verbose switch on diagnostic messages
-h,--help display this messagePython
lx.fsl.makerot(
theta: float,
axis: Any = None,
centre: Any = None,
*,
cov: Any = None,
n_threads: int = 1,
upstream_defects: UpstreamDefectsName = "fix",
implementation: ImplementationName = "auto",
) -> np.ndarrayWhere UpstreamDefectsName is one of "fix", "reproduce"; ImplementationName is one of "auto", "replica", "clean-room", "original" (0.1.0rc1’s spelling of "clean-room").
FSL’s makerot: the 4 x 4 matrix of a rotation by theta degrees about axis (three values of any length, z by default) through centre (mm, the origin by default), or through the centre of the image cov (half its extent in mm). The axis is divided by its length (FSL divides by the square root of it, FSL-76; upstream_defects="reproduce" gives FSL’s matrix); an axis or centre of other than three values is an error here (FSL-77 is about the command line, where one word holds them).
The result is a 4 × 4 array.
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 makerot accepts (crates/larmorx-fsl/src/cli/makerot.rs) and the arguments of lx.fsl.makerot (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.
makerot option |
Python | Default | Notes |
|---|---|---|---|
-t, --theta |
theta |
degreesFSL: “angle of rotation (in degrees)” | |
-a, --axis |
axis |
None |
three values; divided by its length (FSL by its square root: FSL-76, corrected by default)FSL: “unnormalised axis vector (comma separated)” |
-c, --centre |
centre |
None |
three valuesFSL: “centre of rotation in mm (comma separated)” |
--cov |
cov |
None |
an image: the rotation’s centre is its centreFSL: “image filename used for centre of volume” |
-o, --out |
the result | FSL: “output filename for matrix” | |
-v, --verbose, -h, --help |
command line only | 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 makerot ...) and are arguments of lx.fsl.makerot. 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. The command lines run as python -m larmorx.
import larmorx as lx
r = lx.fsl.makerot(30, axis=(1, 2, 3), centre=(4, 5, 6))
r.shape # -> (4, 4)larmorx fsl makerot -t 30 -a 1,2,3 -c 4,5,6 -o rot.matPorts
makerot 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.4): FSL-76 corrected by default (FSL’s matrix with
reproduce, named), FSL-77 refused by default (FSL’s reading with reproduce, named in both
modes). Where FSL aborts, they print the same lines and exit with status 1.
The replica’s record holds 14 cases of makerot: 8 identical to FSL, 6 where both refuse or abort
alike. The clean room’s holds 14: 8 identical to FSL in every byte of text and file, 6 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 makerot’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 makerot shares with the page’s other programs: