Programs · FSL
img2imgcoord
- Original
- FSL 6.0.7.23
- Command line
larmorx fsl img2imgcoord- Python
lx.fsl.img2imgcoord- 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
img2imgcoord maps coordinates from one image to another through a FLIRT matrix: voxels by
default, millimetres with -mm.
Command line
larmorx fsl img2imgcoord [options] <filename containing coordinates>Everything after larmorx fsl img2imgcoord is the original’s command line: the arguments of FSL 6.0.7.23’s img2imgcoord, 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 img2imgcoord ...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.
img2imgcoord's usage text, as the clean room prints it
Usage: img2imgcoord [options] <filename containing coordinates>
Options are:
-src <filename of source image>
-dest <filename of destination image>
-xfm <filename of affine transform (e.g. source2dest.mat)>
-warp <filename of warpfield (e.g. intermediate2dest_warp.nii.gz)>
-premat <filename of pre-warp affine transform (e.g. source2intermediate.mat)> (default=identity)
-vox (all coordinates in voxels - default)
-mm (all coordinates in mm)
-v (verbose)
-help
Notes:
(1) if '-' is used as coordinate filename then coordinates are read from standard input
(2) the first three options are compulsoryPython
lx.fsl.img2imgcoord(
coords: Any,
src: Any,
dest: Any,
*,
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 img2imgcoord: coords (N x 3, or a file of rows x y z) in src’s voxels (NIfTI’s), or millimetres with mm, mapped through xfm (FLIRT’s matrix from src to dest; the identity without one) to dest’s; 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 img2imgcoord accepts (crates/larmorx-fsl/src/cli/coords.rs) and the arguments of lx.fsl.img2imgcoord (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.
img2imgcoord option |
Python | Default | Notes |
|---|---|---|---|
<filename containing coordinates> |
coords |
- or no file: standard input (refused at a terminal, as FSL) |
|
-src, -dest |
src, dest |
||
-xfm, -premat |
xfm |
None |
FSL: “(default=identity)” |
-vox, -mm |
mm |
False |
voxels by defaultFSL: “(all coordinates in voxels - default)”FSL: “(all coordinates in mm)” |
-warp |
command line only | FNIRT’s warp fields: refused until FNIRT is ported | |
-v, -help, -flirt |
command line only | -flirt accepted and ignoredFSL: “(verbose)” |
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 img2imgcoord ...); lx.fsl.img2imgcoord 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.img2imgcoord 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), T1w.nii.gz (a synthetic head of 40 × 48 × 40 voxels of 4 mm), bold2t1.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
xyz = lx.fsl.img2imgcoord([[10, 20, 30]], "boldref.nii.gz", "T1w.nii.gz", xfm="bold2t1.mat")
xyz.shape # -> (1, 3)larmorx fsl img2imgcoord -src boldref.nii.gz -dest T1w.nii.gz -xfm bold2t1.mat coords.txtPorts
img2imgcoord 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. The
coordinate programs’ -warp (a FNIRT warp field) is refused until FNIRT is ported: an unreadable
file, or an image of other than three volumes, gives FSL’s messages and exit status 1, as FSL.
Matrices other than 4 × 4 where FSL would invert them beyond 4 × 4 are refused (FSL prints part
of its output, then aborts).
The replica’s record holds 11 cases of img2imgcoord: 7 identical to FSL, 4 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 img2imgcoord’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 img2imgcoord shares with the page’s other programs: