% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/network.R
\name{spatial_route}
\alias{spatial_route}
\title{Shortest paths and origin-destination costs over a network}
\usage{
spatial_route(
  x,
  network,
  to,
  to_id = NULL,
  geometry = TRUE,
  cost_col = "cost",
  dest_col = "destination",
  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{to}{An \code{sf}/\code{sfc} of destination points. One destination routes every
origin to it; several produce one row per (origin, destination).}

\item{to_id}{Optional column in \code{to} identifying each destination in the
output. \code{NULL} (default) uses the 1-based destination index.}

\item{geometry}{If \code{TRUE} (default) each row carries the route line; if
\code{FALSE} only the cost column (the cost-matrix form, no geometry).}

\item{cost_col, dest_col}{Names of the output cost and destination-identifier
columns. Defaults \code{"cost"}, \code{"destination"}.}

\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, destination) carrying \code{x}'s
attributes, the destination id, the cost, and (when \code{geometry = TRUE}) the
route 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 the shortest path to one or more destinations \code{to}. Each
origin and destination is snapped to its nearest graph node; the solver
(native-C Dijkstra) returns one row per (origin, destination) pair with the
total cost and, by default, the route geometry. With \code{geometry = FALSE} only
the cost is returned, so a destination set per origin yields the
origin-destination cost matrix in long form. The billion-origin stream never
materialises; the graph stays resident.
}
\details{
An unreachable destination returns an infinite cost and an empty geometry
rather than dropping the row, so a cost matrix stays rectangular. Snapping is
to the nearest node, so place origins and destinations on or near the network;
costs are in the units of the network's \code{weight} (or CRS length units when the
graph was built from geometry length). 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 = 1:2, x = c(0, 0), y = c(0, 1)), f)
dest <- sf::st_sfc(sf::st_point(c(2, 1)))

tbl(f) |>
  spatial_route(net, to = dest, coords = c("x", "y")) |>
  collect_sf()
unlink(f)
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=spatial_network]{spatial_network()}} to build the graph, \code{\link[=spatial_service_area]{spatial_service_area()}} for
reachability, \code{\link[=collect_sf]{collect_sf()}} to materialize routes as \code{sf}.
}
