femic.lidar.products Module

The femic.lidar.products module owns FEMIC’s versioned LiDAR product bundle. It packages already-compiled artifacts against a P79.1 selection, records source and processing lineage, writes per-product checksums, and validates the bundle before delivery to WS4 P43 or FHOPS P13.

Use this page when you are building, inspecting, or debugging a product bundle rather than the upstream LidarBC discovery contract.

Start Here If…

Use this page first if you are trying to:

  • turn a P79.1 selection and a product plan into a consumer-ready bundle;

  • inspect the manifest fields that travel with a terrain or canopy product;

  • debug a checksum, CRS, resolution, licence, or lineage validation failure; or

  • pin a bundle version for WS4 P43 or FHOPS P13.

Typical Usage

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
femic lidar inspect data/lidar/products/lidarbc-2026.10.0 --json

The matching Python entry points are:

from pathlib import Path
from femic.lidar.products import (
    build_lidar_product_bundle,
    validate_lidar_product_bundle,
)

result = build_lidar_product_bundle(
    selection_manifest_path=Path("metadata/lidar/lidarbc_selection.json"),
    product_plan_path=Path("config/lidar/product_plan.json"),
    output_dir=Path("data/lidar/products/lidarbc-2026.10.0"),
)
report = validate_lidar_product_bundle(result.bundle_dir)

Key Entry Surfaces

  • load_lidar_product_plan() Load and validate a femic.lidar.product_plan.v1 document, resolving artifact paths relative to the plan file.

  • build_lidar_product_bundle() Copy compiled products into the deterministic bundle layout, compute checksums, and write the versioned manifest.

  • validate_lidar_product_bundle() Verify manifest structure, selection provenance, checksums, native CRS, resolution, licence, and source-tile lineage.

  • LidarProductManifest Consumer-facing manifest with bundle identity, source, selection, processing, products, summary, and consumer contract.

  • LidarProductValidation Machine-readable validation report with errors, warnings, and counts.

Cross-References

Versioned LidarBC product bundles and consumer manifest contracts.

The P79.8 slice packages already-compiled products; it does not compile terrain or canopy rasters. A bundle is reproducible from a P79.1 selection manifest, a product plan, and the product bytes.

class femic.lidar.products.LidarProductBuildResult(bundle_dir, manifest_path, selection_path, manifest)[source]

Bases: object

Paths and manifest returned by a successful bundle build.

Parameters:
bundle_dir: Path
manifest: LidarProductManifest
manifest_path: Path
selection_path: Path
to_dict()[source]

Return the build result as a JSON-serializable mapping.

Return type:

dict[str, object]

exception femic.lidar.products.LidarProductError[source]

Bases: RuntimeError

Raised when a product plan, selection, or bundle contract is invalid.

class femic.lidar.products.LidarProductManifest(bundle_id, bundle_name, bundle_version, created_utc, producer, source, selection, processing, products, consumer_contract, schema_version='femic.lidar.product.v1', layout_version='femic.lidar.bundle.v1')[source]

Bases: object

The versioned, consumer-facing product manifest.

Parameters:
  • bundle_id (str)

  • bundle_name (str)

  • bundle_version (str)

  • created_utc (str)

  • producer (dict[str, object])

  • source (dict[str, object])

  • selection (dict[str, object])

  • processing (dict[str, object])

  • products (tuple[LidarProductRecord, ...])

  • consumer_contract (dict[str, object])

  • schema_version (str)

  • layout_version (str)

bundle_id: str
bundle_name: str
bundle_version: str
consumer_contract: dict[str, object]
created_utc: str
layout_version: str = 'femic.lidar.bundle.v1'
processing: dict[str, object]
producer: dict[str, object]
property product_count: int

Return the number of packaged product artifacts.

products: tuple[LidarProductRecord, ...]
schema_version: str = 'femic.lidar.product.v1'
selection: dict[str, object]
source: dict[str, object]
to_dict()[source]

Return the manifest as a JSON-serializable mapping.

Return type:

dict[str, object]

property total_bytes: int

Return the total packaged product size in bytes.

class femic.lidar.products.LidarProductPlan(bundle_version, processing_version, products, processing_lineage=(), parameters=<factory>)[source]

Bases: object

A reproducible product-build plan.

Parameters:
  • bundle_version (str)

  • processing_version (str)

  • products (tuple[LidarProductSpec, ...])

  • processing_lineage (tuple[str, ...])

  • parameters (dict[str, object])

bundle_version: str
parameters: dict[str, object]
processing_lineage: tuple[str, ...] = ()
processing_version: str
products: tuple[LidarProductSpec, ...]
to_dict()[source]

