Programs · FSL
pointflirt
pointflirt finds the affine matrix that maps one set of points onto another, in the least-squares sense.
- Original
- FSL 6.0.7.23
- Command line
larmorx fsl pointflirt- Python
lx.fsl.pointflirt- 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 points are in millimetres, or in voxels with --vox, scaled by the two
images’ voxel sizes. It warns when the points do not determine the matrix, and a file of exactly
three points is read with one point per column, as FSL reads it.
Command line
larmorx fsl pointflirt -i <invol coords> -r <refvol coords> -o <output matrix>
larmorx fsl pointflirt -i <invol coords> -r <refvol coords> -o <output matrix> --vox --invol=<input vol> --refvol=<ref vol>Everything after larmorx fsl pointflirt is the original’s command line: the arguments of FSL 6.0.7.23’s pointflirt, 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 pointflirt ...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.
pointflirt's usage text, as the clean room prints it
Part of FSL (ID: 2412.6-dirty)
pointflirt
Copyright(c) 2001, University of Oxford (Mark Jenkinson)
Usage:
pointflirt -i <invol coords> -r <refvol coords> -o <output matrix>
pointflirt -i <invol coords> -r <refvol coords> -o <output matrix> --vox --invol=<input vol> --refvol=<ref vol>
Compulsory arguments (You MUST set one or more of):
-i filename of input volume coordinates
-r filename of reference volume coordinates
Optional arguments (You may optionally specify one or more of):
-o,--out filename of affine matrix output
--vox use voxel coordinates, not mm, for input
--invol filename of input volume (needed for --vox option)
--refvol filename of reference volume (needed for --vox option)
-v,--verbose switch on diagnostic messages
-h,--help display this messagePython
lx.fsl.pointflirt(
in_points: Any,
ref_points: Any,
*,
in_image: Any = None,
ref_image: Any = None,
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 pointflirt: the affine 4 x 4 matrix that maps in_points onto ref_points (N x 3 arrays or text files, in mm; with in_image and ref_image, in voxels, scaled by their voxel sizes: --vox) in the least-squares sense.
The two sets hold as many points; in_image and ref_image are paths or lx.Image objects,
given both or neither.
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 pointflirt accepts (crates/larmorx-fsl/src/cli/pointflirt.rs) and the arguments of lx.fsl.pointflirt (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.
pointflirt option |
Python | Default | Notes |
|---|---|---|---|
-i, -r |
in_points, ref_points |
the input’s and the reference’s pointsFSL: “filename of input volume coordinates”FSL: “filename of reference volume coordinates” | |
-o, --out |
the result | FSL: “filename of affine matrix output” | |
--vox |
in_image, ref_image given |
in_image=None, ref_image=None |
voxel coordinates; needs --invol and --refvolFSL: “use voxel coordinates, not mm, for input” |
--invol, --refvol |
in_image, ref_image |
in_image=None, ref_image=None |
the images whose voxel sizes scale the pointsFSL: “filename of input volume (needed for --vox option)”FSL: “filename of reference volume (needed for --vox option)” |
-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 pointflirt ...); lx.fsl.pointflirt 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.pointflirt 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: in.txt (eight points in millimetres, one x y z per line), ref.txt (the same eight points moved by 2, −3 and 4 mm). The command lines run as python -m larmorx.
import larmorx as lx
# The second file holds the first's points moved by 2, -3 and 4 mm.
aff = lx.fsl.pointflirt("in.txt", "ref.txt")
aff[:3, 3].round(6).tolist() # -> [2.0, -3.0, 4.0]larmorx fsl pointflirt -i in.txt -r ref.txt -o in2ref.matPorts
pointflirt 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.6), with its transposition rule, --vox and the
nullspace warning. Two
coordinate files both empty or missing are refused in both modes (FSL-204: FSL crashes after
its Could not open matrix file lines): larmorx-nc: error: pointflirt: no points in the coordinate files (FSL-204), exit status 1, the clean room after -v’s headings, as FSL prints
them. The clean room reads a nan word as 0 (the fit of the points as read) and stops on an
overflow as FSL’s SVD does.
The replica’s record holds 14 cases of pointflirt: 7 identical to FSL, 6 where both refuse
alike, and 1 of FSL-204. The clean room’s holds 17: 8 within its thresholds, 7 refused alike, and
the 2 of FSL-204.
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 pointflirt’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 pointflirt shares with the page’s other programs: