FEMIC LidarBC Products

WS4 consumes versioned FEMIC LidarBC product bundles. It does not run LiDAR discovery, materialization, terrain compilation, or canopy processing.

Bundle Contract

A FEMIC bundle contains manifest.json, provenance/selection.json, and products/. WS4 pins:

  • bundle_id and bundle_version;

  • manifest_sha256;

  • each product sha256 and relative_path.

ws4.io.lidar.load_femic_lidar_bundle validates the manifest, checksums, OGL-BC licence, native CRS, per-product resolution and vertical datum, and source-tile membership.

Python Usage

from pathlib import Path
from ws4.io.lidar import (
    bundle_pin,
    load_femic_lidar_bundle,
    summarize_femic_lidar_for_polygons,
)

bundle = load_femic_lidar_bundle(
    Path("data/femic/lidarbc-2026.10.0"),
    expected_bundle_id="lidarbc-995fb1f771f4d7fe",
)
pin = bundle_pin(bundle)
rows = summarize_femic_lidar_for_polygons(
    bundle,
    Path("data/blocks.gpkg"),
    product="slope",
    id_field="block_id",
)

Polygon summaries require ws4[lidar]. Polygon and product CRS must match; there is no silent reprojection or resampling.

Registration

Register a validated bundle in a compiled dataset:

ws4 lidar register \
  --dataset build/compiled \
  --bundle data/femic/lidarbc-2026.10.0 \
  --bundle-id lidarbc-995fb1f771f4d7fe \
  --bundle-version 2026.10.0-tfl6-pilot

ws4 lidar inspect --dataset build/compiled
ws4 lidar validate --dataset build/compiled

Registration writes the pin to manifest.json under metadata.lidar_products and to a lidar_products.json sidecar. The bundle is referenced, not copied.

The same registration is available during a build:

ws4 build --xml recipe.xml --fragments fragments.parquet --out build/compiled \
  --lidar-bundle data/femic/lidarbc-2026.10.0 \
  --lidar-bundle-id lidarbc-995fb1f771f4d7fe \
  --lidar-bundle-version 2026.10.0-tfl6-pilot

Fragment And Block Mapping

Map registered products to fragment and block support:

ws4 lidar map \
  --dataset build/compiled \
  --fragments data/fragments.gpkg \
  --out build/lidar_mapping \
  --product slope \
  --product chm \
  --statistic mean \
  --statistic p95

Fragment rows are zonal statistics over each fragment polygon. Block rows are zonal statistics over the dissolved block geometry. The default fields are fragment_id, block_id, and area_ha; override them with --fragment-id-field, --block-id-field, and --area-field.

The output includes lidar_fragments.csv, lidar_blocks.csv, and lidar_mapping_manifest.json. The manifest records the bundle pin, product checksums, CRS, native resolution, statistics, and explicit aggregation rules. No resampling or reprojection is performed.

Canopy And Precision Forestry

Map CHM height/cover and optional tree/VRI evidence:

ws4 lidar canopy \
  --dataset build/compiled \
  --fragments data/fragments.gpkg \
  --out build/canopy_mapping \
  --vri data/vri.gpkg \
  --tree-product individual_tree

The mapping records CHM mean/p90/p95/max and cover at 2/5/10 m for fragments and dissolved blocks. With --vri it adds area-weighted VRI height/closure and CHM-minus-VRI deltas plus uncertainty summaries. With --tree-product it adds tree counts, height mean/p95, and species counts per support.

The manifest records bundle provenance, checksums, CRS, native resolution, aggregation rules, VRI uncertainty, tree summary, and explicit caveats. CHM cover at >=2 m is not VRI crown-closure equivalence. No segmentation or raw point-cloud processing is implemented.

Dataset Integration

Write mapping fields into the compiled dataset:

ws4 lidar integrate \
  --dataset build/compiled \
  --fragments-mapping build/canopy_mapping/canopy_fragments.csv \
  --blocks-mapping build/canopy_mapping/canopy_blocks.csv

Fields are prefixed lidar_ (for example lidar_slope_mean, lidar_chm_p95, lidar_vri_height_m, lidar_tree_count). They are optional extra columns in the fragment and block Parquet tables; datasets without them remain valid.

The manifest records the bundle pin, mapping hashes, field lists, support keys, and integration timestamp under metadata.lidar_fields. Re-running without --overwrite fails when fields already exist. Simulation/optimization read the same dataset contract and simply see the extra columns.

Integration is a vectorized Parquet join. A 50,000-fragment / 5,000-block synthetic integration with four fields completed in about 0.14 s on the development host; no simulator or optimizer code path changes.

Validation Evidence

The real TFL 6 AOI path used a 100 ha support made of seven VRI polygons and one block:

  • WS4 vs FEMIC producer reference: maximum absolute difference 7.1e-15 (tolerance 1e-9);

  • WS4 vs FHOPS P14.1 consumer: maximum absolute difference 0.0;

  • map time 0.755 s; integration 0.037 s;

  • bundle 13.4 MB, mapping 4.4 KB, compiled validation dataset 52 KB;

  • licence OGL-BC, CRS EPSG:3005, native resolution 1 m.

The full report is in notes/reports/p52-closeout.md. No production dataset switch or model-semantics change was made.

Shared Parity

The WS4 and FHOPS consumer contracts were validated against FEMIC bundle lidarbc-995fb1f771f4d7fe over seven shared TFL 6 polygons. Slope and CHM mean/p95 values matched exactly (maximum absolute difference 0.0).

Web UI

A dataset registered and integrated through P52 exposes its canonical block fields in the web application’s LiDAR tab. The service reads the manifest pin and joins the fields by block_id; it does not open the rasters or re-run the mapping. See Web service (optional) for the endpoint and layer behavior. The P52 overwrite path drops old fields before joining, so a re-integrated dataset carries one canonical column per field rather than _x/_y copies.