femic.lidar.materialization Module

The femic.lidar.materialization module owns P79.2 resumable LidarBC tile materialization. It plans a managed layout, downloads tile bytes into an explicit root, resumes partial transfers, verifies size and SHA-256, and records retry state in materialization.json.

Use this page when you are planning, downloading, resuming, or auditing LiDAR tile payloads rather than compiling products or packaging a consumer bundle.

Start Here If…

Use this page first if you are trying to:

  • write a preflight manifest without downloading tile bytes;

  • resume an interrupted LiDAR download;

  • inspect why a tile is pending, partial, or failed; or

  • verify that a managed materialization root is complete and checksum-clean.

Typical Usage

femic lidar materialize \
  --selection-manifest metadata/lidar/lidarbc_selection.json \
  --output-root data/lidar \
  --plan-only

femic lidar materialize \
  --selection-manifest metadata/lidar/lidarbc_selection.json \
  --output-root data/lidar

femic lidar materialization-status data/lidar --json --require-complete

The matching Python entry points are:

from pathlib import Path
from femic.lidar.materialization import (
    materialize_lidar_selection,
    validate_lidar_materialization,
)

result = materialize_lidar_selection(
    selection_manifest_path=Path("metadata/lidar/lidarbc_selection.json"),
    output_root=Path("data/lidar"),
)
report = validate_lidar_materialization(result.manifest_path)

Key Entry Surfaces

  • plan_lidar_materialization() Build a pending manifest from a P79.1 selection without writing tile bytes.

  • materialize_lidar_selection() Download or resume all selected tiles under an explicit root.

  • validate_lidar_materialization() Check manifest structure, paths, sizes, checksums, and completeness.

  • write_lidar_materialization_manifest() Persist a manifest atomically.

  • LidarMaterializationManifest Audit surface with source, selection, storage, summary, and per-tile state.

  • LidarMaterializationTile Per-tile source URL, local path, status, checksum, retry, and resume fields.

Cross-References

Resumable LidarBC tile materialization with auditable manifests.

P79.2 downloads selected public tiles into an explicit managed data root. It keeps large artifacts out of git, resumes partial downloads, verifies SHA-256 and size on completion, and records enough retry state for a later rerun.

exception femic.lidar.materialization.LidarMaterializationError[source]

Bases: RuntimeError

Raised when a materialization plan, download, or manifest is invalid.

class femic.lidar.materialization.LidarMaterializationManifest(generated_utc, updated_utc, source, selection, storage, tiles, schema_version='femic.lidar.materialization.v1')[source]

Bases: object

Auditable manifest for one managed LiDAR materialization root.

Parameters:
  • generated_utc (str)

  • updated_utc (str)

  • source (dict[str, object])

  • selection (dict[str, object])

  • storage (dict[str, object])

  • tiles (tuple[LidarMaterializationTile, ...])

  • schema_version (str)

property downloading_count: int

Return the number of tiles still marked as downloading.

property failed_count: int

Return the number of failed tiles.

generated_utc: str
property is_complete: bool

Return whether every tile is verified.

property partial_count: int

Return the number of partial tiles.

property pending_count: int

Return the number of pending tiles.

schema_version: str = 'femic.lidar.materialization.v1'
selection: dict[str, object]
source: dict[str, object]
storage: dict[str, object]
property tile_count: int

Return the number of selected tiles.

tiles: tuple[LidarMaterializationTile, ...]
to_dict()[source]

Return the materialization manifest as a JSON-serializable mapping.

Return type:

dict[str, object]

property total_bytes: int

Return the summed verified or partial byte count.

updated_utc: str
property verified_count: int

Return the number of verified tiles.

class femic.lidar.materialization.LidarMaterializationResult(manifest, manifest_path, output_root, downloaded_count, resumed_count, skipped_count, failed_count, pending_count)[source]

Bases: object

Outcome of one materialization run.

Parameters:
  • manifest (LidarMaterializationManifest)

  • manifest_path (Path)

  • output_root (Path)

  • downloaded_count (int)

  • resumed_count (int)

  • skipped_count (int)

  • failed_count (int)

  • pending_count (int)

