spatial_locate: Locate streamed points along a resident line layer

In vectra: Columnar Query Engine for Larger-than-RAM Data

Locate streamed points along a resident line layer

Description

Streams a large point layer x through the engine and, for each point, finds the nearest line of a small resident line layer and where the point falls along it – linear referencing (sf::st_line_project). Each point gets the identifier of its nearest line, the measure (distance along that line from its start to the point's projection), and the perpendicular distance to the line. With snap = TRUE the point geometry is moved onto the line at that measure. This is the two-layer companion to a per-feature sf::st_line_interpolate, which goes the other way (a measure back to a point); the billion-row point stream never materializes, while line (the reference network) stays resident.

Usage

spatial_locate(
  x,
  line,
  geom = "geometry",
  coords = NULL,
  crs = NA,
  y_id = NULL,
  id_col = "line",
  measure_col = "measure",
  dist_col = "distance",
  snap = FALSE,
  out_geom = NULL,
  flush_rows = NULL
)

Arguments

x	A vectra_node (from tbl(), tbl_tiff(), any verb chain, ...). It is consumed by the stream.
line	An sf or sfc object of the reference lines (the resident layer).
geom	Name of the input geometry column holding hex-WKB or WKT strings. Default "geometry". Ignored when coords is given.
coords	Optional length-2 character vector naming the x and y coordinate columns to assemble point geometry from (e.g. c("x", "y")), for inputs such as tiff_extract_points() output. The coordinate columns are retained.
crs	Coordinate reference system of the input geometry, in any form sf::st_crs() accepts (EPSG integer, WKT, proj string). Defaults to the CRS the upstream node carries, or unknown.
y_id	Optional name of a column in line whose value identifies the matched line in the output. Default NULL uses line's 1-based row index.
id_col, measure_col, dist_col	Names of the output columns holding the matched-line identifier, the measure along the line, and the perpendicular distance. Defaults "line", "measure", "distance".
snap	If TRUE, replace each point's geometry with its projection onto the nearest line. Default FALSE keeps the original points.
out_geom	Name of the output geometry column. Defaults to geom (or "geometry" when coords is used).
flush_rows	Transformed rows buffered before a spill flush. Larger values mean fewer, bigger temporary files. NULL (the default) instead flushes once a spill buffer's size crosses the streaming memory budget (a fraction of vectra_mem(), set with options(vectra.memory = )); an explicit value caps each buffer at that many rows.

Details

Nearest line and distance are sf's sf::st_nearest_feature and sf::st_distance: planar (CRS units) on projected or unprojected planar data, great-circle (metres) on geographic coordinates with spherical geometry on (sf::sf_use_s2()). Points arrive either as a hex-WKB geometry column (geom) or as two coordinate columns (coords). The sf package is an optional dependency (Suggests).

Value

A vectra_node of x's rows – geometry included (or snapped onto the line) – plus the matched-line identifier, the measure, and the perpendicular distance, backed by temporary .vtr spills (removed when the node is garbage-collected) and carrying the input CRS.

See Also

spatial_knn() for nearest neighbours with distances, spatial_join() for a nearest-feature attribute join, spatial_map() with ~ sf::st_line_interpolate(line, .x$m) for the inverse, collect_sf() to materialize as sf.

Examples

line <- sf::st_sfc(
  sf::st_linestring(rbind(c(0, 0), c(10, 0))),
  sf::st_linestring(rbind(c(0, 5), c(0, 15))))
line <- sf::st_sf(road = c("main", "side"), geometry = line)
pts  <- data.frame(id = 1:2, x = c(3, 1), y = c(1, 9))
f <- tempfile(fileext = ".vtr")
write_vtr(pts, f)

# Each point's position along its nearest road.
tbl(f) |>
  spatial_locate(line, coords = c("x", "y"), y_id = "road") |>
  collect()
unlink(f)

vectra documentation built on July 10, 2026, 5:08 p.m.