% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/imaging-ants-io.R
\name{write_ants_warp}
\alias{write_ants_warp}
\alias{read_ants_warp}
\title{Read and write an \verb{'ANTs'} deformation (warp) field}
\usage{
write_ants_warp(
  field,
  file,
  vox2ras = attr(field, "vox2ras"),
  affine = NULL,
  direction = c("forward", "inverse")
)

read_ants_warp(file, recover_affine = FALSE)
}
\arguments{
\item{field}{a \code{(nx, ny, nz, 3)} array of \verb{RAS} displacements; the
\code{vox2ras} attribute is used when \code{vox2ras} is not supplied}

\item{file}{path to the warp \code{.nii} / \code{.nii.gz} file}

\item{vox2ras}{the fixed-grid \eqn{4\times 4} voxel-to-\verb{RAS} matrix}

\item{affine}{optional \eqn{4\times 4} \verb{RAS} \verb{affine} to embed (with
reduced precision) in the header; \code{NULL} (default) embeds nothing}

\item{direction}{\code{"forward"} or \code{"inverse"}; recorded as the
header direction flag when \code{affine} is embedded}

\item{recover_affine}{logical; if \code{TRUE}, attempt to decode a hidden
\verb{affine} from the header and attach it as the \code{"transform"} attribute
(with a \code{"direction"} attribute). Default \code{FALSE}}
}
\value{
\code{write_ants_warp} returns \code{file} invisibly;
\code{read_ants_warp} returns the \code{(nx, ny, nz, 3)} \verb{RAS} field with
a \code{"vox2ras"} attribute (and, if recovered, \code{"transform"} /
\code{"direction"} attributes).
}
\description{
\code{write_ants_warp} stores a dense displacement field (such as the
\code{forward_field} / \code{inverse_field} from
\code{\link{register_volume3d}}) as an \pkg{'ANTs'} 5-D warp \code{'NIfTI'}
(\code{intent_code} \code{1007}, \verb{LPS} vectors) readable by
\code{antsApplyTransforms}; \code{read_ants_warp} reads it back. Requires the
suggested \pkg{freesurferformats} package.

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