% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/imaging-fill-surface.R
\name{fill_surface}
\alias{fill_surface}
\title{Fill a volume cube based on water-tight surface}
\usage{
fill_surface(
  surface,
  inflate = 0,
  close_radius = NULL,
  resolution = 256L,
  IJK2RAS = NULL,
  preview = FALSE,
  preview_frame = 128
)
}
\arguments{
\item{surface}{a surface mesh; accepted classes include \code{'mesh3d'}
(from \code{rgl}), \code{'fs.surface'} (from \code{freesurferformats}),
\code{'ieegio_surface'} (from \pkg{ieegio}), or a bare list containing a
\code{vb} vertex matrix; see \code{\link{ensure_mesh3d}} for details and
for how \code{'ieegio_surface'} inputs are coerced}

\item{inflate}{amount of 'voxels' to inflate on the final result; must be
a non-negative integer. A zero \code{inflate} value means the resulting
volume is tightly close to the surface}

\item{close_radius}{radius (in 'voxels' along the finest 'IJK' axis; see
\code{IJK2RAS}) of the morphological closing (dilate-then-erode) operation
used to connect the embedded surface into a water-tight shell \emph{and} to
remove small topological handles/tunnels (for example a hole drilled
through an otherwise solid structure) before the surface is filled; default
is \code{NULL}, which derives a radius from the surface geometry (capped at
\code{15} 'voxels'). Handles/tunnels wider than roughly twice this radius
(in physical, \verb{RAS} space) will not be closed, so when the input
surface is known to contain larger topological defects, set this to a
larger number explicitly. Larger radii cost more time and memory (the
closing operates on a dense \code{resolution^3} volume) and - because the
operation is performed in a fixed-size volume - must leave enough margin
that the dilated shell does not reach the volume boundary; radii that are
too large for the working cube will be capped with a warning}

\item{resolution}{number of 'voxels' along each margin of the working
cube volume that the surface is embedded into; default is \code{256}.
Larger values increase the spatial precision of the fill and the closing
operation (at the cost of memory and computation time, which scale with
\code{resolution^3}); the value must leave enough room for the surface
(transformed into 'IJK' space via \code{IJK2RAS}) plus the closing margin
to fit inside the cube}

\item{IJK2RAS}{volume 'IJK' (zero-indexed coordinate index) to
\code{'tkrRAS'} transform, default is automatically determined
leave it `NULL` if you don't know how to set it. When the linear part of
\code{IJK2RAS} encodes voxel sizes that differ across axes (\code{pixdim},
i.e. the three 'IJK' axes do not advance by the same physical distance per
'voxel'), the dilate/erode operations underlying \code{close_radius} and
\code{inflate} automatically use a different number of 'voxels' along each
axis so that the resulting structuring element stays isotropic in physical
(\verb{RAS}) space}

\item{preview}{whether to preview the results; default is false}

\item{preview_frame}{integer from 1 to 256 the depth frame used to generate
preview.}
}
\value{
A list containing the filled volume and parameters used to generate
the volume
}
\description{
Create a cube volume (\code{256} 'voxels' on each margin), fill
in the 'voxels' that are inside of the surface.
}
\details{
This function creates a volume (256 on each margin) and fill in
the volume from a surface mesh. The surface vertex points will be embedded
into the volume first. These points may not be connected together, hence
for each 'voxel', a cube patch will be applied to grow the volume. Then,
the volume will be bucket-filled from a corner, forming a negated mask of
"outside-of-surface" area. The inverted bucket-filled volume is then shrunk
so the mask boundary tightly fits the surface
}
\section{Coercing Surface Inputs}{

The surface objects are converted to \code{'mesh3d'} object before
applying further calculations.

When \code{surface} is a surface \pkg{ieegio} object, the returned
\code{mesh3d$vb} contains vertices that have been left-multiplied by
\code{surface$geometry$transforms[[1]]} (the first transform stored in the
geometry, typically the \code{ScannerAnat} or voxel-to-world transform).

\strong{Breaking change:} Earlier versions (before 0.2.6) of \pkg{ravetools}
returned the raw \code{surface$geometry$vertices} without applying any
transform, so downstream code often multiplied by
\code{surface$geometry$transforms[[1]]} (or an equivalent) manually before
working in world space. Such code will now \emph{double}
apply the transform and produce incorrect coordinates. If you previously
applied a transform from \code{surface$geometry$transforms} by hand after
calling a \pkg{ravetools} mesh function on an \code{'ieegio_surface'},
remove that manual step.

Surfaces with an empty or missing \code{geometry$transforms} list (for
example, surfaces produced by \pkg{ieegio}'s \code{volume_to_surface},
which stores an identity transform) are unaffected.

If \code{geometry$transforms} contains multiple transforms targeting
different coordinate spaces, only the first one is used. Callers that need
a specific target space should select and apply that transform themselves
before calling \pkg{ravetools} mesh functions.
}

\examples{

\donttest{

# takes > 5s to run example

# Generate a sphere
surface <- vcg_sphere()
surface$vb[1:3, ] <- surface$vb[1:3, ] * 50

fill_surface(surface, preview = TRUE)

}

}
\seealso{
\code{\link{ensure_mesh3d}}
}
\author{
Zhengjia Wang
}
