femic.lidar.hydrography Module
The femic.lidar.hydrography module derives screening-level stream
candidates from a native DEM. It fills depressions, routes D8 flow, thresholds
flow accumulation, compares candidates with aligned public hydrography, and
writes a JSON review manifest plus a Markdown caveat report.
Use this page when you are deriving, reviewing, or comparing terrain-derived stream candidates rather than compiling general terrain products.
Start Here If…
Use this page first if you are trying to:
derive screening stream candidates from a DEM;
resume or tune a D8 flow-accumulation workflow;
compare candidate streams with an aligned public-hydrography raster or vector;
inspect comparison precision, recall, F1, or Jaccard; or
review the mandatory caveats before operational use.
Typical Usage
from pathlib import Path
from femic.lidar.hydrography import (
compare_stream_candidates,
derive_stream_candidates,
)
result = derive_stream_candidates(
Path("data/lidar/dem.tif"),
Path("data/lidar/stream_candidates"),
accumulation_threshold=100,
reference_path=Path("data/public/fwa_streams.geojson"),
)
metrics = compare_stream_candidates(candidate_mask, reference_mask)
Key Entry Surfaces
fill_dem_depressions()Priority-flood depression filling with an isolation count.derive_d8_flow_direction()D8 direction codes and downstream flat indices.accumulate_d8_flow()Upstream-cell accumulation over the D8 network.compare_stream_candidates()Overlap and agreement metrics for candidate/reference masks.derive_stream_candidates()End-to-end candidate workflow with review manifest and caveat report.write_stream_candidate_manifest()Persist the JSON review manifest.write_stream_candidate_review()Persist the human-readable caveat and checklist report.
Cross-References
Terrain-derived stream candidates with explicit review caveats.
P79.4 derives screening-level D8 flow paths from a native DEM, compares them with an aligned public-hydrography reference, and writes a review manifest and caveat report. Candidates are not authoritative streams.
- exception femic.lidar.hydrography.StreamCandidateError[source]
Bases:
RuntimeErrorRaised when stream-candidate inputs or outputs are invalid.
- class femic.lidar.hydrography.StreamCandidateManifest(generated_utc, source, parameters, outputs, qa, comparison, caveats=('Terrain-derived candidates are a screening aid, not an authoritative stream layer.', 'D8 routing is sensitive to DEM artefacts, culverts, bridges, and source resolution.', 'Depression filling changes local flow paths and may create synthetic channels.', 'Candidates require field or public-hydrography review before riparian, operability, or legal use.', 'No reprojection or resampling was performed.'), warnings=(), schema_version='femic.lidar.stream_candidates.v1')[source]
Bases:
objectReview manifest for one terrain-derived stream-candidate build.
- Parameters:
generated_utc (str)
source (TerrainRasterMetadata)
parameters (dict[str, object])
outputs (dict[str, str])
qa (dict[str, object])
comparison (StreamComparison | None)
caveats (tuple[str, ...])
warnings (tuple[str, ...])
schema_version (str)
- caveats: tuple[str, ...] = ('Terrain-derived candidates are a screening aid, not an authoritative stream layer.', 'D8 routing is sensitive to DEM artefacts, culverts, bridges, and source resolution.', 'Depression filling changes local flow paths and may create synthetic channels.', 'Candidates require field or public-hydrography review before riparian, operability, or legal use.', 'No reprojection or resampling was performed.')
- comparison: StreamComparison | None
- generated_utc: str
- outputs: dict[str, str]
- parameters: dict[str, object]
- qa: dict[str, object]
- schema_version: str = 'femic.lidar.stream_candidates.v1'
- source: TerrainRasterMetadata
- to_dict()[source]
Return the manifest as a JSON-serializable mapping.
- Return type:
dict[str, object]
- warnings: tuple[str, ...] = ()
- class femic.lidar.hydrography.StreamCandidateResult(manifest, output_dir, stream_path, accumulation_path, manifest_path, review_path)[source]
Bases:
objectPaths and manifest returned by a stream-candidate build.
- Parameters:
manifest (StreamCandidateManifest)
output_dir (Path)
stream_path (Path)
accumulation_path (Path)
manifest_path (Path)
review_path (Path)
- accumulation_path: Path
- manifest: StreamCandidateManifest
- manifest_path: Path
- output_dir: Path
- review_path: Path
- stream_path: Path
- class femic.lidar.hydrography.StreamComparison(candidate_cells, reference_cells, true_positive, false_positive, false_negative, precision, recall, f1, jaccard, candidate_area_ha=None, reference_area_ha=None, overlap_area_ha=None)[source]
Bases:
objectOverlap metrics between candidate and reference stream masks.
- Parameters:
candidate_cells (int)
reference_cells (int)
true_positive (int)
false_positive (int)
false_negative (int)
precision (float | None)
recall (float | None)
f1 (float | None)
jaccard (float | None)
candidate_area_ha (float | None)
reference_area_ha (float | None)
overlap_area_ha (float | None)
- candidate_area_ha: float | None = None
- candidate_cells: int
- f1: float | None
- false_negative: int
- false_positive: int
- jaccard: float | None
- overlap_area_ha: float | None = None
- precision: float | None
- recall: float | None
- reference_area_ha: float | None = None
- reference_cells: int
- to_dict()[source]
Return the comparison as a JSON-serializable mapping.
- Return type:
dict[str, object]
- true_positive: int
- femic.lidar.hydrography.accumulate_d8_flow(elevation, downstream, valid)[source]
Accumulate one cell of area downstream over a D8 network.
- Parameters:
elevation (ndarray)
downstream (ndarray)
valid (ndarray)
- Return type:
ndarray
- femic.lidar.hydrography.compare_stream_candidates(candidate_mask, reference_mask, *, pixel_area_m2=None)[source]
Compare candidate and reference stream masks.
- Parameters:
candidate_mask (ndarray)
reference_mask (ndarray)
pixel_area_m2 (float | None)
- Return type:
- femic.lidar.hydrography.derive_d8_flow_direction(elevation, valid, *, resolution_x, resolution_y)[source]
Derive D8 flow directions and downstream flat indices.
Codes are 1=E, 2=SE, 3=S, 4=SW, 5=W, 6=NW, 7=N, 8=NE. Sinks and invalid cells receive
-1.- Parameters:
elevation (ndarray)
valid (ndarray)
resolution_x (float)
resolution_y (float)
- Return type:
tuple[ndarray, ndarray]
- femic.lidar.hydrography.derive_stream_candidates(source_dem_path, output_dir, *, accumulation_threshold=100, fill_depressions=True, reference_path=None, reference_all_touched=False, generated_utc=None)[source]
Derive screening stream candidates from a native DEM.
The workflow fills depressions (optional), routes D8 flow, thresholds flow accumulation, writes candidate and accumulation rasters, and emits a JSON review manifest plus a Markdown caveat report. It never reprojects or resamples the DEM.
- Parameters:
source_dem_path (Path)
output_dir (Path)
accumulation_threshold (int)
fill_depressions (bool)
reference_path (Path | None)
reference_all_touched (bool)
generated_utc (str | None)
- Return type:
- femic.lidar.hydrography.fill_dem_depressions(elevation, valid, *, epsilon=1e-06)[source]
Fill depressions with a priority-flood pass.
Returns the filled elevation grid and the count of valid cells that were not connected to the outer boundary and therefore were left unfilled.
- Parameters:
elevation (ndarray)
valid (ndarray)
epsilon (float)
- Return type:
tuple[ndarray, int]
- femic.lidar.hydrography.write_stream_candidate_manifest(manifest, path)[source]
Write the stream-candidate review manifest as JSON.
- Parameters:
manifest (StreamCandidateManifest)
path (Path)
- Return type:
Path
- femic.lidar.hydrography.write_stream_candidate_review(manifest, path)[source]
Write a human-readable caveat and review report.
- Parameters:
manifest (StreamCandidateManifest)
path (Path)
- Return type:
Path