% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spatial.R
\name{rasterize}
\alias{rasterize}
\title{Rasterize a streamed point layer onto a fixed grid}
\usage{
rasterize(
  x,
  template = NULL,
  field = NULL,
  fun = c("count", "sum", "mean", "min", "max"),
  extent = NULL,
  res = NULL,
  dims = NULL,
  coords = c("x", "y"),
  geom = NULL,
  crs = NA,
  background = NA_real_,
  path = NULL,
  dtype = "f32"
)
}
\arguments{
\item{x}{A \code{vectra_node} streaming the points (from \code{\link[=tbl]{tbl()}}, \code{\link[=tbl_csv]{tbl_csv()}}, any
verb chain). It is consumed by the stream.}

\item{template}{Optional grid to borrow geometry and CRS from: a
\code{vectra_raster} (from \code{\link[=vec_open_raster]{vec_open_raster()}}), or a numeric
\code{c(xmin, ymin, xmax, ymax)} extent. When omitted, supply \code{extent} with
\code{res} or \code{dims}.}

\item{field}{Name of a numeric column to aggregate. Required for every \code{fun}
except \code{"count"} (which ignores it).}

\item{fun}{Reduction over the points in each cell: one of \code{"count"}, \code{"sum"},
\code{"mean"}, \code{"min"}, \code{"max"}. \code{NA} values in \code{field} are skipped.}

\item{extent}{Numeric \code{c(xmin, ymin, xmax, ymax)} defining the grid extent
when no \code{template} is given.}

\item{res}{Cell size: a single number for square cells, or \code{c(xres, yres)}.
The cell counts are rounded to fit \code{extent} exactly. Supply \code{res} or \code{dims}.}

\item{dims}{Grid shape \code{c(nrow, ncol)}, an alternative to \code{res}.}

\item{coords}{Length-2 character vector naming the x and y coordinate
columns. Default \code{c("x", "y")}. Ignored when \code{geom} is supplied.}

\item{geom}{Name of a hex-WKB point-geometry column to rasterize instead of
coordinate columns. Requires \pkg{sf}.}

\item{crs}{Coordinate reference system recorded on the output, in any form
\code{\link[sf:st_crs]{sf::st_crs()}} accepts or a bare EPSG integer. Defaults to the template's,
then the node's, else unknown.}

\item{background}{Value for cells that receive no point. Default \code{NA_real_}.}

\item{path}{Optional output path. When given, the grid is written to a \code{.vec}
raster via \code{\link[=vec_write_raster]{vec_write_raster()}} and the opened \code{\link[=vec_open_raster]{vec_open_raster()}} handle is
returned invisibly. When \code{NULL}, the grid is returned in memory.}

\item{dtype}{Storage dtype for the \code{.vec} output (see \code{\link[=vec_write_raster]{vec_write_raster()}}).
Default \code{"f32"}.}
}
\value{
When \code{path} is \code{NULL}, a numeric matrix with \code{nrow} grid rows
(row 1 northmost) and \code{ncol} grid columns, carrying \code{gt}, \code{extent}, \code{res},
\code{crs}, and \code{fun} attributes. When \code{path} is given, the written
\code{vectra_raster} handle (invisibly).
}
\description{
Folds a larger-than-RAM stream of points into a fixed raster grid one batch
at a time. The grid (\code{template}) is held resident in memory while the points
flow past the engine, so peak memory is the grid plus one batch regardless of
how many points there are -- the streaming counterpart to running
\code{terra::rasterize()} on a point set that has to fit in RAM. Each point's
coordinate is mapped to its grid cell through the raster geotransform and the
per-cell value is accumulated in C.
}
\details{
The reduction \code{fun} is a monoid over the points falling in each cell:
\code{"count"} tallies points (no \code{field} needed); \code{"sum"}, \code{"mean"}, \code{"min"},
\code{"max"} aggregate a numeric \code{field}. Cells that receive no point take the
\code{background} value (\code{NA} by default). This is the \emph{monoid fold} tier of the
spatial toolbox: bounded memory, a single streaming pass, no spill.

Points arrive either as two numeric coordinate columns (\code{coords}, the default
and fully \pkg{sf}-free path -- the headline larger-than-RAM case) or decoded
from a hex-WKB point-geometry column (\code{geom}, which needs \pkg{sf}). Geometry
input is expected to be points (one coordinate per row); line and polygon
coverage rasterization is out of scope here.
}
\examples{
set.seed(1)
n <- 1e4
pts <- data.frame(x = runif(n, 0, 10), y = runif(n, 0, 10), z = rnorm(n))
f <- tempfile(fileext = ".vtr")
write_vtr(pts, f)

# Point density on a 10x10 grid, streamed: the grid is resident, the
# points are not.
counts <- tbl(f) |> rasterize(extent = c(0, 0, 10, 10), dims = c(10, 10))
counts

# Mean of z per cell.
zmean <- tbl(f) |>
  rasterize(extent = c(0, 0, 10, 10), dims = c(10, 10),
            field = "z", fun = "mean")
unlink(f)

}
\seealso{
\code{\link[=vec_write_raster]{vec_write_raster()}} and \code{\link[=vec_to_tiff]{vec_to_tiff()}} for raster output,
\code{\link[=spatial_join]{spatial_join()}} to instead tag points with polygon attributes.
}