Return the plan as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.lidar.products.LidarProductRecord(product_id, product, relative_path, media_type, size_bytes, sha256, crs, resolution_m, vertical_datum, retrieved_utc, source_tile_ids, source_layer_ids, licence_id, derived, lineage=())[source]

Bases: object

One packaged product artifact recorded in the bundle manifest.

Parameters:
  • product_id (str)

  • product (str)

  • relative_path (str)

  • media_type (str)

  • size_bytes (int)

  • sha256 (str)

  • crs (str)

  • resolution_m (float | None)

  • vertical_datum (str)

  • retrieved_utc (str)

  • source_tile_ids (tuple[str, ...])

  • source_layer_ids (tuple[int, ...])

  • licence_id (str)

  • derived (bool)

  • lineage (tuple[str, ...])

crs: str
derived: bool
licence_id: str
lineage: tuple[str, ...] = ()
media_type: str
product: str
product_id: str
relative_path: str
resolution_m: float | None
retrieved_utc: str
sha256: str
size_bytes: int
source_layer_ids: tuple[int, ...]
source_tile_ids: tuple[str, ...]
to_dict()[source]

Return the product record as a JSON-serializable mapping.

Return type:

dict[str, object]

vertical_datum: str
class femic.lidar.products.LidarProductSpec(product, source_path, media_type, crs, resolution_m, vertical_datum, retrieved_utc, source_tile_ids, source_layer_ids, derived=False, lineage=())[source]

Bases: object

One planned product artifact before checksumming and packaging.

Parameters:
  • product (str)

  • source_path (Path)

  • media_type (str)

  • crs (str)

  • resolution_m (float | None)

  • vertical_datum (str)

  • retrieved_utc (str)

  • source_tile_ids (tuple[str, ...])

  • source_layer_ids (tuple[int, ...])

  • derived (bool)

  • lineage (tuple[str, ...])

crs: str
derived: bool = False
lineage: tuple[str, ...] = ()
media_type: str
product: str
resolution_m: float | None
retrieved_utc: str
source_layer_ids: tuple[int, ...]
source_path: Path
source_tile_ids: tuple[str, ...]
vertical_datum: str
class femic.lidar.products.LidarProductValidation(bundle_dir, manifest_path, is_valid, checked_utc, errors, warnings, bundle_id, bundle_version, product_count, total_bytes)[source]

Bases: object

Validation outcome for one product bundle.

Parameters:
  • bundle_dir (Path)

  • manifest_path (Path)

  • is_valid (bool)

  • checked_utc (str)

  • errors (tuple[str, ...])

  • warnings (tuple[str, ...])

  • bundle_id (str | None)

  • bundle_version (str | None)

  • product_count (int)

  • total_bytes (int)

bundle_dir: Path
bundle_id: str | None
bundle_version: str | None
checked_utc: str
errors: tuple[str, ...]
is_valid: bool
manifest_path: Path
product_count: int
to_dict()[source]

Return the validation report as a JSON-serializable mapping.

Return type:

dict[str, object]

total_bytes: int
warnings: tuple[str, ...]
femic.lidar.products.build_lidar_product_bundle(*, selection_manifest_path, product_plan_path, output_dir, overwrite=False, generated_utc=None)[source]

Build a reproducible product bundle from a selection and product plan.

The bundle layout is:

manifest.json
provenance/selection.json
products/<product>__<index>__<filename>

The selection digest and every product checksum are recorded in the manifest. Rebuilding with the same inputs and generated_utc produces the same manifest bytes.

Raises:
  • LidarProductError – If the selection, plan, output directory, or safety checks fail.

  • OSError – If a product or bundle file cannot be copied or written.

Parameters:
  • selection_manifest_path (Path)

  • product_plan_path (Path)

  • output_dir (Path)

  • overwrite (bool)

  • generated_utc (str | None)

Return type:

LidarProductBuildResult

femic.lidar.products.load_lidar_product_plan(path)[source]

Load and validate a product plan, resolving product paths beside it.

Raises:

LidarProductError – If the plan schema, fields, or product entries are invalid.

Parameters:

path (Path)

Return type:

LidarProductPlan

femic.lidar.products.validate_lidar_product_bundle(bundle_dir, *, checked_utc=None)[source]

Validate a product bundle against its manifest and provenance.

The check covers manifest structure, selection digest, product existence and checksums, native CRS, resolution and vertical-datum fields, licence, derived-product labelling, and selected-tile lineage. It does not parse raster or point-cloud payloads.

Parameters:
  • bundle_dir (Path)

  • checked_utc (str | None)

Return type:

LidarProductValidation