R/prepare_stream_network_from_features.R
prepare_stream_network_from_features.RdNormalizes retained linework and produces spatial inspection features for direction and topology findings. Source coordinate order is not evidence of downstream direction. An optional source DEM automatically establishes endpoint-based direction and reverses supported candidates on a copy. Optional consolidation first joins raw continuations into logical links.
prepare_stream_network_from_features(
stream_network,
source_mappings,
configuration,
configuration_streams,
observation,
actor,
review_mode = c("CREATE_REVIEW_FEATURES", "VALIDATE_ONLY"),
dem = NULL,
consolidate = FALSE,
protected_nodes = NULL,
connect = FALSE
)Projected `sf` line features from a retained `stream_network` feature class.
Data frame with exactly one row per source feature. `source_row` is the one-based row number in `stream_network`, `stream_id` is required, and `reach_id` is optional. Governed IDs are UUIDs.
One `stream_network_configuration` row.
The corresponding `stream_network_configuration_stream` rows.
One `stream_network_observation` row whose evidence class is `SOURCE_NETWORK_RETAINED`.
Stable actor or process identifier.
CREATE_REVIEW_FEATURES returns pending INSPECT features; VALIDATE_ONLY assesses but does not apply DEM direction corrections and returns an empty, typed review layer.
Optional single-band terra SpatRaster representing the source Stream DEM, in the linework CRS. NULL skips DEM direction assessment. Automatic correction requires finite DEM values at every endpoint. An incomplete DEM fails before any corrections are returned; VALIDATE_ONLY reports per-endpoint coverage diagnostics to help select the correct input.
Logical; FALSE retains raw segmentation (the compatible default). TRUE builds logical links before DEM orientation, preserving Stream/Reach boundaries and source lineage. Raw endpoint DEM coverage is checked before merging. VALIDATE_ONLY never consolidates or records edits.
Optional exact endpoint POINTs passed to
build_logical_stream_links when consolidating. Boundaries inside source
lines must first be split explicitly; they are not inferred or snapped.
Logical; FALSE preserves the seven-table return. TRUE adds
candidate node and connection tables using connect_stream_network
after direction/geometry assessment. Unresolved direction or geometry defers
the whole assignment with a linked finding and empty typed tables. Directed
cycles also defer assignment. VALIDATE_ONLY never assigns nodes.
A named list with stream_network, stream_network_source, stream_network_review, stream_network_validation_run, and stream_network_validation_issue, stream_network_operation, and stream_network_direction_evidence. Direction evidence is empty without a DEM; operations also record applied logical-link consolidation and node assignment. With connect = TRUE, stream_network_node and stream_network_connection are appended (empty when deferred/validate-only). Evidence records pre-orientation logical-link endpoint values, raster reference, method, action, and an operation link for applied corrections/classifications. Review Shape is the affected candidate line, not a proposed repair. INSPECT decisions cannot authorize geometry changes; concrete repair proposals and their application are later steps.
Checks cover duplicate geometry (including reversed lines), self-intersections, closed segments, intersections involving a line interior, and noncoincident endpoints within the Observation's topology tolerance. Exact shared endpoints are permitted. Intersection findings require interpretation: a crossing is not automatically a hydrologic connection.
This retained-source slice does not detect every network defect: disconnected components, multi-segment cycles, near endpoint-to-interior gaps, and missing Stream/Reach boundary splits remain outside its base checks. Optional connectivity assigns node UUIDs and checks directed cycles. Its WORKING result remains REVIEW_REQUIRED because segment roles and acceptance remain unresolved.