% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spatial_topology.R
\name{spatial_centerline}
\alias{spatial_centerline}
\title{Trace the centerline (medial axis) of streamed polygons}
\usage{
spatial_centerline(
  x,
  density = NULL,
  prune = 0,
  geom = "geometry",
  crs = NA,
  out_geom = NULL,
  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{density}{Boundary sampling spacing in CRS units: the polygon outline is
densified to at most this vertex spacing before the Voronoi diagram is
built. \code{NULL} (default) uses one-hundredth of each polygon's bounding-box
diagonal.}

\item{prune}{Drop centerline branches shorter than this length (CRS units),
removing the short spurs the skeleton grows toward convex corners. \code{0}
(default) keeps every branch.}

\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{out_geom}{Name of the output geometry column. Defaults to \code{geom}
(or \code{"geometry"} when \code{coords} is used).}

\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 centerlines, each carrying its source polygon's
attributes (replicated if the centerline is several lines) and the input
CRS, backed by temporary \code{.vtr} spills removed when the node is
garbage-collected.
}
\description{
Approximates the centerline of every polygon in a streamed layer, one batch
at a time -- the medial axis a per-feature transform such as a buffer cannot
produce. Each polygon's boundary is densified and its Voronoi diagram taken;
the Voronoi edges that fall inside the polygon trace the points equidistant
from two stretches of boundary, which is its skeleton, and they are merged
into maximal lines. This is the usual approximation for river or road
centerlines from a filled shape; \code{prune} drops the short branches that the
skeleton grows toward convex corners. A non-polygon geometry passes through
unchanged.
}
\details{
The centerline is an approximation whose detail is set by \code{density} (the
boundary sampling spacing): finer sampling traces the axis more closely at
more cost. Geometry travels through the engine as hex-encoded WKB in a string
column and the CRS is carried on the returned node; the Voronoi construction
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}
road <- sf::st_polygon(list(rbind(
  c(0, 0), c(10, 0), c(10, 2), c(0, 2), c(0, 0))))
f <- tempfile(fileext = ".vtr")
write_vtr(data.frame(
  geometry = sf::st_as_binary(sf::st_sfc(road), hex = TRUE)
), f)

# The centerline runs down the middle of the strip.
tbl(f) |> spatial_centerline(density = 0.25, prune = 0.5) |> collect_sf()
unlink(f)
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=spatial_construct]{spatial_construct()}} with \code{kind = "pole"} for the single deepest
interior point, \code{\link[=spatial_simplify]{spatial_simplify()}} to simplify a coverage, \code{\link[=collect_sf]{collect_sf()}}
to materialize as \code{sf}.
}
