Terrain and slope support
Terrain support maps a validated FEMIC DEM or DSM to a buffered corridor segment. It records the aggregation statistic, buffer, valid-pixel rule, coverage, elevation, slope, aspect, terrain class, and an explicit access proxy. It never reprojects, resamples, fills a missing cell, or downloads a raster.
Input contract
A TerrainRaster is a north-up two-dimensional elevation array with:
a western and southern edge and an eastern and northern edge;
a CRS and a resolution in metres;
a vertical datum;
a validated
LidarProductProvenancewhose product kind isdemordsm;an optional nodata value.
The raster provenance must agree with the raster CRS, resolution, and vertical datum. A mismatch fails; there is no silent transform.
A SegmentWindow is a polyline in the raster CRS with a buffer distance. The buffer is the corridor
support around the segment. A segment CRS that differs from the raster CRS fails.
Aggregation
aggregate_terrain_support samples cell centers within the segment buffer and computes:
valid-cell count and candidate-cell count;
coverage percentage;
elevation statistic;
slope statistic;
circular mean aspect;
terrain class;
access proxy and access class.
The supported statistics are mean, median, min, max, and p90. The configuration
records the minimum valid-pixel count and minimum coverage percentage.
from datetime import UTC, datetime
from brushline.integrations.terrain import (
SegmentWindow,
TerrainConfig,
TerrainRaster,
aggregate_terrain_support,
validate_terrain_support,
)
raster = TerrainRaster(
values=dem_array,
min_x=0.0,
min_y=0.0,
max_x=500.0,
max_y=500.0,
crs="EPSG:3005",
resolution_m=1.0,
vertical_datum="CGVD2013",
provenance=dem_provenance,
)
report = aggregate_terrain_support(
raster,
[SegmentWindow(segment_id="s1", coordinates=[(0, 10), (500, 10)], buffer_m=20)],
TerrainConfig(statistic="mean", min_valid_pixels=4, min_coverage_pct=50),
created_utc=datetime(2026, 11, 14, tzinfo=UTC),
)
assert validate_terrain_support(report).is_valid
Coverage states
State |
Rule |
|---|---|
|
Valid pixels and coverage meet the configured thresholds. |
|
Some valid cells exist, but a threshold is not met. |
|
No valid cells exist in the buffer; terrain values are empty and a reason is recorded. |
A partial or missing state is not a zero. It is a knowledge state for the state build and the review.
Terrain classes
The slope classes are:
flat: less than 2 degrees;gentle: 2 to less than 10 degrees;moderate: 10 to less than 20 degrees;steep: 20 to less than 30 degrees;very_steep: 30 degrees or more.
The access proxy is max(0, 1 - slope / access_slope_deg), with a default 30-degree zero point. It is
an evidence input, not an operability verdict. The access classes are high at 0.8 or more,
moderate at 0.5 or more, and low below 0.5. Missing support is unknown.
Named errors
Prefix |
Meaning |
|---|---|
|
Unknown statistic or invalid aggregation rule. |
|
Provenance is not a DEM/DSM, or source metadata is wrong. |
|
Source and report metadata disagree. |
|
The report time is not timezone-aware. |
|
Unknown state, impossible pixel counts, or observed support below a threshold. |
|
Missing values, a missing state with valid pixels, or a missing reason. |
|
A non-missing support has no access proxy (warning). |
|
The report has no segments (warning). |
Limits
The adapter does not parse raster payloads; the caller supplies the validated elevation array.
It does not reproject, resample, mosaic, or fill nodata.
It does not decide machine operability, access permission, or an operational route.
It does not choose the final terrain threshold for a partnership; that remains a documented configuration decision.