% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spatial_more.R
\name{contours}
\alias{contours}
\title{Extract contour iso-lines from a streamed raster}
\usage{
contours(x, levels, band = 1L, merge = TRUE, crs = NA, flush_rows = NULL)
}
\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{levels}{Numeric vector of contour levels to trace.}

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

\item{merge}{If \code{TRUE} (default) join each level's segments into continuous
lines with \code{\link[sf:st_line_merge]{sf::st_line_merge()}}; if \code{FALSE} return the raw per-cell
segments.}

\item{crs}{Coordinate reference system recorded on the node. Defaults to the
raster's EPSG, else unknown.}

\item{flush_rows}{Rows buffered before a spill flush. Defaults to
\code{getOption("vectra.spatial_flush", 5e5)}.}
}
\value{
A \code{vectra_node} with a \code{level} column and a hex-WKB \code{geometry} column,
materialise it with \code{\link[=collect_sf]{collect_sf()}}.
}
\description{
Traces contour lines at one or more levels from a \code{.vec} raster with marching
squares, reading the raster one tile-row strip at a time (each strip expanded
by one row so a cell straddling the strip boundary is traced once). Each strip
contributes line segments, which are accumulated into a lazy \code{vectra_node}
carrying a \code{level} column and hex-WKB geometry. With \code{merge = TRUE} the
segments of each level are joined into continuous lines.
}
\details{
Extraction is the \emph{sort / partition} tier of the spatial toolbox: bounded to
one haloed strip at a time. The optional final merge collects the segment set,
which is small relative to the raster, and joins it per level; this is the
small all-to-all step on the output, not on the grid. Geometry assembly and
the merge are delegated to \pkg{sf} (an optional dependency).
}
\examples{
\dontshow{if (requireNamespace("sf", quietly = TRUE)) withAutoprint(\{ # examplesIf}
z <- outer(1:20, 1:20, function(r, c) r + c)
f <- tempfile(fileext = ".vec")
vec_write_raster(z, f, dtype = "f64", extent = c(0, 0, 20, 20))

iso <- contours(f, levels = c(15, 25, 35))
collect_sf(iso)
unlink(f)
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=polygonize]{polygonize()}} for area features, \code{\link[=terrain]{terrain()}} for the DEM
derivatives contours often accompany, \code{\link[=collect_sf]{collect_sf()}} to materialise as \code{sf}.
}
