Orient lines upstream using DEM endpoint elevations

Source: R/orient_lines_from_dem.R

Generalizes the endpoint comparison used by flowline(). Finite, unequal endpoint elevations support downstream-to-upstream coordinate order: keep a line whose start is lower, or reverse a line whose end is lower. Elevations are sampled from their containing raster cells (terra's simple extraction). No elevation-difference threshold or profile inference is introduced.

orient_lines_from_dem(lines, dem)

Arguments

lines

Nonempty projected sf line features. Attributes, row order, CRS, and geometry types are preserved. MULTILINESTRING rows with one part are supported; rows with several parts require separate normalization.

dem

Single-band terra SpatRaster in the same CRS as lines.

Value

A list with lines (the resulting sf) and direction (one evidence row per input row). Evidence fields are input_row, start_elevation, end_elevation (before correction), start_sample_status, end_sample_status (AVAILABLE, OUTSIDE_DEM_EXTENT, DEM_NODATA, or NOT_SAMPLED), action (KEEP, REVERSE, UNRESOLVED), reason_code, method, dem_band, and dem_source. No governed identifiers are required.

Details

Equal or missing endpoint elevations and true multipart geometries remain unchanged and unresolved. This method does not establish network topology or guarantee downhill flow throughout a line. The caller must supply the appropriate source DEM. Values use its native vertical units; a file reference is recorded when available, but is not a content fingerprint.