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.LidarMaterializationManifestAudit surface with source, selection, storage, summary, and per-tile state.LidarMaterializationTilePer-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:
RuntimeErrorRaised 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:
objectAuditable 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:
objectOutcome 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
- 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:
objectOne 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
- class femic.lidar.materialization.LidarMaterializationValidation(manifest_path, is_valid, is_complete, checked_utc, errors, warnings, tile_count, verified_count, total_bytes)[source]
Bases:
objectValidation 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:
- 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:
- 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:
- femic.lidar.materialization.write_lidar_materialization_manifest(manifest, path)[source]
Write a materialization manifest atomically and return the path.
- Parameters:
manifest (LidarMaterializationManifest)
path (Path)
- Return type:
Path