% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/network.R
\name{spatial_service_area}
\alias{spatial_service_area}
\title{Service areas and isochrones over a network}
\usage{
spatial_service_area(
  x,
  network,
  cost,
  output = c("polygon", "lines", "nodes"),
  band_col = "band",
  geom = "geometry",
  coords = NULL,
  crs = NA,
  out_geom = NULL,
  flush_rows = NULL
)
}
\arguments{
\item{x}{A \code{vectra_node} of origin features (point geometry, or \code{coords}).}

\item{network}{A \code{vectra_network} from \code{\link[=spatial_network]{spatial_network()}}.}

\item{cost}{A cost budget (scalar), or several budgets for nested isochrone
bands (e.g. \code{c(5, 10, 15)}).}

\item{output}{\code{"polygon"} (default) for the convex hull of the reachable
nodes, \code{"lines"} for the reachable edges, or \code{"nodes"} for the reachable
nodes as a multipoint.}

\item{band_col}{Name of the output column holding each row's budget. Default
\code{"band"}.}

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

\item{coords}{Optional length-2 character vector naming the x and y
coordinate columns to assemble point geometry from (e.g. \code{c("x", "y")}),
for inputs such as \code{\link[=tiff_extract_points]{tiff_extract_points()}} output. The coordinate columns
are retained.}

\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}: one row per (origin, band) carrying \code{x}'s attributes,
the band value, and the service-area geometry. Backed by temporary \code{.vtr}
spills removed when the node is garbage-collected, and carrying the network
CRS.
}
\description{
Streams a layer of origins \code{x} past a resident \code{\link[=spatial_network]{spatial_network()}} and, for
each origin, finds every part of the network reachable within a cost budget -
the service area, or, with several budgets, nested travel-cost isochrone bands.
Each origin is snapped to its nearest graph node and a budget-bounded Dijkstra
(native C) collects the reachable nodes; the reachable set is returned as the
convex hull (\code{output = "polygon"}, the generalised service area), the
reachable edges (\code{"lines"}), or the reachable nodes (\code{"nodes"}).
}
\details{
A vector \code{cost} returns one row per (origin, band), each band the area
reachable within that budget, so the rows nest from the smallest budget out.
Costs are in the network's \code{weight} units. The convex-hull polygon is a
generalisation; use \code{output = "lines"} for the exact reachable network. The
\pkg{sf} package is an optional dependency (Suggests).
}
\examples{
\dontshow{if (requireNamespace("sf", quietly = TRUE)) withAutoprint(\{ # examplesIf}
mk <- function(x1, y1, x2, y2)
  sf::st_linestring(rbind(c(x1, y1), c(x2, y2)))
streets <- sf::st_sfc(
  mk(0, 0, 1, 0), mk(1, 0, 2, 0), mk(0, 0, 0, 1),
  mk(0, 1, 1, 1), mk(1, 0, 1, 1), mk(1, 1, 2, 1), mk(2, 0, 2, 1))
net <- spatial_network(streets)

f <- tempfile(fileext = ".vtr")
write_vtr(data.frame(id = 1L, x = 0, y = 0), f)

tbl(f) |>
  spatial_service_area(net, cost = c(1, 2), output = "lines",
                       coords = c("x", "y")) |>
  collect_sf()
unlink(f)
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=spatial_network]{spatial_network()}} to build the graph, \code{\link[=spatial_route]{spatial_route()}} for
shortest paths, \code{\link[=collect_sf]{collect_sf()}} to materialize as \code{sf}.
}
