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 into min/max/mean/count cells.

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

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

One loaded terrain grid with validity mask and metadata.

Parameters:
metadata: TerrainRasterMetadata
valid: ndarray
values: ndarray
exception femic.lidar.terrain.TerrainProcessingError[source]

Bases: RuntimeError

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

QA report for a terrain-product build.

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

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

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

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

Zonal-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, ...]
to_dict()[source]

Return the result as a JSON-serializable mapping.

Return type:

dict[str, object]

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_percent is 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:

TerrainQaReport

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:

ZonalStatisticsResult

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:

TerrainRasterResult

femic.lidar.terrain.inspect_terrain_raster(path)[source]

Read normalized metadata for one terrain raster without loading values.

Parameters:

path (Path)

Return type:

TerrainRasterMetadata

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 min for a DTM-like surface, max for a DSM-like surface, or mean/count for 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:

TerrainRasterResult

femic.lidar.terrain.read_terrain_grid(path)[source]

Load a single-band terrain grid and its validity mask.

Parameters:

path (Path)

Return type:

TerrainGrid

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:
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:
Return type:

Path