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: RuntimeError

Raised 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: object

Review 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: object

Paths 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
to_dict()[source]

Return the result as a JSON-serializable mapping.

Return type:

dict[str, object]

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: object

Overlap 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:

StreamComparison

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:

StreamCandidateResult

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:
Return type:

Path

femic.lidar.hydrography.write_stream_candidate_review(manifest, path)[source]

Write a human-readable caveat and review report.

Parameters:
Return type:

Path