% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spatial_more.R
\name{mask}
\alias{mask}
\title{Mask a streamed raster to a polygon layer}
\usage{
mask(
  x,
  mask,
  inverse = FALSE,
  band = NULL,
  background = NA_real_,
  path = NULL,
  dtype = "f32",
  compression = c("fast", "balanced", "max")
)
}
\arguments{
\item{x}{A \code{vectra_raster} (from \code{\link[=vec_open_raster]{vec_open_raster()}}) or a path to a \code{.vec}
raster.}

\item{mask}{An \code{sf} or \code{sfc} polygon layer to clip against. When it carries no
CRS it inherits the raster's EPSG.}

\item{inverse}{If \code{FALSE} (default) keep pixels inside \code{mask}; if \code{TRUE} keep
the pixels outside it.}

\item{band}{Band(s) to mask (1-based). Default \code{NULL} masks every band.}

\item{background}{Value written to cleared pixels. Default \code{NA_real_}.}

\item{path}{Optional output \code{.vec} path. When given the result is streamed to
disk and the opened \code{\link[=vec_open_raster]{vec_open_raster()}} handle is returned invisibly; when
\code{NULL} the result is returned in memory (a matrix for one band, a list of
matrices for several).}

\item{dtype}{Storage dtype for \code{.vec} output (see \code{\link[=vec_write_raster]{vec_write_raster()}}).
Default \code{"f32"}.}

\item{compression}{Compression effort for \code{.vec} output. Default \code{"fast"}.}
}
\value{
When \code{path} is \code{NULL}, a numeric matrix (one band) or a list of
matrices (several), each carrying \code{gt}, \code{extent}, and \code{crs} attributes
(row 1 northmost). When \code{path} is given, the written \code{vectra_raster} handle
(invisibly).
}
\description{
Keeps the pixels of a \code{.vec} raster whose cell centre falls inside a resident
polygon layer and sets the rest to \code{background}, reading the raster one
tile-row strip at a time so the whole grid is never resident. It is the raster
counterpart of \code{\link[=spatial_clip]{spatial_clip()}}: the streamed side is the (large) raster and
the small \code{mask} layer stays in memory. With \code{inverse = TRUE} the inside is
cleared and the outside kept.
}
\details{
This is the \emph{monoid fold} tier of the spatial toolbox: bounded to one strip
plus the resident mask, a single streaming pass, no spill. A pixel is tested
against the mask only when its centre falls in the mask bounding box, so the
point-in-polygon work stays proportional to the overlap rather than the whole
grid. Point-in-polygon is delegated to \pkg{sf} (an optional dependency);
topology and CRS handling are \pkg{sf}'s.
}
\examples{
\dontshow{if (requireNamespace("sf", quietly = TRUE)) withAutoprint(\{ # examplesIf}
vals <- matrix(1:100, 10, 10, byrow = TRUE)
f <- tempfile(fileext = ".vec")
vec_write_raster(vals, f, dtype = "f64", extent = c(0, 0, 10, 10))

disc <- sf::st_buffer(sf::st_sfc(sf::st_point(c(5, 5))), 3)
inside <- mask(f, disc)
sum(!is.na(inside))
unlink(f)
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=spatial_clip]{spatial_clip()}} for the vector analogue, \code{\link[=zonal]{zonal()}} for per-zone
summaries over the same pixel-in-polygon assignment.
}
