Programs · FSL
img2stdcoord
- Original
- FSL 6.0.7.23
- Command line
larmorx fsl img2stdcoord- Python
lx.fsl.img2stdcoord- 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
img2stdcoord maps coordinates from an image to a standard image through a FLIRT matrix: input
voxels by default, output in the standard image’s millimetres.
Command line
larmorx fsl img2stdcoord [options] <filename containing coordinates>Everything after larmorx fsl img2stdcoord is the original’s command line: the arguments of FSL 6.0.7.23’s img2stdcoord, 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 img2stdcoord ...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.
img2stdcoord's usage text, as the clean room prints it
Usage: img2stdcoord [options] <filename containing coordinates>
e.g. img2stdcoord -img <invol> -std <standard image> -xfm <img2standard mat file> <coordinate file>
img2stdcoord -img <invol> <coordinate file>
img2stdcoord -img <invol> -
Options are:
-img <filename of input image>
-std <filename of standard image>
-xfm <filename of affine transform (e.g. example_func2standard.mat)>
-warp <filename of warpfield (e.g. highres2standard_warp.nii.gz)>
-premat <filename of pre-warp affine transform (e.g. example_func2highres.mat)> (default=identity)
-vox (input coordinates in voxels - default)
-mm (input coordinates in mm)
-v (verbose output)
-verbose (more verbose output)
-help
Notes:
(1) if '-' is used as coordinate filename then coordinates are read from standard input
(2) the -img option is compulsoryPython
lx.fsl.img2stdcoord(
coords: Any,
img: Any,
std: Any = None,
*,
xfm: Any = None,
mm: bool = False,
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 img2stdcoord: coords (N x 3, or a file) in img’s NIfTI voxels, or its millimetres with mm, mapped through xfm (FLIRT’s matrix from img to std) to std’s millimetres; returned as N x 3.
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 img2stdcoord accepts (crates/larmorx-fsl/src/cli/coords.rs) and the arguments of lx.fsl.img2stdcoord (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.
img2stdcoord option |
Python | Default | Notes |
|---|---|---|---|
<filename containing coordinates> |
coords |
- or no file: standard input (refused at a terminal, as FSL) |
|
-img, -std |
img, std |
std=None |
|
-xfm, -premat |
xfm |
None |
FSL: “(default=identity)” |
-vox, -mm |
mm |
False |
input voxels by defaultFSL: “(input coordinates in voxels - default)”FSL: “(input coordinates in mm)” |
-warp |
command line only | FNIRT’s warp fields: refused until FNIRT is ported | |
-v, -verbose, -help, -flirt |
command line only | -flirt gives FSL’s warning about outdated optionsFSL: “(verbose output)”FSL: “(more verbose output)” |
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 img2stdcoord ...); lx.fsl.img2stdcoord 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.img2stdcoord 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: T1w.nii.gz (a synthetic head of 40 × 48 × 40 voxels of 4 mm), std.nii.gz (a synthetic head of 40 × 48 × 40 voxels of 4 mm), t1_to_std.mat (the identity as a 4 × 4 text matrix), coords.txt (two coordinates, one x y z per line). The command lines run as python -m larmorx.
import larmorx as lx
mm = lx.fsl.img2stdcoord([[10, 20, 30]], "T1w.nii.gz", "std.nii.gz", xfm="t1_to_std.mat")
mm.shape # -> (1, 3)larmorx fsl img2stdcoord -img T1w.nii.gz -std std.nii.gz -xfm t1_to_std.mat coords.txtPorts
img2stdcoord 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.2), standard input included (the prompts and the
refusal at a terminal). Where FSL aborts, they print the same lines and exit with status 1;
-warp is refused until FNIRT is ported.
The replica’s record holds 12 cases of img2stdcoord: 7 identical to FSL, 5 where both refuse or
abort alike. The clean room’s holds 12: 7 identical to FSL in every byte of text and file, 5
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 img2stdcoord’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 img2stdcoord shares with the page’s other programs: