brushline.integrations.terrain
The terrain raster contract, buffered segment support, slope/aspect and access-proxy aggregation, and the terrain support validator.
Terrain and slope support for corridor segments.
The adapter consumes a validated FEMIC DEM or DSM provenance and a north-up raster array. It aggregates cells within a buffered segment support, records the statistic, buffer, valid-pixel rule, slope, aspect, terrain class, and an explicit access proxy, and marks partial or missing coverage. It does not reproject, resample, fill, or download a raster.
- class brushline.integrations.terrain.SegmentWindow(*, segment_id: Annotated[str, MinLen(min_length=1)], coordinates: Annotated[list[tuple[float, float]], MinLen(min_length=2)], buffer_m: Annotated[float, Ge(ge=0)] = 10.0, crs: str = 'EPSG:3005')[source]
Bases:
BaseModelA buffered corridor segment for terrain aggregation.
- Parameters:
segment_id (str) – Segment id.
coordinates (list of tuple of float) – Polyline vertices in the raster CRS.
buffer_m (float, optional) – Buffer distance in metres. Defaults to
10.crs (str, optional) – Segment CRS. It must match the raster CRS.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.integrations.terrain.TerrainConfig(*, statistic: str = 'mean', min_valid_pixels: Annotated[int, Ge(ge=1)] = 4, min_coverage_pct: Annotated[float, Ge(ge=0), Le(le=100)] = 50.0, access_slope_deg: Annotated[float, Gt(gt=0)] = 30.0)[source]
Bases:
BaseModelAggregation rules for one terrain support run.
- Parameters:
statistic (str, optional) –
mean,median,min,max, orp90.min_valid_pixels (int, optional) – Minimum slope-valid cells for observed support. Defaults to
4.min_coverage_pct (float, optional) – Minimum valid-cell percentage for observed support. Defaults to
50.access_slope_deg (float, optional) – Slope at which the access proxy reaches zero. Defaults to
30.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.integrations.terrain.TerrainRaster(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 terrain raster with validated provenance.
- Parameters:
values (numpy.ndarray) – Two-dimensional elevation array with row zero at the north edge.
min_x (float) – Western raster edge.
min_y (float) – Southern raster edge.
max_x (float) – Eastern raster edge.
max_y (float) – Northern raster edge.
crs (str) – Raster CRS.
resolution_m (float) – Cell size in metres.
vertical_datum (str) – Vertical datum.
provenance (LidarProductProvenance) – Validated DEM/DSM provenance.
nodata (float or None, optional) – Nodata value.
- class brushline.integrations.terrain.TerrainSupport(*, segment_id: Annotated[str, MinLen(min_length=1)], state: str, coverage_pct: Annotated[float, Ge(ge=0), Le(le=100)], candidate_pixels: Annotated[int, Ge(ge=0)], valid_pixels: Annotated[int, Ge(ge=0)], elevation_m: float | None = None, slope_deg: Annotated[float | None, Ge(ge=0), Le(le=90)] = None, aspect_deg: Annotated[float | None, Ge(ge=0), Lt(lt=360)] = None, terrain_class: str = 'missing', access_proxy: Annotated[float | None, Ge(ge=0), Le(le=1)] = None, access_class: str = 'unknown', statistic: str = 'mean', buffer_m: Annotated[float, Ge(ge=0)], reason: str = '')[source]
Bases:
BaseModelOne segment’s terrain support.
- Parameters:
segment_id (str) – Segment id.
state (str) –
observed,partial, ormissing.coverage_pct (float) – Valid-cell percentage.
candidate_pixels (int) – Cells within the buffer.
valid_pixels (int) – Cells with valid elevation and slope.
elevation_m (float or None) – Aggregated elevation.
slope_deg (float or None) – Aggregated slope.
aspect_deg (float or None) – Circular mean aspect.
terrain_class (str) – Slope class.
access_proxy (float or None) – Slope-derived access proxy from 0 to 1. It is not an operability verdict.
access_class (str) –
high,moderate,low, orunknown.statistic (str) – Aggregation statistic.
buffer_m (float) – Segment buffer.
reason (str, optional) – Why support is partial or missing.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- exception brushline.integrations.terrain.TerrainSupportError[source]
Bases:
ValueErrorRaised when a terrain raster or segment support cannot be aggregated.
- class brushline.integrations.terrain.TerrainSupportReport(*, schema_version: ~typing.Literal['brushline.terrain-support.v1'] = 'brushline.terrain-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.terrain.TerrainConfig, supports: list[~brushline.integrations.terrain.TerrainSupport] = <factory>)[source]
Bases:
BaseModelThe terrain support report for one raster.
- Parameters:
schema_version ({"brushline.terrain-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) – Validated DEM/DSM provenance.
config (TerrainConfig) – Aggregation rules.
supports (list of TerrainSupport) – Segment support records.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- brushline.integrations.terrain.aggregate_terrain_support(raster: TerrainRaster, segments: list[SegmentWindow], config: TerrainConfig | None = None, *, created_utc: datetime | None = None) TerrainSupportReport[source]
Aggregate a validated terrain raster to buffered segment support.
- Parameters:
raster (TerrainRaster) – North-up DEM or DSM with validated provenance.
segments (list of SegmentWindow) – Buffered segment polylines.
config (TerrainConfig, optional) – Aggregation rules.
created_utc (datetime, optional) – Report time. Defaults to the current UTC time.
- Returns:
TerrainSupportReport – Segment support with coverage and provenance.
- Raises:
TerrainSupportError – When a segment CRS differs from the raster CRS or the configuration is invalid.
- brushline.integrations.terrain.segment_buffer_mask(x_grid: ndarray, y_grid: ndarray, coordinates: ndarray, buffer_m: float) ndarray[source]
Return cells whose centers fall within a buffered polyline.
- Parameters:
x_grid (numpy.ndarray) – Cell-center x coordinates.
y_grid (numpy.ndarray) – Cell-center y coordinates.
coordinates (numpy.ndarray) – Polyline vertices.
buffer_m (float) – Buffer distance.
- Returns:
numpy.ndarray – Boolean mask with the grid shape.
- brushline.integrations.terrain.validate_terrain_support(report: TerrainSupportReport) ContractValidation[source]
Validate terrain support states, ranges, and provenance.
- Parameters:
report (TerrainSupportReport) – Report to validate.
- Returns:
ContractValidation – Errors, warnings, and counts.