% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spatial.R
\name{focal}
\alias{focal}
\title{Moving-window (focal) statistics over a streamed raster}
\usage{
focal(
  x,
  w = matrix(1, 3, 3),
  fun = c("mean", "sum", "min", "max", "sd", "median"),
  na.rm = TRUE,
  band = 1L,
  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{w}{A numeric weight matrix with odd dimensions, or a single positive
odd integer \code{k} for a \verb{k x k} window of ones. Default \code{matrix(1, 3, 3)}.}

\item{fun}{Window statistic: one of \code{"sum"}, \code{"mean"}, \code{"min"}, \code{"max"},
\code{"sd"}, \code{"median"}. Default \code{"mean"}.}

\item{na.rm}{Skip nodata cells inside the window (\code{TRUE}, default) or let
them propagate \code{NA} (\code{FALSE}).}

\item{band}{Band to read (1-based). Default 1.}

\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 as an in-memory matrix.}

\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 (row 1 northmost) carrying
\code{gt}, \code{extent}, \code{crs}, and \code{fun} attributes. When \code{path} is given, the
written \code{vectra_raster} handle (invisibly).
}
\description{
Applies a moving window to a \code{.vec} raster, reading the input one tile-row
strip at a time -- each strip expanded by the kernel radius (a halo read) so
window neighbours are available without ever holding the whole grid resident.
The per-window statistic is computed in C. When \code{path} is given the output is
streamed straight back to a new \code{.vec} one tile-row at a time, so neither the
input nor the output band is ever fully in memory; this is the raster op that
runs out of core where an in-memory engine needs the whole raster at once.
}
\details{
This is the \emph{sort / partition} tier of the spatial toolbox: bounded to one
haloed strip at a time, exploiting tile locality.

The window \code{w} is a numeric weight matrix with odd dimensions (or a single
odd integer \code{k}, shorthand for a \verb{k x k} matrix of ones). \code{NA} weights mark
cells outside the window. For \code{fun = "sum"}/\code{"mean"} the weights scale the
values (sum is \code{sum(w * x)}, mean is \code{sum(w * x) / sum(w)}); for the other
statistics a finite weight only marks membership. With \code{na.rm = TRUE} (the
default) nodata cells inside the window are skipped; with \code{na.rm = FALSE} any
nodata cell -- including a window that runs off the raster edge -- makes the
result \code{NA}, matching the resident behaviour.
}
\examples{
m <- matrix(1:36, 6, 6, byrow = TRUE)
f <- tempfile(fileext = ".vec")
vec_write_raster(m, f, dtype = "f64", extent = c(0, 0, 6, 6))

# 3x3 mean smoother; edge cells see off-raster neighbours.
focal(f, w = matrix(1, 3, 3), fun = "mean")
unlink(f)

}
\seealso{
\code{\link[=terrain]{terrain()}} for DEM derivatives built on the same strip pass,
\code{\link[=zonal]{zonal()}} for per-zone summaries.
}
