Programs · FSL
flirt
flirt registers one image to another with an affine transform, with every cost function and boundary-based registration (BBR).
- Original
- FSL 6.0.7.23
- Command line
larmorx fsl flirt- Python
lx.fsl.flirt- 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
It finds a transform of 6, 7, 9 or 12 degrees of freedom, or
applies a given matrix (-applyxfm, -applyisoxfm), and writes the 4 × 4 matrix from the
input’s FSL millimetres to the reference’s (-omat) and, on request, the input resampled onto the
reference’s grid (-out).
Its schedules may use alignpaxes (the rotation between the two images’ principal axes, with the
centres of gravity aligned) and setoption paramsubset with any finite mask (its pseudo-inverse
by the SVD, as FSL’s); -debug writes FLIRT’s debug volumes (the pyramid, the weights and, with
-cost bbr, BBR’s debug volume).
Command line
larmorx fsl flirt [options] -in <inputvol> -ref <refvol> -out <outputvol>
larmorx fsl flirt [options] -in <inputvol> -ref <refvol> -omat <outputmatrix>
larmorx fsl flirt [options] -in <inputvol> -ref <refvol> -applyxfm -init <matrix> -out <outputvol>Everything after larmorx fsl flirt is the original’s command line: the arguments of FSL 6.0.7.23’s flirt, 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 flirt ...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.
flirt's usage text, as the clean room prints it
FLIRT version 6.0
Usage: flirt [options] -in <inputvol> -ref <refvol> -out <outputvol>
flirt [options] -in <inputvol> -ref <refvol> -omat <outputmatrix>
flirt [options] -in <inputvol> -ref <refvol> -applyxfm -init <matrix> -out <outputvol>
Available options are:
-in <inputvol> (no default)
-ref <refvol> (no default)
-init <matrix-filname> (input 4x4 affine matrix)
-omat <matrix-filename> (output in 4x4 ascii format)
-out, -o <outputvol> (default is none)
-datatype {char,short,int,float,double} (force output data type)
-cost {mutualinfo,corratio,normcorr,normmi,leastsq,labeldiff,bbr} (default is corratio)
-searchcost {mutualinfo,corratio,normcorr,normmi,leastsq,labeldiff,bbr} (default is corratio)
-usesqform (initialise using appropriate sform or qform)
-displayinit (display initial matrix)
-anglerep {quaternion,euler} (default is euler)
-interp {trilinear,nearestneighbour,sinc,spline} (final interpolation: def - trilinear)
-sincwidth <full-width in voxels> (default is 7)
-sincwindow {rectangular,hanning,blackman}
-bins <number of histogram bins> (default is 256)
-dof <number of transform dofs> (default is 12)
-noresample (do not change input sampling)
-forcescaling (force rescaling even for low-res images)
-minsampling <vox_dim> (set minimum voxel dimension for sampling (in mm))
-applyxfm (applies transform (no optimisation) - requires -init)
-applyisoxfm <scale> (as applyxfm but forces isotropic resampling)
-paddingsize <number of voxels> (for applyxfm: interpolates outside image by size)
-searchrx <min_angle> <max_angle> (angles in degrees: default is -90 90)
-searchry <min_angle> <max_angle> (angles in degrees: default is -90 90)
-searchrz <min_angle> <max_angle> (angles in degrees: default is -90 90)
-nosearch (sets all angular search ranges to 0 0)
-coarsesearch <delta_angle> (angle in degrees: default is 60)
-finesearch <delta_angle> (angle in degrees: default is 18)
-schedule <schedule-file> (replaces default schedule)
-refweight <volume> (use weights for reference volume)
-inweight <volume> (use weights for input volume)
-wmseg <volume> (white matter segmentation volume needed by BBR cost function)
-wmcoords <text matrix> (white matter boundary coordinates for BBR cost function)
-wmnorms <text matrix> (white matter boundary normals for BBR cost function)
-fieldmap <volume> (fieldmap image in rads/s - must be already registered to the reference image)
-fieldmapmask <volume> (mask for fieldmap image)
-pedir <index> (phase encode direction of EPI - 1/2/3=x/y/z & -1/-2/-3=-x/-y/-z)
-echospacing <value> (value of EPI echo spacing - units of seconds)
-bbrtype <value> (type of bbr cost function: signed [default], global_abs, local_abs)
-bbrslope <value> (value of bbr slope)
-setbackground <value> (use specified background value for points outside FOV)
-noclamp (do not use intensity clamping)
-noresampblur (do not use blurring on downsampling)
-2D (use 2D rigid body mode - ignores dof)
-verbose <num> (0 is least and default)
-v (same as -verbose 1)
-i (pauses at each stage: default is off)
-version (prints version number)
-helpPython
lx.fsl.flirt(
in_image: Any,
ref_image: Any,
*,
init: Any = None,
dof: int = 12,
cost: Cost = "corratio",
search_cost: Cost = "corratio",
bins: int = 256,
interp: Interpolation = "trilinear",
sinc_width: int = 7,
sinc_window: SincWindow = "hanning",
search_rx: tuple[float, float] = (-90.0, 90.0),
search_ry: tuple[float, float] = (-90.0, 90.0),
search_rz: tuple[float, float] = (-90.0, 90.0),
no_search: bool = False,
coarse_search: float = 60.0,
fine_search: float = 18.0,
schedule: str | os.PathLike[str] | None = None,
apply_xfm: bool = False,
apply_isoxfm: float | None = None,
use_sqform: bool = False,
out: bool = True,
datatype: DataType | None = None,
ref_weight: Any = None,
in_weight: Any = None,
wm_seg: Any = None,
wm_coords: Any = None,
wm_norms: Any = None,
fieldmap: Any = None,
fieldmap_mask: Any = None,
pe_dir: int | None = None,
echo_spacing: float = 0.0005,
bbr_type: BbrType = "signed",
bbr_slope: float = -0.5,
padding_size: float = 0.0,
background: float | None = None,
no_resample: bool = False,
no_clamp: bool = False,
no_resample_blur: bool = False,
force_scaling: bool = False,
min_sampling: float | None = None,
base_scale: float | None = None,
two_d: bool = False,
n_threads: int = 1,
implementation: ImplementationName = "auto",
upstream_defects: UpstreamDefectsName = "fix",
) -> FlirtResultWhere Cost is one of "corratio", "mutualinfo", "normcorr", "normmi", "leastsq", "labeldiff", "bbr", "woods"; Interpolation is one of "trilinear", "nearestneighbour", "sinc", "spline"; SincWindow is one of "rectangular", "hanning", "blackman"; DataType is one of "char", "short", "int", "float", "double"; BbrType is one of "signed", "global_abs", "local_abs"; ImplementationName is one of "auto", "replica", "clean-room", "original" (0.1.0rc1’s spelling of "clean-room"); UpstreamDefectsName is one of "fix", "reproduce".
Register in_image to ref_image (FSL’s flirt), or apply init with apply_xfm/apply_isoxfm.
Images are paths or lx.Image objects. init is a 4 × 4 matrix (an array or a .mat file),
schedule a schedule file. The result’s matrix maps the input’s FSL millimetres to the
reference’s, as -omat writes it; its image is the input on the reference’s grid (None
unless out); its stdout holds FLIRT’s verbose lines and a schedule’s print.
fMRIPrep’s boundary-based registration of a BOLD reference to the T1w (no FreeSurfer), with
FSL’s bbr.sch (in $FSLDIR/etc/flirtsch):
r = lx.fsl.flirt(
"boldref.nii.gz", "T1w_brain.nii.gz",
init="init.mat", cost="bbr", search_cost="bbr", dof=6, base_scale=1,
schedule="/path/to/fsl/etc/flirtsch/bbr.sch", wm_seg="wm_mask.nii.gz",
)
r.matrix # 4 x 4, input FSL mm -> reference FSL mm (as -omat writes it)
r.image # the BOLD reference on the T1w's gridIts result, FlirtResult, holds what flirt computed.
| Field | Type | What it holds |
|---|---|---|
matrix |
np.ndarray |
The 4 x 4 matrix from the input’s FSL millimetres to the reference’s, as -omat writes it. |
image |
Image | None |
The input resampled onto the reference’s grid; None unless out. |
stdout |
str |
FLIRT’s standard output: its verbose lines and a schedule’s print. |
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 flirt accepts (crates/larmorx-fsl/src/cli/flirt.rs) and the arguments of lx.fsl.flirt (python/larmorx/fsl/flirt.py), whose defaults and descriptions are taken from it. Under each option, in grey, FSL’s own help for it.
| FLIRT option | Python | Default | Notes |
|---|---|---|---|
-in, -ref |
in_image, ref_image |
paths or lx.ImageFSL: “(no default)” |
|
-out, -omat |
out=True (the image), the matrix always |
True |
returned in FlirtResult; -o is -outFSL: “(default is none)”FSL: “(output in 4x4 ascii format)” |
-init |
init |
None |
a 4 x 4 array or a .mat fileFSL: “(input 4x4 affine matrix)” |
-applyxfm, -applyisoxfm s |
apply_xfm=True, apply_isoxfm=s |
apply_xfm=False, apply_isoxfm=None |
need init (or use_sqform)FSL: “(applies transform (no optimisation) - requires -init)”FSL: “(as applyxfm but forces isotropic resampling)” |
-usesqform |
use_sqform |
False |
FSL: “(initialise using appropriate sform or qform)” |
-dof 6/7/9/12 |
dof |
12 |
FSL: “(default is 12)” |
-cost, -searchcost |
cost, search_cost |
cost="corratio", search_cost="corratio" |
corratio (default), mutualinfo, normmi, normcorr, leastsq, labeldiff, bbr, woodsFSL: “(default is corratio)” |
-bins |
bins |
256 |
256FSL: “(default is 256)” |
-interp |
interp |
"trilinear" |
trilinear, nearestneighbour, sinc, splineFSL: “(final interpolation: def - trilinear)” |
-sincwidth, -sincwindow |
sinc_width, sinc_window |
sinc_width=7, sinc_window="hanning" |
7, hanningFSL: “(default is 7)” |
-searchrx a b, -searchry a b, -searchrz a b, -nosearch |
search_rx, search_ry, search_rz, no_search |
search_rx=(-90.0, 90.0), search_ry=(-90.0, 90.0), search_rz=(-90.0, 90.0), no_search=False |
degreesFSL: “(angles in degrees: default is -90 90)”FSL: “(sets all angular search ranges to 0 0)” |
-coarsesearch, -finesearch |
coarse_search, fine_search |
coarse_search=60.0, fine_search=18.0 |
60, 18 degreesFSL: “(angle in degrees: default is 60)”FSL: “(angle in degrees: default is 18)” |
-schedule |
schedule |
None |
a schedule fileFSL: “(replaces default schedule)” |
-datatype |
datatype |
None |
char, short, int, float, doubleFSL: “(force output data type)” |
-refweight, -inweight |
ref_weight, in_weight |
ref_weight=None, in_weight=None |
FSL: “(use weights for reference volume)”FSL: “(use weights for input volume)” |
-wmseg, -wmcoords, -wmnorms |
wm_seg, wm_coords, wm_norms |
wm_seg=None, wm_coords=None, wm_norms=None |
BBR’s boundaryFSL: “(white matter segmentation volume needed by BBR cost function)”FSL: “(white matter boundary coordinates for BBR cost function)”FSL: “(white matter boundary normals for BBR cost function)” |
-fieldmap, -fieldmapmask, -pedir, -echospacing |
fieldmap, fieldmap_mask, pe_dir, echo_spacing |
fieldmap=None, fieldmap_mask=None, pe_dir=None, echo_spacing=0.0005 |
BBR with a field mapFSL: “(fieldmap image in rads/s - must be already registered to the reference image)”FSL: “(mask for fieldmap image)”FSL: “(phase encode direction of EPI - 1/2/3=x/y/z & -1/-2/-3=-x/-y/-z)”FSL: “(value of EPI echo spacing - units of seconds)” |
-bbrtype, -bbrslope |
bbr_type, bbr_slope |
bbr_type="signed", bbr_slope=-0.5 |
signed, global_abs, local_abs; −0.5FSL: “(type of bbr cost function: signed [default], global_abs, local_abs)”FSL: “(value of bbr slope)” |
-paddingsize, -setbackground |
padding_size, background |
padding_size=0.0, background=None |
FSL: “(for applyxfm: interpolates outside image by size)”FSL: “(use specified background value for points outside FOV)” |
-noresample, -noclamp, -noresampblur, -forcescaling |
no_resample, no_clamp, no_resample_blur, force_scaling |
no_resample=False, no_clamp=False, no_resample_blur=False, force_scaling=False |
FSL: “(do not change input sampling)”FSL: “(do not use intensity clamping)”FSL: “(do not use blurring on downsampling)”FSL: “(force rescaling even for low-res images)” |
-minsampling, -basescale |
min_sampling, base_scale |
min_sampling=None, base_scale=None |
FSL: “(set minimum voxel dimension for sampling (in mm))” |
-2D |
two_d |
False |
FSL: “(use 2D rigid body mode - ignores dof)” |
-v, -verbose, -printinit, -displayinit, -debugsave, -debug, -i, -help, -version, -anglerep, -applynonisoxfm, -nosave |
command line only | -anglerep quaternion since 2026-11-02FSL: “(same as -verbose 1)”FSL: “(0 is least and default)”FSL: “(display initial matrix)”FSL: “(pauses at each stage: default is off)”FSL: “(prints version number)”FSL: “(default is euler)” |
|
OMP_NUM_THREADS |
n_threads |
1 |
the results do not depend on it |
LARMORX_UPSTREAM_DEFECTS |
upstream_defects |
"fix" |
fix (default) or reproduce |
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 flirt ...) and are arguments of lx.fsl.flirt. 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); the results do 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: epi.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). The command lines run as python -m larmorx.
import larmorx as lx
# A default 12-dof registration.
r = lx.fsl.flirt("epi.nii.gz", "T1w.nii.gz")
r.matrix.shape # -> (4, 4)
# The same call, the clean room chosen, without the resampled image.
c = lx.fsl.flirt("epi.nii.gz", "T1w.nii.gz", out=False, implementation="clean-room")
c.image is None # -> Truelarmorx fsl flirt -in epi.nii.gz -ref T1w.nii.gz -omat epi2t1.mat -out epi2t1.nii.gzPorts
flirt 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 |
The replica’s record, against FSL 6.0.7.23 itself in its standard comparison, holds fMRIPrep’s
boundary-based calls in three of fMRIPrep’s runs (ds005040, ds003592, ds000228), bit-identical, their
matrices also identical as text to fMRIPrep’s own (its container’s FSL); every cost function,
search option, schedule FSL ships, -applyxfm 3D and 4D with every interpolation and data type,
the BBR variants and the command line’s errors. The clean room is within the thresholds in 239 of
its 240 compared cases, out of 339 (its record of 2026-11-07), which holds FLIRT’s fourteen
programs. The one it misses is a weighted woods registration (real/weights-woods): its matrix
passes, but its standard error holds FSL’s warning Woods is not implemented with cost function weighting where FSL’s has ended. fMRIPrep’s three boundary-based calls are within 0.0113 mm of
FSL’s matrices at the 95th percentile of the brain.
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 flirt’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 flirt shares with the page’s other programs: