a5_line_string_to_cells: Cells traced by a great-circle linestring

In a5R: 'A5' Discrete Global Grid System

Cells traced by a great-circle linestring

Description

Returns, for each linestring feature, the A5 cells at resolution whose pentagons the great-circle path through its waypoints crosses. Each path's cells are uncompacted and in order along it, with duplicates removed first-seen; a MULTILINESTRING feature's parts are traced in order into one path.

Usage

a5_line_string_to_cells(x, resolution, simplify = TRUE)

Arguments

x	A linestring-like geometry. One of: Any geometry handleable by wk::wk_handle() containing one or more LINESTRING / MULTILINESTRING features. A SpatVector of linestrings (requires the terra package). A two-column numeric matrix (cbind(lon, lat)) of waypoints. A data.frame with columns lon and lat.
resolution	Integer scalar target resolution (0–30).
simplify	Logical scalar. If TRUE (default), return one flat a5_cell vector with the paths of every feature concatenated in feature order; a cell crossed by several features appears once per feature. If FALSE, return an a5_cell_list with one path per feature, suitable for a list column.

Details

Consecutive waypoints are connected by great-circle arcs (not rhumb lines or planar segments), so antimeridian-crossing paths work transparently when written in unwrapped lon/lat. A line string with a single waypoint gives the cell containing it.

A path is an ordered sequence, so the result is a vector of cells rather than an a5_covering; use as_a5_covering() to treat the cells a path crosses as a set.

Matrix and data.frame inputs are treated as a single linestring; for multi-feature data, pass an sf, sfc, wk, or SpatVector geometry instead.

Value

An a5_cell vector at resolution, or an a5_cell_list when simplify = FALSE. A missing or empty geometry contributes no cells (an empty element in the list form).

See Also

a5_polygon_to_cells(), a5_grid_disk().

Examples

line <- wk::wkt("LINESTRING (2.35 48.86, -0.13 51.51)")
cells <- a5_line_string_to_cells(line, resolution = 6)
cells

# One path per feature
lines <- wk::wkt(c(
  "LINESTRING (2.35 48.86, -0.13 51.51)",
  "LINESTRING (2.35 48.86, 4.83 45.76)"
))
paths <- a5_line_string_to_cells(lines, resolution = 6, simplify = FALSE)
lengths(paths)

a5R documentation built on Oct. 19, 2026, 5:08 p.m.