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 QA DSM - DEM on 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.

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

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

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

QA report for one CHM/canopy build.

Parameters:
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
dem: TerrainRasterMetadata
dsm: TerrainRasterMetadata
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: object

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

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

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

Return the row as a JSON-serializable mapping.

Return type:

dict[str, object]

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:

CanopyQaReport

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:

VriComparison

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:

CanopyHeightResult

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:

CanopyStructureResult

femic.lidar.canopy.write_canopy_qa_report(report, path)[source]

Write the canopy QA report as pretty-printed JSON.

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

Path

femic.lidar.canopy.write_vri_comparison_csv(comparison, path)[source]

Write polygon-level VRI comparison rows as CSV.

Parameters:
Return type:

Path