"""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.
"""
from __future__ import annotations
import itertools
import math
from dataclasses import dataclass
from datetime import UTC, datetime
from typing import Literal
import numpy as np
from pydantic import BaseModel, ConfigDict, Field, model_validator
from brushline.integrations.lidar import LidarProductProvenance
from brushline.model.validation import ContractValidation, check_duplicates
TERRAIN_SUPPORT_SCHEMA_VERSION: Literal["brushline.terrain-support.v1"] = (
"brushline.terrain-support.v1"
)
TERRAIN_STATISTICS: tuple[str, ...] = ("mean", "median", "min", "max", "p90")
TERRAIN_STATES: tuple[str, ...] = ("observed", "partial", "missing")
TERRAIN_CLASSES: tuple[str, ...] = ("flat", "gentle", "moderate", "steep", "very_steep")
ACCESS_CLASSES: tuple[str, ...] = ("high", "moderate", "low", "unknown")
TERRAIN_PRODUCT_KINDS: frozenset[str] = frozenset({"dem", "dsm"})
[docs]
class TerrainSupportError(ValueError):
"""Raised when a terrain raster or segment support cannot be aggregated."""
[docs]
class SegmentWindow(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 = ConfigDict(extra="forbid", frozen=True)
segment_id: str = Field(min_length=1)
coordinates: list[tuple[float, float]] = Field(min_length=2)
buffer_m: float = Field(default=10.0, ge=0)
crs: str = "EPSG:3005"
[docs]
class TerrainConfig(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 = ConfigDict(extra="forbid", frozen=True)
statistic: str = "mean"
min_valid_pixels: int = Field(default=4, ge=1)
min_coverage_pct: float = Field(default=50.0, ge=0, le=100)
access_slope_deg: float = Field(default=30.0, gt=0)
[docs]
class TerrainSupport(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 = ConfigDict(extra="forbid", frozen=True)
segment_id: str = Field(min_length=1)
state: str
coverage_pct: float = Field(ge=0, le=100)
candidate_pixels: int = Field(ge=0)
valid_pixels: int = Field(ge=0)
elevation_m: float | None = None
slope_deg: float | None = Field(default=None, ge=0, le=90)
aspect_deg: float | None = Field(default=None, ge=0, lt=360)
terrain_class: str = "missing"
access_proxy: float | None = Field(default=None, ge=0, le=1)
access_class: str = "unknown"
statistic: str = "mean"
buffer_m: float = Field(ge=0)
reason: str = ""
@model_validator(mode="after")
def _state_consistency(self) -> TerrainSupport:
if self.state not in TERRAIN_STATES:
raise ValueError(f"unknown terrain state {self.state!r}")
if self.valid_pixels > self.candidate_pixels:
raise ValueError("valid_pixels cannot exceed candidate_pixels")
if self.state == "missing":
if self.valid_pixels != 0:
raise ValueError("a missing support must have zero valid pixels")
if any(
value is not None for value in (self.elevation_m, self.slope_deg, self.aspect_deg)
):
raise ValueError("a missing support must have no terrain values")
if self.state in ("observed", "partial") and self.elevation_m is None:
raise ValueError("observed or partial support needs elevation")
if self.terrain_class not in (*TERRAIN_CLASSES, "missing"):
raise ValueError(f"unknown terrain class {self.terrain_class!r}")
if self.access_class not in ACCESS_CLASSES:
raise ValueError(f"unknown access class {self.access_class!r}")
return self
[docs]
class TerrainSupportReport(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 = ConfigDict(extra="forbid")
schema_version: Literal["brushline.terrain-support.v1"] = TERRAIN_SUPPORT_SCHEMA_VERSION
created_utc: datetime
crs: str = Field(min_length=1)
resolution_m: float = Field(gt=0)
vertical_datum: str = Field(min_length=1)
raster_bounds: list[float] = Field(min_length=4, max_length=4)
source: LidarProductProvenance
config: TerrainConfig
supports: list[TerrainSupport] = Field(default_factory=list)
[docs]
@dataclass(frozen=True)
class TerrainRaster:
"""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.
"""
values: np.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
def __post_init__(self) -> None:
"""Validate the raster shape, provenance, and bounds."""
if self.values.ndim != 2 or self.values.size == 0:
raise TerrainSupportError("terrain values must be a non-empty 2D array")
if self.max_x <= self.min_x or self.max_y <= self.min_y:
raise TerrainSupportError("terrain bounds must have positive area")
if self.resolution_m <= 0:
raise TerrainSupportError("terrain resolution must be positive")
if not self.crs or not self.vertical_datum:
raise TerrainSupportError("terrain CRS and vertical datum are required")
if self.provenance.product not in TERRAIN_PRODUCT_KINDS:
raise TerrainSupportError("terrain provenance must be a DEM or DSM")
if self.provenance.crs != self.crs:
raise TerrainSupportError("terrain provenance CRS does not match the raster")
if self.provenance.resolution_m is not None and not math.isclose(
self.provenance.resolution_m, self.resolution_m
):
raise TerrainSupportError("terrain provenance resolution does not match the raster")
if self.provenance.vertical_datum != self.vertical_datum:
raise TerrainSupportError("terrain provenance vertical datum does not match the raster")
[docs]
def cell_centers(self) -> tuple[np.ndarray, np.ndarray]:
"""Return cell-center x and y arrays.
Returns
-------
tuple of numpy.ndarray
Two arrays with the raster shape.
"""
rows, cols = self.values.shape
xs = self.min_x + (np.arange(cols) + 0.5) * self.resolution_m
ys = self.max_y - (np.arange(rows) + 0.5) * self.resolution_m
x_grid, y_grid = np.meshgrid(xs, ys)
return x_grid, y_grid
[docs]
def aggregate_terrain_support(
raster: TerrainRaster,
segments: list[SegmentWindow],
config: TerrainConfig | None = None,
*,
created_utc: datetime | None = None,
) -> TerrainSupportReport:
"""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.
"""
rules = config or TerrainConfig()
if rules.statistic not in TERRAIN_STATISTICS:
raise TerrainSupportError(f"unknown terrain statistic {rules.statistic!r}")
x_grid, y_grid = raster.cell_centers()
elevations = raster.values.astype(float)
if raster.nodata is not None:
elevations = np.where(elevations == raster.nodata, np.nan, elevations)
slope, aspect = _slope_aspect(elevations, raster.resolution_m)
valid = np.isfinite(elevations) & np.isfinite(slope)
supports: list[TerrainSupport] = []
for segment in segments:
if segment.crs != raster.crs:
raise TerrainSupportError(
f"segment {segment.segment_id} CRS {segment.crs!r} does not match "
f"raster CRS {raster.crs!r}; explicit transformation is required"
)
if segment.buffer_m < 0:
raise TerrainSupportError("segment buffer must be non-negative")
support_mask = segment_buffer_mask(
x_grid,
y_grid,
np.asarray(segment.coordinates, dtype=float),
segment.buffer_m,
)
candidate = int(np.count_nonzero(support_mask))
chosen = support_mask & valid
valid_pixels = int(np.count_nonzero(chosen))
coverage = 100.0 * valid_pixels / candidate if candidate else 0.0
if valid_pixels == 0:
supports.append(
TerrainSupport(
segment_id=segment.segment_id,
state="missing",
coverage_pct=0.0,
candidate_pixels=candidate,
valid_pixels=0,
terrain_class="missing",
access_class="unknown",
statistic=rules.statistic,
buffer_m=segment.buffer_m,
reason="no valid terrain cells within the segment buffer",
)
)
continue
state = (
"observed"
if valid_pixels >= rules.min_valid_pixels and coverage >= rules.min_coverage_pct
else "partial"
)
elevation = _statistic(elevations[chosen], rules.statistic)
slope_deg = _statistic(slope[chosen], rules.statistic)
aspect_deg = _circular_mean(aspect[chosen])
terrain_class = _terrain_class(slope_deg)
access_proxy = max(0.0, min(1.0, 1.0 - slope_deg / rules.access_slope_deg))
support = TerrainSupport(
segment_id=segment.segment_id,
state=state,
coverage_pct=coverage,
candidate_pixels=candidate,
valid_pixels=valid_pixels,
elevation_m=elevation,
slope_deg=slope_deg,
aspect_deg=aspect_deg,
terrain_class=terrain_class,
access_proxy=access_proxy,
access_class=_access_class(access_proxy),
statistic=rules.statistic,
buffer_m=segment.buffer_m,
reason="" if state == "observed" else "valid coverage is below the threshold",
)
supports.append(support)
return TerrainSupportReport(
created_utc=created_utc or datetime.now(UTC),
crs=raster.crs,
resolution_m=raster.resolution_m,
vertical_datum=raster.vertical_datum,
raster_bounds=[raster.min_x, raster.min_y, raster.max_x, raster.max_y],
source=raster.provenance,
config=rules,
supports=supports,
)
[docs]
def validate_terrain_support(report: TerrainSupportReport) -> ContractValidation:
"""Validate terrain support states, ranges, and provenance.
Parameters
----------
report : TerrainSupportReport
Report to validate.
Returns
-------
ContractValidation
Errors, warnings, and counts.
"""
errors: list[str] = []
warnings: list[str] = []
check_duplicates(
"TERRAIN",
"segment",
[support.segment_id for support in report.supports],
errors,
)
if report.created_utc.tzinfo is None:
errors.append("TERRAIN-TIME: created_utc is not timezone-aware")
if report.config.statistic not in TERRAIN_STATISTICS:
errors.append(f"TERRAIN-CONFIG: unknown statistic {report.config.statistic!r}")
if report.source.product not in TERRAIN_PRODUCT_KINDS:
errors.append("TERRAIN-SOURCE: provenance is not a DEM or DSM")
if report.source.crs != report.crs:
errors.append("TERRAIN-CRS: source CRS does not match the report")
if report.source.vertical_datum != report.vertical_datum:
errors.append("TERRAIN-DATUM: source vertical datum does not match the report")
if report.source.resolution_m is not None and not math.isclose(
report.source.resolution_m, report.resolution_m
):
errors.append("TERRAIN-RESOLUTION: source resolution does not match the report")
for support in report.supports:
if support.state not in TERRAIN_STATES:
errors.append(
f"TERRAIN-STATE: {support.segment_id} has unknown state {support.state!r}"
)
if support.valid_pixels > support.candidate_pixels:
errors.append(
f"TERRAIN-PIXELS: {support.segment_id} valid pixels exceed candidate pixels"
)
if support.state == "missing" and support.valid_pixels != 0:
errors.append(f"TERRAIN-MISSING: {support.segment_id} has valid pixels but is missing")
if support.state == "missing" and not support.reason.strip():
errors.append(f"TERRAIN-REASON: {support.segment_id} has no missing reason")
if support.state == "observed":
if support.valid_pixels < report.config.min_valid_pixels:
errors.append(
f"TERRAIN-COVERAGE: {support.segment_id} is observed below the pixel threshold"
)
if support.coverage_pct < report.config.min_coverage_pct:
errors.append(
f"TERRAIN-COVERAGE: {support.segment_id} is observed below the "
"coverage threshold"
)
if support.elevation_m is None or support.slope_deg is None:
errors.append(
f"TERRAIN-VALUE: {support.segment_id} is observed without terrain values"
)
if support.state in ("observed", "partial") and support.valid_pixels == 0:
errors.append(
f"TERRAIN-COVERAGE: {support.segment_id} has no valid pixels for a "
"non-missing state"
)
if support.access_proxy is None and support.state != "missing":
warnings.append(f"TERRAIN-ACCESS: {support.segment_id} has no access proxy")
if not report.supports:
warnings.append("TERRAIN-EMPTY: the report has no segment supports")
counts: dict[str, int | float] = {
"segments": len(report.supports),
"observed": sum(1 for support in report.supports if support.state == "observed"),
"partial": sum(1 for support in report.supports if support.state == "partial"),
"missing": sum(1 for support in report.supports if support.state == "missing"),
}
return ContractValidation(tuple(errors), tuple(warnings), counts)
def _slope_aspect(
elevations: np.ndarray,
resolution_m: float,
) -> tuple[np.ndarray, np.ndarray]:
dz_dy, dz_dx = np.gradient(elevations, resolution_m, resolution_m)
slope = np.degrees(np.arctan(np.hypot(dz_dx, dz_dy)))
aspect = np.degrees(np.arctan2(-dz_dx, dz_dy)) % 360.0
return slope, aspect
[docs]
def segment_buffer_mask(
x_grid: np.ndarray,
y_grid: np.ndarray,
coordinates: np.ndarray,
buffer_m: float,
) -> np.ndarray:
"""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.
"""
distance = np.full(x_grid.shape, np.inf, dtype=float)
for start, end in itertools.pairwise(coordinates):
distance = np.minimum(
distance,
_point_to_segment_distance(
x_grid,
y_grid,
start[0],
start[1],
end[0],
end[1],
),
)
return distance <= buffer_m
def _point_to_segment_distance(
x: np.ndarray,
y: np.ndarray,
x1: float,
y1: float,
x2: float,
y2: float,
) -> np.ndarray:
dx = x2 - x1
dy = y2 - y1
length_squared = dx * dx + dy * dy
if length_squared == 0:
return np.hypot(x - x1, y - y1)
t = ((x - x1) * dx + (y - y1) * dy) / length_squared
t = np.clip(t, 0.0, 1.0)
return np.hypot(x - (x1 + t * dx), y - (y1 + t * dy))
def _statistic(values: np.ndarray, name: str) -> float:
if name == "mean":
return float(np.mean(values))
if name == "median":
return float(np.median(values))
if name == "min":
return float(np.min(values))
if name == "max":
return float(np.max(values))
if name == "p90":
return float(np.percentile(values, 90))
raise TerrainSupportError(f"unknown terrain statistic {name!r}")
def _circular_mean(angles: np.ndarray) -> float:
radians = np.radians(angles)
return float(np.degrees(np.arctan2(np.mean(np.sin(radians)), np.mean(np.cos(radians)))) % 360.0)
def _terrain_class(slope_deg: float) -> str:
if slope_deg < 2:
return "flat"
if slope_deg < 10:
return "gentle"
if slope_deg < 20:
return "moderate"
if slope_deg < 30:
return "steep"
return "very_steep"
def _access_class(proxy: float) -> str:
if proxy >= 0.8:
return "high"
if proxy >= 0.5:
return "moderate"
return "low"
__all__ = [
"ACCESS_CLASSES",
"TERRAIN_CLASSES",
"TERRAIN_PRODUCT_KINDS",
"TERRAIN_STATES",
"TERRAIN_STATISTICS",
"TERRAIN_SUPPORT_SCHEMA_VERSION",
"SegmentWindow",
"TerrainConfig",
"TerrainRaster",
"TerrainSupport",
"TerrainSupportError",
"TerrainSupportReport",
"aggregate_terrain_support",
"segment_buffer_mask",
"validate_terrain_support",
]