write_ants_warp: Read and write an 'ANTs' deformation (warp) field

In ravetools: Signal and Image Processing Toolbox for Analyzing Intracranial Electroencephalography Data

Read and write an ⁠'ANTs'⁠ deformation (warp) field

Description

write_ants_warp stores a dense displacement field (such as the forward_field / inverse_field from register_volume3d) as an 'ANTs' 5-D warp 'NIfTI' (intent_code 1007, ⁠LPS⁠ vectors) readable by antsApplyTransforms; read_ants_warp reads it back. Requires the suggested freesurferformats package.

The field is stored on disk with displacement vectors in ⁠LPS⁠ (the x and y components are negated relative to the ⁠RAS⁠ field) and an sform equal to vox2ras, so the file describes the fixed grid's physical space exactly as 'ANTs' expects. Optionally the ⁠RAS⁠ ⁠affine⁠ can be hidden in the header text fields (descrip/aux_file); 'ANTs' ignores those, and recovery on read is opt-in.

Usage

write_ants_warp(
  field,
  file,
  vox2ras = attr(field, "vox2ras"),
  affine = NULL,
  direction = c("forward", "inverse")
)

read_ants_warp(file, recover_affine = FALSE)

Arguments

field	a (nx, ny, nz, 3) array of ⁠RAS⁠ displacements; the vox2ras attribute is used when vox2ras is not supplied
file	path to the warp .nii / .nii.gz file
vox2ras	the fixed-grid 4\times 4 voxel-to-⁠RAS⁠ matrix
affine	optional 4\times 4 ⁠RAS⁠ ⁠affine⁠ to embed (with reduced precision) in the header; NULL (default) embeds nothing
direction	"forward" or "inverse"; recorded as the header direction flag when affine is embedded
recover_affine	logical; if TRUE, attempt to decode a hidden ⁠affine⁠ from the header and attach it as the "transform" attribute (with a "direction" attribute). Default FALSE

Value

write_ants_warp returns file invisibly; read_ants_warp returns the (nx, ny, nz, 3) ⁠RAS⁠ field with a "vox2ras" attribute (and, if recovered, "transform" / "direction" attributes).

See Also

register_volume3d, save_registration

ravetools documentation built on Aug. 21, 2026, 5:06 p.m.