femic.lidar.canopy Module
The femic.lidar.canopy module owns FEMIC’s native CHM, canopy structure,
and VRI uncertainty comparison. It derives DSM - DEM on exactly aligned
grids, summarizes height and cover, and records VRI comparison metrics. It does
not reproject, resample, segment trees, or claim field-level inventory accuracy.
Use this page when you are building or reviewing canopy height and cover products rather than terrain, hydrography, or product packaging.
Start Here If…
Use this page first if you are trying to:
derive a CHM from aligned LidarBC DSM and DEM tiles;
summarize canopy height percentiles and cover thresholds;
compare CHM p95/cover with VRI height/closure;
debug a grid-alignment, vertical-datum, or VRI-field failure; or
inspect the canopy QA report.
Typical Usage
femic lidar canopy \
--dem data/lidar/dem.tif \
--dsm data/lidar/dsm.tif \
--output-dir data/lidar/canopy \
--vri data/input/vri.gpkg \
--vri-height-field proj_height_1 \
--vri-cover-field crown_closure
from pathlib import Path
from femic.lidar.canopy import (
build_canopy_products,
compare_canopy_to_vri,
derive_canopy_height_model,
)
chm = derive_canopy_height_model(
Path("data/lidar/dsm.tif"),
Path("data/lidar/dem.tif"),
Path("data/lidar/chm.tif"),
vertical_datum="CGVD2013",
)
report = build_canopy_products(
Path("data/lidar/dsm.tif"),
Path("data/lidar/dem.tif"),
Path("data/lidar/canopy"),
)
comparison = compare_canopy_to_vri(
chm.path,
Path("data/input/vri.gpkg"),
)
Key Entry Surfaces
derive_canopy_height_model()Derive and QADSM - DEMon an aligned native grid.derive_canopy_structure()Summarize height percentiles and cover thresholds from a CHM.compare_canopy_to_vri()Compare polygon-level CHM p95/cover with VRI fields.build_canopy_products()Build the CHM, structure JSON, optional VRI comparison, and QA reports.CanopyQaReportReview artifact with source grids, CHM, structure, VRI comparison, caveats, and warnings.
Cross-References
Native-resolution CHM, canopy structure, and VRI uncertainty helpers.
P79.7 derives a canopy height model from aligned DSM/DEM rasters, summarizes canopy height and cover, and compares CHM evidence with VRI inventory fields. It does not reproject, resample, segment individual trees, or claim field-level inventory accuracy.
- class femic.lidar.canopy.CanopyHeightResult(path, dsm_path, dem_path, metadata, dsm_metadata, dem_metadata, vertical_datum, generated_utc, valid_pixels, nodata_pixels, negative_pixels, clamped_negative, height_metrics, cover_fractions, valid_area_ha, warnings=())[source]
Bases:
objectDerived CHM raster and its QA summary.
- Parameters:
path (Path)
dsm_path (Path)
dem_path (Path)
metadata (TerrainRasterMetadata)
dsm_metadata (TerrainRasterMetadata)
dem_metadata (TerrainRasterMetadata)
vertical_datum (str | None)
generated_utc (str)
valid_pixels (int)
nodata_pixels (int)
negative_pixels (int)
clamped_negative (bool)
height_metrics (dict[str, object])
cover_fractions (dict[str, float])
valid_area_ha (float)
warnings (tuple[str, ...])
- clamped_negative: bool
- cover_fractions: dict[str, float]
- dem_metadata: TerrainRasterMetadata
- dem_path: Path
- dsm_metadata: TerrainRasterMetadata
- dsm_path: Path
- generated_utc: str
- height_metrics: dict[str, object]
- metadata: TerrainRasterMetadata
- negative_pixels: int
- nodata_pixels: int
- path: Path
- to_dict()[source]
Return the CHM result as a JSON-serializable mapping.
- Return type:
dict[str, object]
- valid_area_ha: float
- valid_pixels: int
- vertical_datum: str | None
- warnings: tuple[str, ...] = ()
- exception femic.lidar.canopy.CanopyProcessingError[source]
Bases:
RuntimeErrorRaised when canopy inputs, grids, or VRI comparisons are invalid.
- class femic.lidar.canopy.CanopyQaReport(generated_utc, dsm, dem, chm, structure, vri_comparison=None, caveats=('CHM is DSM minus DEM on exactly aligned native grids. It is not a field inventory.', 'DSM and DEM must share the same CRS, transform, resolution, and vertical datum.', 'No reprojection or resampling is performed.', 'VRI comparisons are uncertainty evidence, not a field-accuracy claim.'), warnings=(), schema_version='femic.lidar.canopy_qa.v1')[source]
Bases:
objectQA report for one CHM/canopy build.
- Parameters:
generated_utc (str)
dsm (TerrainRasterMetadata)
dem (TerrainRasterMetadata)
chm (CanopyHeightResult)
structure (CanopyStructureResult)
vri_comparison (VriComparison | None)
caveats (tuple[str, ...])
warnings (tuple[str, ...])
schema_version (str)
- caveats: tuple[str, ...] = ('CHM is DSM minus DEM on exactly aligned native grids. It is not a field inventory.', 'DSM and DEM must share the same CRS, transform, resolution, and vertical datum.', 'No reprojection or resampling is performed.', 'VRI comparisons are uncertainty evidence, not a field-accuracy claim.')
- chm: CanopyHeightResult
- generated_utc: str
- schema_version: str = 'femic.lidar.canopy_qa.v1'
- structure: CanopyStructureResult
- to_dict()[source]
Return the canopy QA report as a JSON-serializable mapping.
- Return type:
dict[str, object]
- vri_comparison: VriComparison | None = None
- warnings: tuple[str, ...] = ()
- class femic.lidar.canopy.CanopyStructureResult(path, metadata, thresholds_m, generated_utc, valid_pixels, nodata_pixels, valid_area_ha, height_metrics, cover_fractions, warnings=(), schema_version='femic.lidar.canopy_structure.v1')[source]
Bases:
objectCanopy height and cover summary for one CHM raster.
- Parameters:
path (Path)
metadata (TerrainRasterMetadata)
thresholds_m (tuple[float, ...])
generated_utc (str)
valid_pixels (int)
nodata_pixels (int)
valid_area_ha (float)
height_metrics (dict[str, object])
cover_fractions (dict[str, float])
warnings (tuple[str, ...])
schema_version (str)
- cover_fractions: dict[str, float]
- generated_utc: str
- height_metrics: dict[str, object]
- metadata: TerrainRasterMetadata
- nodata_pixels: int
- path: Path
- schema_version: str = 'femic.lidar.canopy_structure.v1'
- thresholds_m: tuple[float, ...]
- to_dict()[source]
Return the canopy structure result as a JSON-serializable mapping.
- Return type:
dict[str, object]
- valid_area_ha: float
- valid_pixels: int
- warnings: tuple[str, ...] = ()
- class femic.lidar.canopy.VriComparison(vri_path, height_field, cover_field, chm_height_metric, polygon_count, matched_count, skipped_count, height_bias_m, height_mae_m, height_rmse_m, cover_bias_pct, cover_mae_pct, rows, generated_utc, warnings=())[source]
Bases:
objectSummary uncertainty comparison between CHM and VRI polygons.
- Parameters:
vri_path (Path)
height_field (str)
cover_field (str | None)
chm_height_metric (str)
polygon_count (int)
matched_count (int)
skipped_count (int)
height_bias_m (float | None)
height_mae_m (float | None)
height_rmse_m (float | None)
cover_bias_pct (float | None)
cover_mae_pct (float | None)
rows (tuple[VriComparisonRow, ...])
generated_utc (str)
warnings (tuple[str, ...])
- chm_height_metric: str
- cover_bias_pct: float | None
- cover_field: str | None
- cover_mae_pct: float | None
- generated_utc: str
- height_bias_m: float | None
- height_field: str
- height_mae_m: float | None
- height_rmse_m: float | None
- matched_count: int
- polygon_count: int
- rows: tuple[VriComparisonRow, ...]
- skipped_count: int
- to_dict()[source]
Return the comparison as a JSON-serializable mapping.
- Return type:
dict[str, object]
- vri_path: Path
- warnings: tuple[str, ...] = ()
- class femic.lidar.canopy.VriComparisonRow(polygon_id, vri_height_m, chm_p95_m, chm_mean_m, height_delta_m, vri_cover_pct, chm_cover_pct, cover_delta_pct, valid_pixels)[source]
Bases:
objectOne polygon-level CHM versus VRI comparison.
- Parameters:
polygon_id (str)
vri_height_m (float | None)
chm_p95_m (float | None)
chm_mean_m (float | None)
height_delta_m (float | None)
vri_cover_pct (float | None)
chm_cover_pct (float | None)
cover_delta_pct (float | None)
valid_pixels (int)
- chm_cover_pct: float | None
- chm_mean_m: float | None
- chm_p95_m: float | None
- cover_delta_pct: float | None
- height_delta_m: float | None
- polygon_id: str
- valid_pixels: int
- vri_cover_pct: float | None
- vri_height_m: float | None
- femic.lidar.canopy.build_canopy_products(dsm_path, dem_path, output_dir, *, clamp_negative=True, nodata=None, vertical_datum=None, thresholds_m=(2.0, 5.0, 10.0, 20.0), vri_path=None, vri_height_field='proj_height_1', vri_cover_field='crown_closure', vri_id_field='feature_id', generated_utc=None)[source]
Build CHM/canopy products, optional VRI comparison, and QA reports.
- Parameters:
dsm_path (Path)
dem_path (Path)
output_dir (Path)
clamp_negative (bool)
nodata (float | None)
vertical_datum (str | None)
thresholds_m (Sequence[float])
vri_path (Path | None)
vri_height_field (str)
vri_cover_field (str | None)
vri_id_field (str)
generated_utc (str | None)
- Return type:
- femic.lidar.canopy.compare_canopy_to_vri(chm_path, vri_path, *, height_field='proj_height_1', cover_field='crown_closure', id_field='feature_id', min_valid_pixels=10, cover_threshold_m=2.0, generated_utc=None)[source]
Compare polygon-level CHM p95/cover with VRI height/cover fields.
- Parameters:
chm_path (Path)
vri_path (Path)
height_field (str)
cover_field (str | None)
id_field (str)
min_valid_pixels (int)
cover_threshold_m (float)
generated_utc (str | None)
- Return type:
- femic.lidar.canopy.derive_canopy_height_model(dsm_path, dem_path, output_path, *, clamp_negative=True, nodata=None, vertical_datum=None, thresholds_m=(2.0, 5.0, 10.0, 20.0), generated_utc=None)[source]
Derive CHM = DSM - DEM on exactly aligned native grids.
- Parameters:
dsm_path (Path)
dem_path (Path)
output_path (Path)
clamp_negative (bool)
nodata (float | None)
vertical_datum (str | None)
thresholds_m (Sequence[float])
generated_utc (str | None)
- Return type:
- femic.lidar.canopy.derive_canopy_structure(chm_path, *, thresholds_m=(2.0, 5.0, 10.0, 20.0), generated_utc=None)[source]
Summarize canopy height and cover from a CHM raster.
- Parameters:
chm_path (Path)
thresholds_m (Sequence[float])
generated_utc (str | None)
- Return type:
- femic.lidar.canopy.write_canopy_qa_report(report, path)[source]
Write the canopy QA report as pretty-printed JSON.
- Parameters:
report (CanopyQaReport)
path (Path)
- Return type:
Path
- femic.lidar.canopy.write_canopy_qa_summary_csv(report, path)[source]
Write a one-row-per-product canopy QA summary CSV.
- Parameters:
report (CanopyQaReport)
path (Path)
- Return type:
Path
- femic.lidar.canopy.write_vri_comparison_csv(comparison, path)[source]
Write polygon-level VRI comparison rows as CSV.
- Parameters:
comparison (VriComparison)
path (Path)
- Return type:
Path