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

A 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: BaseModel

Aggregation rules for one terrain support run.

Parameters:
  • statistic (str, optional) – mean, median, min, max, or p90.

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

A 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.

cell_centers() → tuple[ndarray, ndarray][source]

Return cell-center x and y arrays.

Returns:

tuple of numpy.ndarray – Two arrays with the raster shape.

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

One segment’s terrain support.

Parameters:
  • segment_id (str) – Segment id.

  • state (str) – observed, partial, or missing.

  • 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, or unknown.

  • 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: ValueError

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

The 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.