% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/network.R
\name{spatial_network}
\alias{spatial_network}
\title{Build a routable network graph from a line layer}
\usage{
spatial_network(
  lines,
  weight = NULL,
  directed = FALSE,
  direction = NULL,
  weight_to = NULL,
  tolerance = 0,
  geom = "geometry",
  crs = NA
)
}
\arguments{
\item{lines}{An \code{sf} or \code{sfc} object of (multi)linestrings, or a \code{vectra_node}
carrying a hex-WKB line geometry column (it is materialised).}

\item{weight}{Name of a column in \code{lines} holding each edge's traversal cost.
\code{NULL} (default) uses the geometry length (\code{\link[sf:st_length]{sf::st_length()}}).}

\item{directed}{If \code{TRUE}, edges are one-way (by \code{direction}, or the digitised
from->to direction). \code{FALSE} (default) makes every edge two-way.}

\item{direction}{Name of a column of one-way codes, used when \code{directed}:
\code{"B"} two-way, \code{"FT"} from->to only, \code{"TF"} to->from only, \code{"N"} closed (the
\code{+}/\code{-}/\code{0} sign convention is also accepted). \code{NULL} uses \code{"FT"} for every
line, or \code{"B"} when \code{weight_to} is given.}

\item{weight_to}{Name of a column holding the reverse-direction cost on a
two-way edge of a directed graph. \code{NULL} reuses \code{weight}.}

\item{tolerance}{Endpoints within this distance (CRS units) are snapped to one
node. \code{0} (default) joins only exactly-coincident endpoints.}

\item{geom, crs}{Geometry column name and CRS, as in \code{\link[=spatial_map]{spatial_map()}}. The CRS
defaults to the one \code{lines} carries.}
}
\value{
A \code{vectra_network} object: the resident graph (an external pointer
plus the node coordinates, edge table, and source-line geometry needed to
snap queries and rebuild routes). Print it to see the node, edge, and
connected-component counts.
}
\description{
Builds the node-edge graph a shortest-path query needs: nodes at line
endpoints, edges weighted by geometry length or a cost column. The graph is
held resident in an external pointer and passed to \code{\link[=spatial_route]{spatial_route()}} and
\code{\link[=spatial_service_area]{spatial_service_area()}}, which stream origin (and destination) batches past
it. This is the network counterpart of a resident \code{sf} \code{y} in \code{\link[=spatial_knn]{spatial_knn()}}:
the graph is the resident budget (bounded by the network size), while the
query side scales by streaming.
}
\details{
Endpoints within \code{tolerance} of each other are snapped to a single node, so a
layer whose touching lines do not share exactly-equal endpoint coordinates
still connects. The input must be (multi)linestrings; a \code{MULTILINESTRING} is
split into its parts, each becoming one edge with the source attributes. Lines
are treated as already split at their junctions (the usual road-network
convention); two lines that merely cross in their interiors are not connected
unless they share an endpoint. The graph and the Dijkstra solver are native C;
\pkg{sf} (an optional dependency, Suggests) supplies only the geometry.
}
\examples{
\dontshow{if (requireNamespace("sf", quietly = TRUE)) withAutoprint(\{ # examplesIf}
# A small grid of streets.
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)
net
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=spatial_route]{spatial_route()}} for shortest paths and origin-destination costs,
\code{\link[=spatial_service_area]{spatial_service_area()}} for reachability and isochrones.
}
