Programs · FSL

std2imgcoord

Original
FSL 6.0.7.23
Command line
larmorx fsl std2imgcoord
Python
lx.fsl.std2imgcoord
Ports
  • replica larmorx-nc FSL Licence: non-commercial use only experimental
  • clean room larmorx Apache-2.0 experimental
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

text
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):

text
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
text
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 compulsory

Python

python
lx.fsl.std2imgcoord(
    coords: Any,
    img: Any,
    std: Any = None,
    *,
    xfm: Any = None,
    vox: bool = False,
    n_threads: int = 1,
    implementation: ImplementationName = "auto",
) -> np.ndarray

Where 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 N
n_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-room
implementation="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.

python
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)
bash
larmorx fsl std2imgcoord -img boldref.nii.gz -std std.nii.gz -xfm bold2std.mat coords.txt

Ports

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-nc holds it (crates-nc/), under the FSL Licence’s terms, and larmorx runs it as a separate program, larmorx-nc fsl <program>, when larmorx-nc is installed (pip install larmorx-nc).
  • The clean room is written from specs/flirt.md by an implementer who never read FSL’s source or the replica. It is part of larmorx, 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: