Programs · FSL
std2imgcoord
- Original
- FSL 6.0.7.23
- Command line
larmorx fsl std2imgcoord- Python
lx.fsl.std2imgcoord- 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
std2imgcoord maps coordinates from a standard image to an image through the inverse of a FLIRT
matrix: millimetres by default, the image’s voxels with -vox.
Command line
larmorx fsl std2imgcoord [options] <filename containing coordinates>Everything after larmorx fsl std2imgcoord is the original’s command line: the arguments of FSL 6.0.7.23’s std2imgcoord, 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 std2imgcoord ...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.
std2imgcoord's usage text, as the clean room prints it
Usage: std2imgcoord [options] <filename containing coordinates>
e.g. std2imgcoord -img <invol> -std <standard image> -xfm <img2standard mat file> <coordinate file>
std2imgcoord -img <invol> -std <standard image> <coordinate file>
std2imgcoord -img <invol> -std <standard image> -
Options are:
-std <filename of standard image>
-img <filename of input 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)
-mm (outputs coordinates in mm - default)
-vox (outputs coordinates in voxels)
-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.std2imgcoord(
coords: Any,
img: Any,
std: Any = None,
*,
xfm: Any = None,
vox: 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 std2imgcoord: coords (N x 3, or a file) in std’s millimetres (its sform or qform; without std, the voxel sizes of a 1 mm grid) mapped through the inverse of xfm (FLIRT’s matrix from img to std) to img’s millimetres, or its NIfTI voxels with vox; 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 std2imgcoord accepts (crates/larmorx-fsl/src/cli/coords.rs) and the arguments of lx.fsl.std2imgcoord (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.
std2imgcoord 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 |
the matrix invertedFSL: “(default=identity)” |
-mm, -vox |
vox |
False |
millimetres by defaultFSL: “(outputs coordinates in mm - default)”FSL: “(outputs coordinates in voxels)” |
-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 std2imgcoord ...); lx.fsl.std2imgcoord 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.std2imgcoord 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: boldref.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), bold2std.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
ijk = lx.fsl.std2imgcoord([[0, 0, 0]], "boldref.nii.gz", "std.nii.gz", xfm="bold2std.mat", vox=True)
ijk.shape # -> (1, 3)larmorx fsl std2imgcoord -img boldref.nii.gz -std std.nii.gz -xfm bold2std.mat coords.txtPorts
std2imgcoord 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): there the list also ends at a coordinate equal to the one before it,
which is not printed. 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 13 cases of std2imgcoord: 8 identical to FSL, 5 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 std2imgcoord’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 std2imgcoord shares with the page’s other programs: