brushline.integrations.canopy
The CHM raster contract, buffered canopy support, height and cover statistics, optional structure and tree products, VRI comparison evidence, and the canopy support validator.
Canopy, cover, and optional tree support for corridor segments.
The adapter maps a validated CHM to buffered segment support, records height and cover statistics, keeps optional vertical structure and tree products separate, and records a VRI comparison without silently reconciling it. It does not generate a CHM, segment trees, classify species, or decide the low-vegetation state.
- class brushline.integrations.canopy.CanopyBand(*, lower_m: Annotated[float, Ge(ge=0)], upper_m: Annotated[float, Gt(gt=0)], cover_pct: Annotated[float, Ge(ge=0), Le(le=100)])[source]
Bases:
BaseModelOne vertical canopy band.
- Parameters:
lower_m (float) – Lower height bound.
upper_m (float) – Upper height bound.
cover_pct (float) – Cover percentage in the band.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.integrations.canopy.CanopyConfig(*, min_valid_pixels: Annotated[int, Ge(ge=1)] = 4, min_coverage_pct: Annotated[float, Ge(ge=0), Le(le=100)] = 50.0, domain_min_m: Annotated[float | None, Ge(ge=0)] = None, domain_max_m: Annotated[float | None, Gt(gt=0)] = None, max_out_of_domain_fraction: Annotated[float, Ge(ge=0), Le(le=1)] = 0.5)[source]
Bases:
BaseModelAggregation and applicability rules for canopy support.
- Parameters:
min_valid_pixels (int, optional) – Minimum valid CHM cells for observed support. Defaults to
4.min_coverage_pct (float, optional) – Minimum valid-cell percentage for observed support. Defaults to
50.domain_min_m (float or None, optional) – Lower height of the applicability domain.
domain_max_m (float or None, optional) – Upper height of the applicability domain.
max_out_of_domain_fraction (float, optional) – Maximum fraction of valid cells outside the domain. Defaults to
0.5.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.integrations.canopy.CanopyRaster(values: ndarray, min_x: float, min_y: float, max_x: float, max_y: float, crs: str, resolution_m: float, vertical_datum: str, provenance: LidarProductProvenance, nodata: float | None = None)[source]
Bases:
objectA north-up CHM raster with validated provenance.
- Parameters:
values (numpy.ndarray) – Two-dimensional CHM array with row zero at the north edge.
min_x (float) – Western edge.
min_y (float) – Southern edge.
max_x (float) – Eastern edge.
max_y (float) – Northern edge.
crs (str) – Raster CRS.
resolution_m (float) – Cell size in metres.
vertical_datum (str) – Vertical datum.
provenance (LidarProductProvenance) – Validated CHM provenance.
nodata (float or None, optional) – Nodata value.
- class brushline.integrations.canopy.CanopySupport(*, segment_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], state: str, coverage_pct: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)], candidate_pixels: ~typing.Annotated[int, ~annotated_types.Ge(ge=0)], valid_pixels: ~typing.Annotated[int, ~annotated_types.Ge(ge=0)], height_mean_m: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0)] = None, height_median_m: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0)] = None, height_p90_m: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0)] = None, height_p95_m: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0)] = None, height_p99_m: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0)] = None, height_max_m: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0)] = None, cover_2m_pct: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)] = None, cover_5m_pct: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)] = None, cover_10m_pct: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)] = None, cover_20m_pct: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)] = None, structure: list[~brushline.integrations.canopy.CanopyBand] = <factory>, tree: ~brushline.integrations.canopy.TreeSupport | None = None, vri: ~brushline.integrations.canopy.VriComparison | None = None, domain_min_m: float | None = None, domain_max_m: float | None = None, out_of_domain_fraction: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)] = 0.0, buffer_m: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], reason: str = '')[source]
Bases:
BaseModelOne segment’s canopy support.
- Parameters:
segment_id (str) – Segment id.
state (str) –
observed,partial,missing, orout_of_domain.coverage_pct (float) – Valid-cell percentage.
candidate_pixels (int) – Cells within the buffer.
valid_pixels (int) – Cells with finite, non-negative CHM values.
height_mean_m – float or None Height statistics.
height_median_m – float or None Height statistics.
height_p90_m – float or None Height statistics.
height_p95_m – float or None Height statistics.
height_p99_m – float or None Height statistics.
height_max_m – float or None Height statistics.
cover_2m_pct (float or None) – Cover at the four thresholds.
cover_5m_pct (float or None) – Cover at the four thresholds.
cover_10m_pct (float or None) – Cover at the four thresholds.
cover_20m_pct (float or None) – Cover at the four thresholds.
structure (list of CanopyBand) – Optional vertical structure.
tree (TreeSupport or None) – Optional tree product.
vri (VriComparison or None) – Optional VRI comparison.
domain_min_m (float or None) – Applicability domain used.
domain_max_m (float or None) – Applicability domain used.
out_of_domain_fraction (float) – Fraction of valid cells outside the domain.
buffer_m (float) – Segment buffer.
reason (str) – Why support is partial, missing, or out of domain.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- exception brushline.integrations.canopy.CanopySupportError[source]
Bases:
ValueErrorRaised when a CHM or canopy support input is invalid.
- class brushline.integrations.canopy.CanopySupportReport(*, schema_version: ~typing.Literal['brushline.canopy-support.v1'] = 'brushline.canopy-support.v1', created_utc: ~datetime.datetime, crs: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], resolution_m: ~typing.Annotated[float, ~annotated_types.Gt(gt=0)], vertical_datum: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], raster_bounds: ~typing.Annotated[list[float], ~annotated_types.MinLen(min_length=4), ~annotated_types.MaxLen(max_length=4)], source: ~brushline.integrations.lidar.LidarProductProvenance, config: ~brushline.integrations.canopy.CanopyConfig, supports: list[~brushline.integrations.canopy.CanopySupport] = <factory>)[source]
Bases:
BaseModelThe canopy support report for one CHM.
- Parameters:
schema_version ({"brushline.canopy-support.v1"}) – Report schema version.
created_utc (datetime) – Timezone-aware creation time.
crs (str) – Raster CRS.
resolution_m (float) – Raster resolution.
vertical_datum (str) – Raster vertical datum.
raster_bounds (list of float) –
min_x, min_y, max_x, max_y.source (LidarProductProvenance) – CHM provenance.
config (CanopyConfig) – Aggregation and applicability rules.
supports (list of CanopySupport) – Segment support.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.integrations.canopy.TreeSupport(*, segment_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], provenance: ~brushline.integrations.lidar.LidarProductProvenance, tree_count: ~typing.Annotated[int, ~annotated_types.Ge(ge=0)], mean_height_m: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0)] = None, mean_crown_radius_m: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0)] = None, species: list[str] = <factory>, model_card_id: str | None = None, note: str = '')[source]
Bases:
BaseModelOptional individual-tree summary for one segment.
- Parameters:
segment_id (str) – Segment id.
provenance (LidarProductProvenance) – Individual-tree product provenance.
tree_count (int) – Tree count.
mean_height_m (float or None) – Mean tree height.
mean_crown_radius_m (float or None) – Mean crown radius.
species (list of str) – Species labels.
model_card_id (str or None) – Optional model card.
note (str) – Optional note.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.integrations.canopy.VriComparison(*, segment_id: Annotated[str, MinLen(min_length=1)], inventory_vintage: Annotated[str, MinLen(min_length=1)], vri_height_m: Annotated[float, Ge(ge=0)], lidar_height_m: Annotated[float | None, Ge(ge=0)] = None, height_difference_m: float | None = None, vri_cover_pct: Annotated[float, Ge(ge=0), Le(le=100)], lidar_cover_pct: Annotated[float | None, Ge(ge=0), Le(le=100)] = None, cover_difference_pct: float | None = None, source: Annotated[str, MinLen(min_length=1)], model_card_id: str | None = None, note: str = '')[source]
Bases:
BaseModelThe recorded difference between LiDAR support and VRI.
- Parameters:
segment_id (str) – Segment id.
inventory_vintage (str) – VRI vintage.
vri_height_m (float) – VRI height.
lidar_height_m (float or None) – LiDAR height, when available.
height_difference_m (float or None) – LiDAR height minus VRI height.
vri_cover_pct (float) – VRI cover.
lidar_cover_pct (float or None) – LiDAR cover at 10 m, when available.
cover_difference_pct (float or None) – LiDAR cover minus VRI cover.
source (str) – VRI source.
model_card_id (str or None) – Optional VRI model card.
note (str) – Comparison note.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.integrations.canopy.VriObservation(*, segment_id: Annotated[str, MinLen(min_length=1)], height_m: Annotated[float, Ge(ge=0)], cover_pct: Annotated[float, Ge(ge=0), Le(le=100)], vintage: Annotated[str, MinLen(min_length=1)], source: Annotated[str, MinLen(min_length=1)], model_card_id: str | None = None)[source]
Bases:
BaseModelA VRI inventory observation for one segment.
- Parameters:
segment_id (str) – Segment id.
height_m (float) – VRI height.
cover_pct (float) – VRI cover percentage.
vintage (str) – Inventory vintage.
source (str) – Inventory source.
model_card_id (str or None) – Optional model card.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- brushline.integrations.canopy.aggregate_canopy_support(raster: CanopyRaster, segments: list[SegmentWindow], config: CanopyConfig | None = None, *, structures: Mapping[str, Sequence[CanopyBand]] | None = None, tree_supports: Sequence[TreeSupport] | None = None, vri_observations: Sequence[VriObservation] | None = None, created_utc: datetime | None = None) CanopySupportReport[source]
Aggregate a validated CHM to buffered segment support.
- Parameters:
raster (CanopyRaster) – North-up CHM with validated provenance.
segments (list of SegmentWindow) – Buffered segment polylines.
config (CanopyConfig, optional) – Aggregation and applicability rules.
structures (mapping of str to sequence of CanopyBand, optional) – Vertical structure by segment.
tree_supports (sequence of TreeSupport, optional) – Optional individual-tree summaries.
vri_observations (sequence of VriObservation, optional) – VRI inventory observations.
created_utc (datetime, optional) – Report time. Defaults to the current UTC time.
- Returns:
CanopySupportReport – Segment canopy support with provenance and comparison evidence.
- Raises:
CanopySupportError – When a segment CRS differs from the CHM CRS.
- brushline.integrations.canopy.validate_canopy_support(report: CanopySupportReport) ContractValidation[source]
Validate canopy states, statistics, structure, trees, and VRI evidence.
- Parameters:
report (CanopySupportReport) – Report to validate.
- Returns:
ContractValidation – Errors, warnings, and counts.