femic.lidar.terrain Module
The femic.lidar.terrain module owns FEMIC’s native-grid terrain raster
APIs. It derives percent slope, rasterizes in-memory sample points into
DTM/DSM-like surfaces, computes aligned zonal statistics, and writes JSON/CSV
QA reports. It does not reproject, resample, read LAZ/COPC, or apply
instance-specific thresholds.
Use this page when you are deriving or validating terrain products rather than discovering, materializing, or packaging LiDAR inputs.
Start Here If…
Use this page first if you are trying to:
derive slope from a native DTM/DEM;
grid sample points into a DTM/DSM-like surface;
compute zonal summaries over slope or elevation;
inspect the QA report for a terrain build; or
debug a rejected geographic, rotated, misaligned, or multiband input.
Typical Usage
from pathlib import Path
from femic.lidar.terrain import (
build_terrain_products,
compute_zonal_statistics,
derive_slope_percent,
rasterize_point_cloud,
)
result = derive_slope_percent(
Path("data/lidar/dem.tif"),
Path("data/lidar/slope_percent.tif"),
)
report = build_terrain_products(
Path("data/lidar/dem.tif"),
Path("data/lidar/terrain"),
)
stats = compute_zonal_statistics(
Path("data/zones.tif"),
Path("data/lidar/slope_percent.tif"),
)
grid = rasterize_point_cloud(
[(1148000.5, 391900.5, 812.3)],
output_path=Path("data/lidar/dtm_candidate.tif"),
bbox_epsg3005=(1148000, 391900, 1148100, 392000),
resolution_m=1.0,
)
Key Entry Surfaces
inspect_terrain_raster()Read normalized CRS, transform, resolution, nodata, bounds, dtype, and band metadata.read_terrain_grid()Load a single-band grid with its validity mask and metadata.require_projected_metre_grid()Enforce the projected-metre, north-up, unrotated terrain contract.derive_slope_percent()Derive Horn 3x3 percent slope on the native grid.rasterize_point_cloud()Aggregate in-memory points intomin/max/mean/countcells.compute_zonal_statistics()Compute aligned positive-zone statistics without resampling.build_terrain_products()Build the named terrain product set and write JSON/CSV QA reports.TerrainQaReportReview artifact with source metadata, products, parameters, counts, and warnings.
Cross-References
Native-grid terrain raster, slope, and zonal-statistic helpers.
P79.3 accepts existing DTM/DEM/DSM rasters and provides a small point-cloud cell-aggregation API for callers that already hold sample points. It does not read LAZ/COPC files, classify ground returns, reproject, or resample silently.
- class femic.lidar.terrain.TerrainGrid(values, valid, metadata)[source]
Bases:
objectOne loaded terrain grid with validity mask and metadata.
- Parameters:
values (ndarray)
valid (ndarray)
metadata (TerrainRasterMetadata)
- metadata: TerrainRasterMetadata
- valid: ndarray
- values: ndarray
- exception femic.lidar.terrain.TerrainProcessingError[source]
Bases:
RuntimeErrorRaised when a terrain raster, slope, or zonal operation is invalid.
- class femic.lidar.terrain.TerrainQaReport(generated_utc, source, products, dependency_stack=('numpy', 'rasterio'), warnings=(), schema_version='femic.lidar.terrain_qa.v1')[source]
Bases:
objectQA report for a terrain-product build.
- Parameters:
generated_utc (str)
source (TerrainRasterMetadata)
products (tuple[TerrainRasterResult, ...])
dependency_stack (tuple[str, ...])
warnings (tuple[str, ...])
schema_version (str)
- dependency_stack: tuple[str, ...] = ('numpy', 'rasterio')
- generated_utc: str
- property product_count: int
Return the number of derived products.
- products: tuple[TerrainRasterResult, ...]
- schema_version: str = 'femic.lidar.terrain_qa.v1'
- source: TerrainRasterMetadata
- to_dict()[source]
Return the QA report as a JSON-serializable mapping.
- Return type:
dict[str, object]
- warnings: tuple[str, ...] = ()
- class femic.lidar.terrain.TerrainRasterMetadata(path, crs, transform, width, height, resolution_x, resolution_y, nodata, dtype, band_count, bounds)[source]
Bases:
objectNormalized metadata for one terrain raster.
- Parameters:
path (Path)
crs (str)
transform (tuple[float, float, float, float, float, float])
width (int)
height (int)
resolution_x (float)
resolution_y (float)
nodata (float | None)
dtype (str)
band_count (int)
bounds (tuple[float, float, float, float])
- band_count: int
- bounds: tuple[float, float, float, float]
- crs: str
- dtype: str
- height: int
- nodata: float | None
- path: Path
- resolution_x: float
- resolution_y: float
- to_dict()[source]
Return the metadata as a JSON-serializable mapping.
- Return type:
dict[str, object]
- transform: tuple[float, float, float, float, float, float]
- width: int
- class femic.lidar.terrain.TerrainRasterResult(product, path, source_path, metadata, algorithm, parameters, generated_utc, valid_pixels, nodata_pixels, min_value, max_value, mean_value, warnings=())[source]
Bases:
objectOne derived terrain raster and its QA summary.
- Parameters:
product (str)
path (Path)
source_path (Path | None)
metadata (TerrainRasterMetadata)
algorithm (str)
parameters (dict[str, object])
generated_utc (str)
valid_pixels (int)
nodata_pixels (int)
min_value (float | None)
max_value (float | None)
mean_value (float | None)
warnings (tuple[str, ...])
- algorithm: str
- generated_utc: str
- max_value: float | None
- mean_value: float | None
- metadata: TerrainRasterMetadata
- min_value: float | None
- nodata_pixels: int
- parameters: dict[str, object]
- path: Path
- product: str
- source_path: Path | None
- to_dict()[source]
Return the product result as a JSON-serializable mapping.
- Return type:
dict[str, object]
- valid_pixels: int
- warnings: tuple[str, ...] = ()
- class femic.lidar.terrain.ZonalStatisticRow(zone_id, count, mean=None, median=None, minimum=None, maximum=None, stddev=None, total=None, area_ha=None)[source]
Bases:
objectStatistics for one positive zone ID.
- Parameters:
zone_id (int)
count (int)
mean (float | None)
median (float | None)
minimum (float | None)
maximum (float | None)
stddev (float | None)
total (float | None)
area_ha (float | None)
- area_ha: float | None = None
- count: int
- maximum: float | None = None
- mean: float | None = None
- median: float | None = None
- minimum: float | None = None
- stddev: float | None = None
- to_dict()[source]
Return the zone row as a JSON-serializable mapping.
- Return type:
dict[str, object]
- total: float | None = None
- zone_id: int
- class femic.lidar.terrain.ZonalStatisticsResult(zones_path, values_path, crs, resolution_x, resolution_y, statistics, rows, generated_utc, warnings=())[source]
Bases:
objectZonal-statistic outcome for one zones/values raster pair.
- Parameters:
zones_path (Path)
values_path (Path)
crs (str)
resolution_x (float)
resolution_y (float)
statistics (tuple[str, ...])
rows (tuple[ZonalStatisticRow, ...])
generated_utc (str)
warnings (tuple[str, ...])
- crs: str
- generated_utc: str
- resolution_x: float
- resolution_y: float
- rows: tuple[ZonalStatisticRow, ...]
- statistics: tuple[str, ...]
- values_path: Path
- warnings: tuple[str, ...] = ()
- zones_path: Path
- femic.lidar.terrain.build_terrain_products(source_path, output_dir, *, products=('slope_percent',), qa_json_path=None, qa_csv_path=None, nodata=None, generated_utc=None)[source]
Build terrain products and write JSON/CSV QA reports.
Only
slope_percentis implemented in P79.3. Additional terrain products should extend this function rather than creating a parallel pipeline.- Parameters:
source_path (Path)
output_dir (Path)
products (Sequence[str])
qa_json_path (Path | None)
qa_csv_path (Path | None)
nodata (float | None)
generated_utc (str | None)
- Return type:
- femic.lidar.terrain.compute_zonal_statistics(zones_path, values_path, *, statistics=('count', 'mean', 'median', 'min', 'max', 'std'), generated_utc=None)[source]
Compute zonal statistics over aligned zones and values rasters.
Zones must be positive integer IDs on exactly the same grid as values. The helper never resamples or reprojects either input.
- Parameters:
zones_path (Path)
values_path (Path)
statistics (Sequence[str])
generated_utc (str | None)
- Return type:
- femic.lidar.terrain.derive_slope_percent(source_path, output_path, *, nodata=None, generated_utc=None)[source]
Derive percent slope from a single-band elevation raster.
The operation preserves the source grid, CRS, and resolution. It requires a projected CRS in metres, a north-up transform, and no resampling.
- Parameters:
source_path (Path)
output_path (Path)
nodata (float | None)
generated_utc (str | None)
- Return type:
- femic.lidar.terrain.inspect_terrain_raster(path)[source]
Read normalized metadata for one terrain raster without loading values.
- Parameters:
path (Path)
- Return type:
- femic.lidar.terrain.rasterize_point_cloud(points_xyz, *, output_path, bbox_epsg3005, resolution_m, crs='EPSG:3005', aggregation='min', nodata=-9999.0, generated_utc=None)[source]
Rasterize points into a native-grid DTM/DSM-like surface.
This is a reusable cell-aggregation core, not a ground-classification workflow. Use
minfor a DTM-like surface,maxfor a DSM-like surface, ormean/countfor diagnostics.- Parameters:
points_xyz (Sequence[tuple[float, float, float]])
output_path (Path)
bbox_epsg3005 (Sequence[object])
resolution_m (float)
crs (str)
aggregation (str)
nodata (float)
generated_utc (str | None)
- Return type:
- femic.lidar.terrain.read_terrain_grid(path)[source]
Load a single-band terrain grid and its validity mask.
- Parameters:
path (Path)
- Return type:
- femic.lidar.terrain.require_projected_metre_grid(metadata)[source]
Require the native-grid slope/flow contract for a terrain raster.
- Parameters:
metadata (TerrainRasterMetadata)
- Return type:
None
- femic.lidar.terrain.write_terrain_qa_report(report, path)[source]
Write a terrain QA report as pretty-printed JSON.
- Parameters:
report (TerrainQaReport)
path (Path)
- Return type:
Path
- femic.lidar.terrain.write_terrain_qa_summary_csv(report, path)[source]
Write a one-row-per-product terrain QA summary CSV.
- Parameters:
report (TerrainQaReport)
path (Path)
- Return type:
Path