% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spatial.R
\name{spatial_construct}
\alias{spatial_construct}
\title{Build a set-wise geometry construction, optionally per group}
\usage{
spatial_construct(
  x,
  kind = .CONSTRUCT_KINDS,
  by = NULL,
  geom = "geometry",
  crs = NA,
  ratio = 0.3,
  allow_holes = FALSE,
  tolerance = 0,
  flush_rows = NULL
)
}
\arguments{
\item{x}{A \code{vectra_node} (from \code{\link[=tbl]{tbl()}}, \code{\link[=tbl_tiff]{tbl_tiff()}}, any verb chain, ...).
It is consumed by the stream.}

\item{kind}{The construction to build; one of the values above.}

\item{by}{Character vector of attribute columns to construct within: one
construction (or tessellation) per distinct combination of their values.
\code{NULL} (default) builds a single construction from the whole layer.}

\item{geom}{Name of the input geometry column holding hex-WKB or WKT strings.
Default \code{"geometry"}. Ignored when \code{coords} is given.}

\item{crs}{Coordinate reference system of the input geometry, in any form
\code{\link[sf:st_crs]{sf::st_crs()}} accepts (EPSG integer, WKT, proj string). Defaults to the
CRS the upstream node carries, or unknown.}

\item{ratio}{For \code{kind = "concave_hull"}, the concaveness in \verb{[0, 1]} (1 is
the convex hull). Default \code{0.3}.}

\item{allow_holes}{For \code{kind = "concave_hull"}, whether the hull may contain
holes. Default \code{FALSE}.}

\item{tolerance}{Distance tolerance for the kinds that take one
(\code{"inscribed_circle"}, \code{"pole"}, \code{"voronoi"}, \code{"delaunay"}). \code{0} (default)
lets the inscribed-circle kinds derive a tolerance from the extent and the
tessellations use the GEOS default.}

\item{flush_rows}{Transformed rows buffered before a spill flush. Larger
values mean fewer, bigger temporary files. Defaults to
\code{getOption("vectra.spatial_flush", 5e5)}.}
}
\value{
A \code{vectra_node} of the construction -- one row per group for the
enclosing kinds, one row per cell for the tessellations -- carrying the
\code{by} columns and the input CRS, backed by temporary \code{.vtr} spills removed
when the node is garbage-collected.
}
\description{
Constructs one geometry (or a tessellation) from a whole set of features --
the constructions a per-feature \code{\link[=spatial_map]{spatial_map()}} cannot express because they
need every feature in scope at once. Like \code{\link[=spatial_dissolve]{spatial_dissolve()}} it rides the
\strong{partition tier}: \code{x} is spilled once and routed into one disjoint shard per
\code{by} group in a single bounded pass, then each shard's geometry is combined
and the construction built with \pkg{sf}. With no \code{by}, the whole layer yields
one construction. Peak memory is the routing budget during the pass, then one
group's geometry while it is built -- partition on a key whose groups fit in
memory.
}
\details{
\code{kind} selects the construction:
\describe{
\item{\code{"convex_hull"}}{the convex hull of the set.}
\item{\code{"concave_hull"}}{the concave hull (\code{ratio}, \code{allow_holes}).}
\item{\code{"envelope"}}{the axis-aligned bounding rectangle.}
\item{\code{"oriented_box"}}{the minimum-area rotated bounding rectangle.}
\item{\code{"enclosing_circle"}}{the minimum bounding circle.}
\item{\code{"inscribed_circle"}}{the maximum inscribed circle (largest circle
that fits inside the set's union).}
\item{\code{"pole"}}{the pole of inaccessibility -- the centre of the maximum
inscribed circle, the point inside the shape farthest from its edges.}
\item{\code{"voronoi"}}{the Voronoi tessellation, one polygon per cell.}
\item{\code{"delaunay"}}{the Delaunay triangulation, one polygon per triangle.}
}
The enclosing kinds and \code{pole} emit one feature per group; \code{voronoi} and
\code{delaunay} emit one feature per cell, each carrying the group's \code{by} values.

Geometry travels through the engine as hex-encoded WKB in a string column and
the CRS is carried on the returned node; use \code{\link[=collect_sf]{collect_sf()}} to materialize.
Topology is \pkg{sf}/GEOS throughout (an optional dependency, Suggests); some
constructions need projected coordinates.
}
\examples{
\dontshow{if (requireNamespace("sf", quietly = TRUE)) withAutoprint(\{ # examplesIf}
nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
nc$band <- nc$SID74 > 5
f <- tempfile(fileext = ".vtr")
write_vtr(data.frame(
  band = nc$band,
  geometry = sf::st_as_binary(sf::st_geometry(nc), hex = TRUE)
), f)

# One convex hull per band.
tbl(f) |>
  spatial_construct("convex_hull", by = "band", crs = sf::st_crs(nc)) |>
  collect_sf()
unlink(f)
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=spatial_dissolve]{spatial_dissolve()}} to merge a group into one feature,
\code{\link[=spatial_map]{spatial_map()}} for per-feature transforms, \code{\link[=collect_sf]{collect_sf()}} to materialize.
}