downloaded_count: int
failed_count: int
manifest: LidarMaterializationManifest
manifest_path: Path
output_root: Path
pending_count: int
resumed_count: int
skipped_count: int
to_dict()[source]

Return the run result as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.lidar.materialization.LidarMaterializationTile(tile_id, product, layer_id, filename, download_url, relative_path, status='pending', attempts=0, expected_size_bytes=None, size_bytes=None, sha256=None, remote_etag=None, last_attempt_utc=None, last_error=None, resumed_from_bytes=None)[source]

Bases: object

One selected tile and its local materialization state.

Parameters:
  • tile_id (str)

  • product (str)

  • layer_id (int)

  • filename (str)

  • download_url (str)

  • relative_path (str)

  • status (str)

  • attempts (int)

  • expected_size_bytes (int | None)

  • size_bytes (int | None)

  • sha256 (str | None)

  • remote_etag (str | None)

  • last_attempt_utc (str | None)

  • last_error (str | None)

  • resumed_from_bytes (int | None)

attempts: int = 0
download_url: str
expected_size_bytes: int | None = None
filename: str
last_attempt_utc: str | None = None
last_error: str | None = None
layer_id: int
product: str
relative_path: str
remote_etag: str | None = None
resumed_from_bytes: int | None = None
sha256: str | None = None
size_bytes: int | None = None
status: str = 'pending'
tile_id: str
to_dict()[source]

Return the tile state as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.lidar.materialization.LidarMaterializationValidation(manifest_path, is_valid, is_complete, checked_utc, errors, warnings, tile_count, verified_count, total_bytes)[source]

Bases: object

Validation outcome for one materialization manifest.

Parameters:
  • manifest_path (Path)

  • is_valid (bool)

  • is_complete (bool)

  • checked_utc (str)

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

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

  • tile_count (int)

  • verified_count (int)

  • total_bytes (int)

checked_utc: str
errors: tuple[str, ...]
is_complete: bool
is_valid: bool
manifest_path: Path
tile_count: int
to_dict()[source]

Return the validation report as a JSON-serializable mapping.

Return type:

dict[str, object]

total_bytes: int
verified_count: int
warnings: tuple[str, ...]
femic.lidar.materialization.materialize_lidar_selection(*, selection_manifest_path, output_root, manifest_path=None, plan_only=False, max_tiles=None, timeout_sec=60.0, fail_fast=False, generated_utc=None)[source]

Materialize selected tiles into a managed root with resume support.

Existing verified files are skipped after size and SHA-256 verification. Partial files are resumed with HTTP Range requests when supported. The manifest is written after each tile so an interrupted run can restart.

Parameters:
  • selection_manifest_path (Path)

  • output_root (Path)

  • manifest_path (Path | None)

  • plan_only (bool)

  • max_tiles (int | None)

  • timeout_sec (float)

  • fail_fast (bool)

  • generated_utc (str | None)

Return type:

LidarMaterializationResult

femic.lidar.materialization.plan_lidar_materialization(selection_manifest_path, *, generated_utc=None)[source]

Build a pending materialization manifest from a selection contract.

The plan records deterministic relative paths and confirmed source URLs but does not create the output root or download any tile bytes.

Parameters:
  • selection_manifest_path (Path)

  • generated_utc (str | None)

Return type:

LidarMaterializationManifest

femic.lidar.materialization.resolve_lidar_materialization_manifest_path(path)[source]

Resolve a manifest file or an output root to its manifest path.

Parameters:

path (Path)

Return type:

Path

femic.lidar.materialization.validate_lidar_materialization(manifest_path, *, checked_utc=None, verify_checksums=True)[source]

Validate a materialization manifest, file sizes, checksums, and status.

Parameters:
  • manifest_path (Path)

  • checked_utc (str | None)

  • verify_checksums (bool)

Return type:

LidarMaterializationValidation

femic.lidar.materialization.write_lidar_materialization_manifest(manifest, path)[source]

Write a materialization manifest atomically and return the path.

Parameters:
Return type:

Path