LiDAR ground-bundle reader

The optional ground bundle is a sidecar product. FEMIC is now the canonical producer; the earlier fresh-urban-forest-lab writer proved the same contract and is legacy.

Build a bundle

femic lidar ground-bundle-build data/lidar/crop/tfl6_blocks.laz \
  output/ground/tfl6_blocks \
  --crs EPSG:3156 --vertical-datum CGVD2013

The command writes ground.laz, manifest.json, and qa.json and is opt-in. Without laspy, install femic[lidar].

Near-surface ground

The default is_ground mask is strict. On steep terrain, some terrain returns can lie on the final PTD surface but remain outside the strict mask. Use the opt-in near-surface pass to add points within a height tolerance of the final surface:

femic lidar ground-bundle-build data/lidar/crop/tfl6_blocks.laz \
  output/ground/tfl6_blocks \
  --crs EPSG:3156 --vertical-datum CGVD2013 \
  --no-sor --include-near-surface --near-surface-tolerance-m 0.15

The pass changes only is_ground. hag and is_low are unchanged. The manifest records include_near_surface and near_surface_tolerance_m; the QA file adds strict_ground_count and near_surface_added. The default remains strict.

Validate a bundle

femic lidar ground-bundle data/lidar/ground/tile_001

The command prints the schema versions, point count, ground count, low-point count, optional LAZ dimensions, and warnings. Use --json for the machine-readable summary.

Skip LAZ inspection

femic lidar ground-bundle data/lidar/ground/tile_001 --no-inspect-points

This validates the manifest, QA file, counts, parameter hash, and file hashes without opening the LAZ. It is useful on a machine without laspy.

Install optional inspection

python -m pip install -e ".[lidar]"

laspy[lazrs] is optional. Without it, the reader still validates the bundle and records a warning that point inspection was skipped.

Large tiles and local crop

LidarBC LAZ tiles can be much larger than a block AOI. LAZ is not COPC, so an HTTP range read does not avoid the full download. Acquire the tile once, then crop locally before running the ground adapter:

femic lidar crop \
  --laz data/lidar/bc_092l062_4_1_2.laz \
  --bbox 881700,627500,882700,628500 \
  --out data/lidar/crop/tfl6_blocks.laz

The bbox is in the source CRS. The command writes the cropped LAZ and tfl6_blocks.manifest.json with input/output hashes, counts, bbox, CRS, and warnings.

Use a COPC source and a bounds-aware reader when one is available. Do not treat this crop as a range-read client.

Summarize by polygon

femic lidar ground-summary data/lidar/ground/tile_001 \
  --polygons blocks.gpkg \
  --id-field block_id \
  --out reports/ground_by_block.csv

Each row reports point count, ground fraction, low-point fraction, and HAG mean/p50/p95/max. The command writes a sidecar ground_by_block.manifest.json. Point and polygon CRS must match; there is no silent reprojection.

Python

from pathlib import Path

from femic.lidar.ground_bundle import read_ground_bundle

bundle = read_ground_bundle(Path("data/lidar/ground/tile_001"))
print(bundle.point_count, bundle.ground_count, bundle.low_point_count)
print(bundle.to_dict())

Validation evidence

LiDAR ground-classification validation summarizes the TFL6 end-to-end run, the Squamish public control, the parameter sensitivity, the rejected candidate, the CI guard, the false-negative audit, and the opt-in near-surface pass.

Limits

  • The reader validates a sidecar; it does not create one.

  • It does not validate ground-classification accuracy.

  • It does not change FEMIC’s default LidarBC products.

  • A missing laspy skips point inspection, not manifest/QA validation.