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

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

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

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

Python

python
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",
) -> FlirtResult

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

python
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 grid

Its 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 N
n_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-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
upstream_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.

python
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  # -> True
bash
larmorx fsl flirt -in epi.nii.gz -ref T1w.nii.gz -omat epi2t1.mat -out epi2t1.nii.gz

Ports

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