LiDAR Instance Integration
Purpose
This guide shows how an instance repository uses the FEMIC LiDAR CLI without copying discovery, materialization, terrain, or packaging helpers into the instance.
Instance Layout
The default layout under an instance root is:
<instance>/
metadata/lidar/lidarbc_selection.json
data/lidar/
materialization.json
lidarbc/<product>/layer_<id>/<year>/<filename>
terrain/
slope_percent.tif
terrain_qa.json
terrain_qa.csv
streams/
stream_candidates.tif
flow_accumulation.tif
stream_candidates_manifest.json
stream_candidates_review.md
canopy/
chm.tif
canopy_structure.json
canopy_qa.json
canopy_qa.csv
vri_canopy_comparison.csv
trees/
tree_product_summary.json
tree_block_summary.csv
products/
<bundle>/
manifest.json
provenance/selection.json
products/
Commit the selection, materialization, QA, review, and product manifests. Annex large tile, raster, and point-cloud payloads through DataLad to the instance’s Arbutus remote. Do not create a full-province mirror.
Instance Root Resolution
The LiDAR commands accept --instance-root PATH and resolve relative default
paths under it. FEMIC_INSTANCE_ROOT is also honoured by the shared instance
context.
export FEMIC_INSTANCE_ROOT="$PWD"
femic lidar discover --bbox 1148000,391900,1149900,393500
femic lidar materialize --selection-manifest metadata/lidar/lidarbc_selection.json
femic lidar terrain --dem data/lidar/lidarbc/dem/layer_5/2023/dem.tif
femic lidar streams --dem data/lidar/lidarbc/dem/layer_5/2023/dem.tif
femic lidar bundle \
--selection-manifest metadata/lidar/lidarbc_selection.json \
--product-plan config/lidar/product_plan.json
Explicit absolute paths still work. The instance root only supplies defaults; it does not hide the source or output paths from the manifests.
Recommended Workflow
Discover the bounded AOI and review the selection manifest.
femic lidar discover \ --bbox 1148000,391900,1149900,393500 \ --manifest-path metadata/lidar/lidarbc_selection.json
Materialize selected tiles and review the manifest.
femic lidar materialize \ --selection-manifest metadata/lidar/lidarbc_selection.json \ --output-root data/lidar femic lidar materialization-status data/lidar --require-complete
Build terrain products and QA.
femic lidar terrain \ --dem data/lidar/lidarbc/dem/layer_5/2023/dem.tif \ --output-dir data/lidar/terrain
Derive stream candidates and review caveats.
femic lidar streams \ --dem data/lidar/lidarbc/dem/layer_5/2023/dem.tif \ --output-dir data/lidar/streams \ --reference data/public/fwa_streams.geojson
Build canopy products and VRI uncertainty evidence.
femic lidar canopy \ --dem data/lidar/lidarbc/dem/layer_5/2023/dem.tif \ --dsm data/lidar/lidarbc/dsm/layer_1/2023/dsm.tif \ --output-dir data/lidar/canopy \ --vri data/input/tfl_6/vri_2025_r1_poly_tfl6.gpkg
Inspect an optional individual-tree product.
femic lidar trees \ --product data/lidar/trees/lidarbc_trees.gpkg \ --output-dir data/lidar/trees
Package the reviewed products for WS4/FHOPS.
femic lidar bundle \ --selection-manifest metadata/lidar/lidarbc_selection.json \ --product-plan config/lidar/product_plan.json \ --output-dir data/lidar/products/lidarbc-2026.10.0 femic lidar inspect data/lidar/products/lidarbc-2026.10.0 --json
TFL 6 Pilot Evidence
A bounded TFL 6 pilot ran the full discovery, materialization, slope, and stream-candidate workflow on a 1 km AOI:
3 LidarBC DEM tiles, 60.0 MiB, all checksum-verified in 7.18 s;
LidarBC median slope 19.46% versus 15.03% on the same-AOI CDED comparison grid;
2.88 ha of LidarBC >=70% slope that CDED did not resolve;
D8 stream-candidate agreement with FWA was too low for riparian use.
The pilot did not change the TFL 6 locked CDED Step 220 proxy. Fragment-level
comparison is the next TFL 6 decision gate. Full evidence is in
planning/phase79_p79_6_tfl6_pilot.md in the parent FEMIC repository.
DataLad Boundary
Track JSON manifests and small review artifacts in the instance repo.
Annex large rasters, point clouds, and tile payloads.
Pin the product
bundle_id,bundle_version, and each productsha256.Do not let an instance edit a delivered product in place; rebuild a new bundle version instead.
Instance Handoff Checklist
[ ] The selection manifest records the AOI and requested products.
[ ] The materialization manifest is complete and checksum-clean.
[ ] Terrain QA reports are reviewed.
[ ] Stream-candidate caveats and comparison metrics are reviewed.
[ ] The product manifest is pinned for WS4/FHOPS.
[ ] Large payloads are annex-managed, not committed to git.