% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spatial_topology.R
\name{spatial_polygonize}
\alias{spatial_polygonize}
\title{Build polygonal faces from a line network}
\usage{
spatial_polygonize(
  x,
  by = NULL,
  geom = "geometry",
  crs = NA,
  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{by}{Character vector of attribute columns to polygonize within: one set
of faces per distinct combination of their values. \code{NULL} (default)
polygonizes the whole layer at once.}

\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{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 one row per face, carrying the \code{by} columns and the
input CRS, backed by temporary \code{.vtr} spills removed when the node is
garbage-collected.
}
\description{
Forms the polygons enclosed by a set of lines (the QGIS "Polygonize", GEOS
\code{Polygonize}): the inverse of taking polygon boundaries. The lines of each
group are unioned and noded so every crossing becomes a shared vertex, then
the faces of that planar arrangement are returned, one per row. A pile of
lines that does not close any area yields no faces. Like \code{\link[=spatial_dissolve]{spatial_dissolve()}}
and \code{\link[=spatial_construct]{spatial_construct()}} 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 group's lines are polygonized together. Peak memory is the routing
budget during the pass, then one group's geometry while its faces are built --
partition on a key whose groups fit in memory. With no \code{by}, the whole layer
yields one set of faces.
}
\details{
Each face is new geometry built from the whole group, so it carries the \code{by}
columns only, not the attributes of any single source line. Geometry travels
through the engine as hex-encoded WKB in a string column and the CRS is
carried on the returned node; the noding is \pkg{sf}/GEOS and expects
projected or unprojected planar data. The \pkg{sf} package is an optional
dependency (Suggests).
}
\examples{
\dontshow{if (requireNamespace("sf", quietly = TRUE)) withAutoprint(\{ # examplesIf}
grid <- sf::st_sfc(
  sf::st_linestring(rbind(c(0, 0), c(2, 0))),
  sf::st_linestring(rbind(c(0, 1), c(2, 1))),
  sf::st_linestring(rbind(c(0, 2), c(2, 2))),
  sf::st_linestring(rbind(c(0, 0), c(0, 2))),
  sf::st_linestring(rbind(c(1, 0), c(1, 2))),
  sf::st_linestring(rbind(c(2, 0), c(2, 2))))
f <- tempfile(fileext = ".vtr")
write_vtr(data.frame(
  geometry = sf::st_as_binary(grid, hex = TRUE)
), f)

# The four unit cells enclosed by the grid of lines.
tbl(f) |> spatial_polygonize() |> collect_sf()
unlink(f)
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=spatial_split]{spatial_split()}} to cut existing polygons by a blade,
\code{\link[=spatial_construct]{spatial_construct()}} for hulls and tessellations, \code{\link[=spatial_dissolve]{spatial_dissolve()}} to
merge geometries by group, \code{\link[=collect_sf]{collect_sf()}} to materialize as \code{sf}.
}
