Terrain-Derived Stream Candidates
Purpose
This guide explains P79.4: how FEMIC derives screening-level stream candidates from a native DEM, compares them with public hydrography, and emits a review manifest with explicit caveats.
Candidates are not an authoritative stream layer. They are a review aid for steep-slope, operability, and riparian screening. Field verification and public-hydrography adjudication are required before operational use.
Workflow
Load a native projected-metre DEM.
Optionally fill depressions with a priority-flood pass.
Route D8 flow and accumulate upstream cells.
Threshold flow accumulation into candidate stream cells.
Optionally compare candidates with an aligned public-hydrography raster or vector.
Write candidate/accumulation rasters and a review manifest.
femic lidar streams \
--dem data/lidar/lidarbc/dem/layer_5/2023/dem.tif \
--output-dir data/lidar/streams \
--accumulation-threshold 100 \
--reference data/public/fwa_streams.geojson
Use --instance-root PATH to resolve the default
data/lidar/streams output under an instance root.
from pathlib import Path
from femic.lidar.hydrography import derive_stream_candidates
result = derive_stream_candidates(
Path("data/lidar/dem/layer_5/2023/dem.tif"),
Path("data/lidar/stream_candidates"),
accumulation_threshold=100,
reference_path=Path("data/public/fwa_streams.geojson"),
)
Inputs
The DEM must satisfy the terrain contract:
single band;
projected CRS in metres;
north-up, unrotated;
positive pixel resolution.
Reference hydrography can be:
a raster on exactly the same grid and CRS as the DEM; or
a vector in exactly the same CRS.
Misaligned or different-CRS references are rejected. FEMIC never reprojects or resamples the DEM or the reference.
Parameters
accumulation_threshold: minimum upstream cell count for a candidate.fill_depressions: priority-flood filling before flow routing.reference_path: optional public-hydrography raster or vector.reference_all_touched: rasterize vector cells touched by a feature.
The D8 codes are 1=E, 2=SE, 3=S, 4=SW, 5=W, 6=NW, 7=N, 8=NE. Sinks and invalid cells receive no downstream target.
Outputs
derive_stream_candidates writes:
<output-dir>/
stream_candidates.tif
flow_accumulation.tif
stream_candidates_manifest.json
stream_candidates_review.md
stream_candidates.tif is uint8: 1 = candidate, 0 = background, 255 =
nodata. flow_accumulation.tif is float32 upstream cell count.
Comparison Metrics
When a reference is supplied, the manifest records:
candidate, reference, true-positive, false-positive, and false-negative cells;
precision, recall, F1, and Jaccard;
candidate, reference, and overlap hectares.
Metrics are descriptive. They do not prove hydrological correctness, and a high overlap does not replace field review.
Review Manifest And Caveats
The manifest uses schema femic.lidar.stream_candidates.v1 and records the
source DEM metadata, parameters, outputs, QA counts, comparison metrics,
caveats, and warnings.
stream_candidates_review.md is the human-readable review surface. It
includes a checklist:
compare candidates against current public hydrography;
check DEM artefacts, culverts, bridges, and cutblocks;
confirm the accumulation threshold for the AOI;
record the reviewer and decision before operational use.
Caveats include:
candidates are a screening aid, not an authoritative stream layer;
D8 routing is sensitive to DEM artefacts, culverts, bridges, and resolution;
depression filling changes local flow paths and may create synthetic channels;
No reprojection or resampling was performed.
Limitations
D8 is a single-flow-direction method; it does not model culverts or bridges.
Depression filling can create synthetic gradients in flat or engineered terrain.
The threshold is an AOI-specific screening choice, not a provincial standard.
No stream classification, fish habitat, riparian reserve, or legal determination is made.