Programs · FSL
applyxfm4D
applyxfm4D resamples each volume of a series onto a reference’s grid, through one matrix or one per volume.
- Original
- FSL 6.0.7.23
- Command line
larmorx fsl applyxfm4D- Python
lx.fsl.applyxfm4d- 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 matrices are one file (-singlematrix) or a directory of files named MAT_0000n,
MAT_nnnn (-fourdigit) or <prefix>nnnn (-userprefix). The interpolation is sinc (the
default), trilinear, nearest neighbour or spline, and the output keeps the input’s data type
(char, short, int, float, double).
Command line
larmorx fsl applyxfm4D <input volume> <ref volume> <output volume> <transformation matrix file/dir>Everything after larmorx fsl applyxfm4D is the original’s command line: the arguments of FSL 6.0.7.23’s applyxfm4D, 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 applyxfm4D ...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.
applyxfm4D's usage text, as the clean room prints it
Usage: applyxfm4D <input volume> <ref volume> <output volume> <transformation matrix file/dir>
--interp, -interp <nearestneighbour (or nn), trilinear, spline, sinc (default)>
--singlematrix, -singlematrix (flag option, do not provide an argument)
--fourdigit, -fourdigit (flag option, do not provide an argument)
--userprefix, -userprefix <prefix>Python
lx.fsl.applyxfm4d(
in_image: str | os.PathLike,
ref_image: str | os.PathLike,
out_image: str | os.PathLike,
transforms: str | os.PathLike,
*,
single_matrix: bool = False,
four_digit: bool = False,
user_prefix: str | None = None,
interp: Interp4D = "sinc",
three_d: bool = False,
n_threads: int = 1,
implementation: ImplementationName = "auto",
upstream_defects: UpstreamDefectsName = "fix",
) -> strWhere Interp4D is one of "sinc", "trilinear", "nearestneighbour", "spline"; 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 applyxfm4D: each volume of in_image resampled onto ref_image’s grid through transforms (one matrix file with single_matrix, else a directory of MAT_0000n files, MAT_000n with four_digit, <user_prefix>000n with user_prefix), written to out_image in the input’s data type (its extension chooses the format: .nii.gz, .nii, .hdr/.img; none: .nii.gz); three_d resamples one volume (-3D). Returns the path written.
The images and transforms are paths.
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 applyxfm4D accepts (crates/larmorx-fsl/src/cli/applyxfm4d.rs) and the arguments of lx.fsl.applyxfm4d (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.
applyxfm4D option |
Python | Default | Notes |
|---|---|---|---|
<input volume> <ref volume> <output volume> |
in_image, ref_image, out_image |
||
<transformation matrix file/dir> |
transforms |
a directory of MAT_0000n files, or one file with -singlematrix |
|
-singlematrix, --singlematrix |
single_matrix |
False |
one matrix for every volume |
-fourdigit, --fourdigit |
four_digit |
False |
the files named MAT_nnnn |
-userprefix, --userprefix |
user_prefix |
None |
the files named <prefix>nnnn |
-interp, --interp |
interp |
"sinc" |
sinc (default), trilinear, nearestneighbour (or nn), spline |
-3D, --3D, -3d, --3d |
three_d |
False |
one volume; with sinc, the rectangular kernel the program asks for (FSL-80) |
-v, --v, -verbose, --verbose |
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 applyxfm4D ...) and are arguments of lx.fsl.applyxfm4d. 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: bold.nii.gz (a synthetic series of 4 such heads), boldref.nii.gz (a synthetic head of 40 × 48 × 40 voxels of 4 mm), bold2ref.mat (the identity as a 4 × 4 text matrix). The command lines run as python -m larmorx.
import larmorx as lx
path = lx.fsl.applyxfm4d(
"bold.nii.gz", "boldref.nii.gz", "bold_on_ref.nii.gz", "bold2ref.mat", single_matrix=True
)larmorx fsl applyxfm4D bold.nii.gz boldref.nii.gz bold_on_ref.nii.gz bold2ref.mat -singlematrixPorts
applyxfm4D 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.7), on FLIRT’s shared resampling (no blur, as FSL). FSL’s defects are corrected
by default, and FSL’s behaviour comes with upstream_defects="reproduce":
- FSL-09: integer outputs are rounded to the nearest and clamped (FSL truncates).
- FSL-79: spline interpolation of an integer image is computed as for a float image (FSL keeps the spline’s coefficients and values in the image’s type); named where the output changes.
- FSL-80:
-3Dwith sinc uses the rectangular kernel of width 9 that the program asks for (FSL uses a blackman kernel of width 7); named where the output changes. - FSL-111: a uint8 image’s values are read as stored (FSL reads them as signed char, its
values 128 to 255 as
v − 256); named where a written value changes. - FSL-75: the background value of a volume 3 voxels wide is taken from the whole border.
- FSL-11: with
FSLOUTPUTTYPEunset, the images are written as.nii.gzand FSL-11 is named (FSL stops at its first image); command line only, as the Python function sets the type itself.
With a reference that has neither form, the output carries the input’s form through the first
matrix, as a registration’s -out does.
The replica’s record holds 25 cases of applyxfm4D: 19 identical to FSL, 6 where both refuse
alike. The clean room’s holds 25: 20 within its thresholds, 5 refused 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 applyxfm4D’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 applyxfm4D shares with the page’s other programs: