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.

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 product sha256.

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

See Also