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
larmorxApache-2.0 AND CC-BY-4.0 validated - clean room
larmorxApache-2.0 experimental
- replica
- 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
larmorx afni 3dvolreg [options] datasetEverything 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):
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
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
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,
) -> VolregResultWhere 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.
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 Nn_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-roomimplementation="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|reproduceupstream_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.
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)larmorx afni 3dvolreg -Fourier -twopass -zpad 4 -1Dfile mc.1D -1Dmatrix_save mc.aff12.1D -maxdisp1D md.1D -prefix reg.nii.gz bold.nii.gzPorts
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 owngen_avgandref_averageoutputs 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 tospecs/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 NNwithin the nearest-neighbour rule,-SAVEDISP’s nineteen datasets bit for bit on AFNI’s raw displacements; 417 of 1,096-1Dfilelines 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 invalidation/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 fromspecs/3dvolreg.mdby 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: