Programs · AFNI

3dvolreg

3dvolreg registers every volume of a series to a base volume with a rigid-body (6-parameter) transform.

Original
AFNI 26.3.05
Command line
larmorx afni 3dvolreg
Python
lx.afni.volreg
Ports
  • replica larmorx Apache-2.0 AND CC-BY-4.0 validated
  • clean room larmorx Apache-2.0 experimental
Evidence
every comparison with AFNI
Source
made from docs/api/afni-volreg.md and the code

What it does

fMRIPrep runs it for its BOLD reference (niworkflows’ RobustAverage: up to 20 volumes aligned before their median, -Fourier -twopass -zpad 4, once per run and per 4D sbref) and sdcflows’ PEPOLAR estimator for its reference averages.

Command line

text
larmorx afni 3dvolreg [options] dataset

Everything after larmorx afni 3dvolreg is the original’s command line: the arguments of AFNI 26.3.05’s 3dvolreg, as AFNI takes them. LARMORX’s own options stand between larmorx and the family afni, so they never meet the original’s (below):

text
larmorx
        [--n-threads N]
        [--implementation auto|replica|clean-room]
        [--upstream-defects fix|reproduce]
        afni 3dvolreg ...

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.

3dvolreg's usage text, as the clean room prints it
text
Usage: 3dvolreg [options] dataset   (larmorx: clean-room original of AFNI 26.3.05's 3dvolreg)

Registers each 3D sub-brick of the input dataset to the base brick (rigid body, 6
parameters), by iterated linearised weighted least squares, as AFNI's 3dvolreg does. The
dataset and the outputs are NIfTI files.

Options (before the dataset):
  -verbose             print progress reports (twice: lots of output)
  -Fourier -heptic -quintic -cubic -linear
                       interpolation for the estimation (default -heptic)
  -final mode          final interpolation: NN cubic quintic heptic Fourier linear
  -clipit / -noclip    clip each output to its input's range (default on)
  -zpad n              zero padding around the edges during rotations (default 4)
  -prefix fname        output (.nii or .nii.gz); NULL writes no dataset
  -float               write the output as float
  -base n | -base dset the n'th sub-brick of the input, or sub-brick 0 of another dataset
  -dfile f             save n, roll, pitch, yaw, dS, dL, dP, rmsold, rmsnew
  -1Dfile f            save roll, pitch, yaw, dS, dL, dP
  -1Dmatrix_save ff    save the base-to-input matrices (ff, or ff.aff12.1D)
  -rotcom              print the 3drotate fragments
  -maxdisp / -nomaxdisp  report the maximum displacement in the automask (default on)
  -maxdisp1D mm        also write it per sub-brick to mm (and its change to mm_delt)
  -savedisp sss        save the displacements of every voxel (sss_DX, sss_DY, sss_DZ)
  -maxite m  -x_thresh x  -rot_thresh r  -delta d  -params m x r d
  -weight 'wset[n]'    the weight brick
  -wtinp               sub-brick 0 of the input as the weight
  -edging ee | ee%     the weight's zeroed edge (default 5%, or AFNI_VOLREG_EDGING)
  -twopass  -twoblur bb  -sinit  -coarse del num  -coarserot  -nocoarserot
                       two passes: a coarse search on blurred bricks first
  -tshift ii           slice-time correct the input first (ignoring ii time points)
  -rotparent rset  -gridparent gset  -twodup
  -input dset / -source dset   the dataset, given as an option

AFNI's global options (anywhere on the command line):
  -overwrite      replace an existing output (AFNI_DECONFLICT=OVERWRITE)
  -Dname=value    set AFNI's environment variable 'name' for this run
  -skip_afnirc    accepted (no .afnirc file is read)

Python

python
lx.afni.volreg(
    image: Any,
    *,
    base: int | Any = 0,
    interpolation: Literal["Fourier", "heptic", "quintic", "cubic", "linear"] = "heptic",
    final: Literal["Fourier", "heptic", "quintic", "cubic", "linear", "NN"] | None = None,
    clip: bool = True,
    zpad: int = 4,
    twopass: bool = False,
    twoblur: float = 2.0,
    coarse: tuple[int, int] = (10, 2),
    coarse_rotation: bool = True,
    sinit: bool = True,
    weight: Any = None,
    weight_index: int = 0,
    weight_input: bool = False,
    edging: float | str | None = None,
    max_iterations: int = 23,
    x_threshold: float = 0.01,
    rot_threshold: float = 0.02,
    delta: float = 0.70,
    tshift: int | None = None,
    float_output: bool = False,
    maxdisp: bool = True,
    save_displacements: bool = False,
    rotparent: str | os.PathLike[str] | None = None,
    gridparent: str | os.PathLike[str] | None = None,
    twodup: bool = False,
    n_threads: int = 1,
    implementation: ImplementationName = "auto",
    upstream_defects: UpstreamDefectsName = "fix",
    afni_settings: Mapping[str, str] | None = None,
) -> VolregResult

Where ImplementationName is one of "auto", "replica", "clean-room", "original" (0.1.0rc1’s spelling of "clean-room"); UpstreamDefectsName is one of "fix", "reproduce".

Registers every volume of a series to a base volume, as AFNI’s 3dvolreg does.

Returns a VolregResult: registered, parameters, matrices, rms (-dfile’s rmsold and rmsnew), max_displacement and max_delta_displacement (with maxdisp=True), displacements (with save_displacements=True: the x, y and z displacement series). lx.afni.fmriprep_volreg_options() gives fMRIPrep’s arguments. The arguments are checked before anything runs (ValueError); AFNI’s fatal errors (a base with fewer than 100 non-zero voxels, mismatched grids, …) are larmorx.ReplicaErrors with AFNI’s message from the replica, ValueErrors with it from the clean room.

python
import larmorx as lx

# As fMRIPrep's RobustAverage calls 3dvolreg (-Fourier -twopass -zpad 4).
r = lx.afni.volreg("bold_sliced.nii.gz", **lx.afni.fmriprep_volreg_options())
r.registered          # the registered series (an lx.Image)
r.parameters          # (n, 6): roll, pitch, yaw (deg), dS, dL, dP (mm), as -1Dfile
r.matrices            # (n, 12): -1Dmatrix_save's rows (base to input, DICOM)
r.max_displacement    # (n,): -maxdisp1D

# The default heptic registration to volume 3, with the displacement datasets.
r = lx.afni.volreg(series, base=3, save_displacements=True, n_threads=6)

Its result, VolregResult, holds what volreg computed (one row per volume).

Field Type What it holds
registered Image The registered series, on the input’s grid (or gridparent's), in the input’s storage type (float32 with float_output=True or a scaled input).
parameters np.ndarray (n, 6) float64: roll, pitch, yaw (degrees, about the I, R and A axes) and dS, dL, dP (mm), as -1Dfile writes them (4 decimals).
matrices np.ndarray (n, 12) float64: each volume’s affine, base to input in DICOM coordinates, row by row (-1Dmatrix_save, 6 significant digits): the matrix fMRIPrep reads.
rms np.ndarray (n, 2) float64: the root mean square difference from the base before and after registration (-dfile's last two columns; 0 with rotparent).
max_displacement np.ndarray | None (n,) float64: the largest displacement of the automask’s boundary voxels, and its largest change from the previous volume (mm, -maxdisp1D, 3 decimals); None with maxdisp=False or no automask.
max_delta_displacement np.ndarray | None (n,) float64: the largest displacement of the automask’s boundary voxels, and its largest change from the previous volume (mm, -maxdisp1D, 3 decimals); None with maxdisp=False or no automask.
displacements tuple[Image, Image, Image] | None With save_displacements=True: each voxel’s displacement along the dataset’s x, y and z axes (mm, float32 series, -savedisp); else None.

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 3dvolreg accepts (crates/larmorx-afni/src/cli/volreg.rs) and the arguments of lx.afni.volreg (python/larmorx/afni/volreg.py), whose defaults and descriptions are taken from it. Under each option, in grey, its line of the usage text the clean room prints, in the clean room’s own words.

AFNI option Python Default Notes
the last word (dataset), -input, -source image NIfTI-1/2 (.nii, .nii.gz) or an in-memory image; sub-brick selectors (dset[...]) are refused, as by every larmorx AFNI toolThe clean room’s usage: “the dataset, given as an option”
-base n, -base dset base (int, path or image) 0 an external base’s first volume (AFNI warns when it has more)The clean room’s usage: “the n’th sub-brick of the input, or sub-brick 0 of another dataset”
-Fourier, -heptic (default), -quintic, -cubic, -linear interpolation "heptic" also -fourier, -Heptic, … (4 letters)The clean room’s usage: “interpolation for the estimation (default -heptic)”
-final mode final None NN, linear, cubic, quintic, heptic, FourierThe clean room’s usage: “final interpolation: NN cubic quintic heptic Fourier linear”
-clipit (default), -noclip clip True -clipit prints AFNI’s noticeThe clean room’s usage: “clip each output to its input’s range (default on)”
-zpad n zpad 4 default 4; AFNI_ROTA_ZPAD is never read (AFNI’s help says otherwise: kept, rule C)The clean room’s usage: “zero padding around the edges during rotations (default 4)”
-prefix p the result its registered; .nii/.nii.gz only; NULL writes nothingThe clean room’s usage: “output (.nii or .nii.gz); NULL writes no dataset”
-float float_output False a scaled input is always written as float, as in AFNIThe clean room’s usage: “write the output as float”
-1Dfile, -dfile, -1Dmatrix_save the result its parameters, rms and matrices; -1Dmatrix_save ff writes ff.aff12.1D unless ff ends in .1DThe clean room’s usage: “save roll, pitch, yaw, dS, dL, dP”The clean room’s usage: “save n, roll, pitch, yaw, dS, dL, dP, rmsold, rmsnew”The clean room’s usage: “save the base-to-input matrices (ff, or ff.aff12.1D)”
-maxdisp (default), -nomaxdisp, -maxdisp1D mm maxdisp True the result’s max_displacement and max_delta_displacement; the delta goes to mm_delt (with -maxdisp1D -: the file -_delt, as AFNI’s help says: kept, rule C)The clean room’s usage: “report the maximum displacement in the automask (default on)”The clean room’s usage: “also write it per sub-brick to mm (and its change to mm_delt)”
-savedisp sss, -SAVEDISP sss save_displacements False the result’s displacements; -SAVEDISP (command line only): 19 normalised datasets; names must end in .nii/.nii.gzThe clean room’s usage: “save the displacements of every voxel (sss_DX, sss_DY, sss_DZ)”
-rotcom (command line only) the 3drotate fragments on standard outputThe clean room’s usage: “print the 3drotate fragments”
-twopass, -twoblur bb, -twodup, -sinit, -coarse del num twopass, twoblur, twodup, sinit=False, coarse twopass=False, twoblur=2.0, twodup=False, sinit=True, coarse=(10, 2) -twopass raises a -maxite below 10 to 66The clean room’s usage: “two passes: a coarse search on blurred bricks first”
-coarserot (default), -nocoarserot coarse_rotation True AFNI-86: AFNI reads -nocoarserot as -noclip (reproduce)The clean room’s usage: “two passes: a coarse search on blurred bricks first”
-weight 'wset[n]', -wtinp, -wtrim weight, weight_index, weight_input weight=None, weight_index=0, weight_input=False -wtrim is always on (AFNI’s notice)The clean room’s usage: “the weight brick”The clean room’s usage: “sub-brick 0 of the input as the weight”
-edging ee, -edging ee% edging None default 5%, or AFNI_VOLREG_EDGINGThe clean room’s usage: “the weight’s zeroed edge (default 5%, or AFNI_VOLREG_EDGING)”
-maxite, -x_thresh, -rot_thresh, -delta, -params m x r d max_iterations, x_threshold, rot_threshold, delta max_iterations=23, x_threshold=0.01, rot_threshold=0.02, delta=0.70 non-positive values are ignored by -maxite etc. (the wrapper refuses them)
-tshift ii tshift None 3dTshift’s default (Fourier, the trend restored) before registeringThe clean room’s usage: “slice-time correct the input first (ignoring ii time points)”
-rotparent rset, -gridparent gset rotparent, gridparent (paths) rotparent=None, gridparent=None the rotparent must be an output of AFNI’s own 3dvolreg (larmorx writes no VOLREG_* attributes)
-verbose (twice: more) (command line only) the CPU times are printed as 0The clean room’s usage: “print progress reports (twice: lots of output)”
-@ (command line only) the arguments from standard input
-overwrite, -Dname=value, -ok_1D_text, -skip_afnirc afni_settings None AFNI’s global options, anywhere on the command line; in Python AFNI’s variables, as for 3dTshiftThe clean room’s usage: “replace an existing output (AFNI_DECONFLICT=OVERWRITE)”The clean room’s usage: “accepted (no .afnirc file is read)”
OMP_NUM_THREADS n_threads 1 the result does not depend on it (AFNI’s 3dvolreg is single-threaded on this path; the clean room runs the work inside each volume in parallel)
LARMORX_UPSTREAM_DEFECTS upstream_defects "fix" fix (default) or reproduce
LARMORX_IMPLEMENTATION implementation "auto" auto, replica or clean-room (--implementation before the family)

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 afni on the command line (larmorx --n-threads 4 afni 3dvolreg ...) and are arguments of lx.afni.volreg. 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 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) and "replica": the bit-exact replica; "clean-room" ("original", 0.1.0rc1’s spelling, still works): the clean room. The variable LARMORX_IMPLEMENTATION in 0.1.0rc1.
--upstream-defects fix|reproduce
upstream_defects="fix"
"fix" (default) or "reproduce" (AFNI’s output); a UpstreamDefectWarning names each defect that changed the result. 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: bold.nii.gz (a synthetic series of 4 such heads). The command lines run as python -m larmorx.

python
import larmorx as lx

# As fMRIPrep's RobustAverage calls 3dvolreg (-Fourier -twopass -zpad 4).
r = lx.afni.volreg("bold.nii.gz", **lx.afni.fmriprep_volreg_options())
r.parameters.shape  # -> (4, 6)
bash
larmorx afni 3dvolreg -Fourier -twopass -zpad 4 -1Dfile mc.1D -1Dmatrix_save mc.aff12.1D -maxdisp1D md.1D -prefix reg.nii.gz bold.nii.gz

Ports

3dvolreg has two ports: a replica and a clean room.

Port Package Licence Status Records
replica larmorx (built in) Apache-2.0 AND CC-BY-4.0 validated afni-volreg-replica
clean room larmorx Apache-2.0 experimental afni-volreg-original
  • The replica: status validated, bit-identical with AFNI 26.3.05 in every compared case of its record (afni-volreg-replica, 2026-11-07, the standard tier through the oracle-output cache: 190 cases, 158 pass, 30 rejected by both alike, 2 expected divergences; all 137 compared cases that write outputs give AFNI’s bytes, data and NIfTI header, and the messages of the 180 cases that ran both programs are AFNI’s byte for byte): every option, data type, orientation, message and failure case; fMRIPrep’s RobustAverage call on the BOLD references of 6 oracle runs (single-band, two volumes, multiband with 160 × 160 × 96 voxels, multi-echo, multiband 8 stored as uint16, Philips float32; 7 more in the full tier) and on sdcflows’ PEPOLAR reference averages of 2, whose medians are fMRIPrep’s own gen_avg and ref_average outputs byte for byte; AFNI 25.2.09 identical on every case. Random testing: a trial and two checks of the final build (validation/difftest/triage.toml: the trial’s 39,751 random cases agree once its findings were fixed; the final build’s checks ran 22,539 cases without a difference, whose notices without a visible change made AFNI-99’s notice exact, then 20,824, every one agreeing).
  • The clean room: status experimental (2026-11-08), held to specs/3dvolreg.md §14.3’s thresholds, not to AFNI’s bits (the shear decomposition’s exact ties: The clean room), in its record (afni-volreg-original, the standard tier from a clean commit: 251 cases, 185 pass, 63 refused alike with the same messages (every error, AFNI-88, -89, -90, -94, -96 included), 3 expected divergences (larmorx refuses AFNI’s .HEAD/.BRIK format, twice, and AFNI-96’s short attribute, rule B), none failing: every option, data type, orientation, message and failure case; fMRIPrep’s RobustAverage call on 8 BOLD references of 6 oracle runs and sdcflows’ 2 PEPOLAR averages, whose inputs re-made in fMRIPrep’s image give fMRIPrep’s own medians from AFNI’s volumes byte for byte: the clean room’s medians within 0.115 of the limit their volumes imply (ds000256’s high-motion child run; 0.0016 or less on the others), its registered volumes within 0.68 of each volume’s limit (the same run, as AFNI’s own tie variants), -final NN within the nearest-neighbour rule, -SAVEDISP’s nineteen datasets bit for bit on AFNI’s raw displacements; 417 of 1,096 -1Dfile lines identical with AFNI’s; the default held to the replica’s default by the same thresholds, with the defects named the same; every byte the same at 1, 2, 5 and 14 threads), and a random-testing trial (21,710 cases, 11,385 agreeing; a seeded sample of 1,200 of the differences judged again with the final build: 67 agree, 860 within 3 times the clean room’s own spread under the ties, 268 runaways whose structure agrees, 5 explained; triaged in validation/difftest/triage.toml; findings).

3dvolreg has two ports, both in pip install larmorx:

  • The replica is bit-exact, translated from AFNI’s source (crates/larmorx-afni-replica; Apache-2.0, with CC BY 4.0’s attribution for the code of the Medical College of Wisconsin, which AFNI 26.3.05 releases under CC BY 4.0 (NOTICE, licensing), and the NIH’s public-domain files).
  • The clean room (crates/larmorx-afni/src/volreg/, Apache-2.0) is built for speed and written from specs/3dvolreg.md by an agent that never read AFNI’s source or the replica (The clean room says how it is built and why its numbers differ from AFNI’s in the last digits).

implementation="auto" (the default, and larmorx afni 3dvolreg) and "replica" run the replica, in the same process; "clean-room" ("original", 0.1.0rc1’s spelling, still works) (--implementation clean-room before the family, or LARMORX_IMPLEMENTATION) runs the clean room, also in the same process. Each image of the result names the one that ran in its implementation.

Evidence

How each of 3dvolreg’s ports was measured against AFNI, case by case: its evidence.

More in the repository

The API page docs/api/afni-volreg.md holds what 3dvolreg shares with the page’s other programs: