% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spatial_more.R
\name{mosaic}
\alias{mosaic}
\title{Merge aligned rasters onto a common grid}
\usage{
mosaic(
  rasters,
  fun = c("first", "last", "mean", "sum", "min", "max"),
  band = 1L,
  path = NULL,
  dtype = "f32",
  compression = c("fast", "balanced", "max")
)
}
\arguments{
\item{rasters}{A list of \code{vectra_raster} handles or \code{.vec} paths sharing
resolution and grid alignment.}

\item{fun}{Overlap rule where inputs cover the same cell: \code{"first"} (the
earliest input in \code{rasters}, default), \code{"last"}, \code{"mean"}, \code{"sum"}, \code{"min"},
or \code{"max"}. Cells covered by no input come back \code{NA}.}

\item{band}{Band read from every input (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 on the union grid (row 1
northmost) carrying \code{gt}, \code{extent}, and \code{crs} attributes. When \code{path} is
given, the written \code{vectra_raster} handle (invisibly).
}
\description{
Combines several \code{.vec} rasters that share a resolution and cell grid into one
raster spanning their union, resolving overlap with \code{fun}. The output is
walked one tile-row strip at a time and each input contributes only the window
overlapping the current strip, so neither the inputs nor the output are held
whole in memory.
}
\details{
This is the \emph{monoid fold} tier of the spatial toolbox: each output strip folds
the overlapping input windows, bounded memory, no spill. The inputs must share
resolution and lie on a common cell grid; \code{\link[=warp]{warp()}} them onto a shared grid
first if they do not. No \pkg{sf} is needed.
}
\examples{
a <- matrix(1, 4, 4); b <- matrix(2, 4, 4)
fa <- tempfile(fileext = ".vec"); fb <- tempfile(fileext = ".vec")
vec_write_raster(a, fa, dtype = "f64", extent = c(0, 0, 4, 4))
vec_write_raster(b, fb, dtype = "f64", extent = c(2, 2, 6, 6))

m <- mosaic(list(fa, fb), fun = "mean")
dim(m)
unlink(c(fa, fb))

}
\seealso{
\code{\link[=warp]{warp()}} to bring rasters onto a shared grid, \code{\link[=rast_calc]{rast_calc()}} for
cellwise combination of already-aligned rasters.
}
