brushline.integrations.lidar

The read-only FEMIC LiDAR bundle adapter: manifest and product models, selection and checksum validation, product provenance, and the committed bundle reference.

Read-only FEMIC LiDAR bundle adapter and provenance.

Brushline consumes the producer’s packaged product bundle. It does not discover tiles, download points, compile terrain, or write payloads. The adapter reads the manifest, pins the FEMIC producer version and bundle identity, verifies the selection digest and every product checksum, checks the native CRS, resolution, vertical datum, licence, and lineage, and returns source-preserving provenance for later segment aggregation.

exception brushline.integrations.lidar.LidarBundleError[source]

Bases: RuntimeError

Raised when a FEMIC LiDAR bundle cannot be loaded or validated.

class brushline.integrations.lidar.LidarBundleManifest(*, schema_version: str, layout_version: str, bundle_id: Annotated[str, MinLen(min_length=1)], bundle_name: Annotated[str, MinLen(min_length=1)], bundle_version: Annotated[str, MinLen(min_length=1)], created_utc: Annotated[str, MinLen(min_length=1)], producer: dict[str, object], source: dict[str, object], selection: dict[str, object], processing: dict[str, object], summary: LidarBundleSummary, products: Annotated[list[LidarProductRecord], MinLen(min_length=1)], consumer_contract: dict[str, object])[source]

Bases: BaseModel

The consumer-facing FEMIC product bundle manifest.

Parameters:
  • schema_version (str) – Product manifest schema version.

  • layout_version (str) – Bundle layout version.

  • bundle_id (str) – Stable bundle id.

  • bundle_name (str) – Human bundle name.

  • bundle_version (str) – Bundle version.

  • created_utc (str) – Creation time.

  • producer (dict of str to object) – Producer tool and version.

  • source (dict of str to object) – Source identity, licence, and native CRS.

  • selection (dict of str to object) – Selection digest and tile summary.

  • processing (dict of str to object) – Processing version, lineage, and parameters.

  • summary (LidarBundleSummary) – Product counts and bytes.

  • products (list of LidarProductRecord) – Packaged products.

  • consumer_contract (dict of str to object) – Consumer rules.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.integrations.lidar.LidarBundleSummary(*, product_count: Annotated[int, Ge(ge=0)], total_bytes: Annotated[int, Ge(ge=0)])[source]

Bases: BaseModel

The manifest summary counts.

Parameters:
  • product_count (int) – Number of products.

  • total_bytes (int) – Total product bytes.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.integrations.lidar.LidarBundleValidation(bundle_dir: Path, manifest: LidarBundleManifest | None, errors: tuple[str, ...], warnings: tuple[str, ...], counts: dict[str, int | float])[source]

Bases: object

The outcome of validating one FEMIC LiDAR bundle.

Parameters:
  • bundle_dir (Path) – Resolved bundle directory.

  • manifest (LidarBundleManifest or None) – Parsed manifest when the JSON shape is valid.

  • errors (tuple of str) – Named errors.

  • warnings (tuple of str) – Non-fatal findings.

  • counts (dict of str to int or float) – Product and byte counts.

property is_valid: bool

Return whether the bundle passed every check.

Returns:

bool – True when there are no errors.

to_dict() → dict[str, object][source]

Return a JSON-ready validation report.

Returns:

dict of str to object – Bundle path, validity, errors, warnings, and counts.

class brushline.integrations.lidar.LidarProductProvenance(*, bundle_id: str, bundle_version: str, femic_version: str, product_id: str, product: str, sha256: str, crs: str, resolution_m: float | None, vertical_datum: str, licence_id: str, retrieved_utc: str, source_tile_ids: list[str], source_layer_ids: list[int], derived: bool, lineage: list[str])[source]

Bases: BaseModel

The provenance that travels with one product-derived attribute.

Parameters:
  • bundle_id (str) – Pinned bundle id.

  • bundle_version (str) – Pinned bundle version.

  • femic_version (str) – Producer FEMIC version.

  • product_id (str) – Product id.

  • product (str) – Product kind.

  • sha256 (str) – Product checksum.

  • crs (str) – Product CRS.

  • resolution_m (float or None) – Product resolution.

  • vertical_datum (str) – Product vertical datum.

  • licence_id (str) – Product licence.

  • retrieved_utc (str) – Source retrieval time.

  • source_tile_ids (list of str) – Source tiles.

  • source_layer_ids (list of int) – Source layers.

  • derived (bool) – Whether the product is derived.

  • lineage (list of str) – Lineage notes.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.integrations.lidar.LidarProductRecord(*, product_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], product: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], relative_path: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], media_type: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], size_bytes: ~typing.Annotated[int, ~annotated_types.Ge(ge=0)], sha256: ~typing.Annotated[str, _PydanticGeneralMetadata(pattern='^[0-9a-f]{64}$')], crs: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], resolution_m: float | None = None, vertical_datum: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], retrieved_utc: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], source_tile_ids: ~typing.Annotated[list[str], ~annotated_types.MinLen(min_length=1)], source_layer_ids: list[int] = <factory>, licence_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], derived: bool = False, lineage: list[str] = <factory>)[source]

Bases: BaseModel

One packaged product in a FEMIC LiDAR bundle.

Parameters:
  • product_id (str) – Stable product identifier.

  • product (str) – Product kind.

  • relative_path (str) – Bundle-relative product path.

  • media_type (str) – Media type.

  • size_bytes (int) – Product size in bytes.

  • sha256 (str) – Product SHA-256.

  • crs (str) – Product CRS.

  • resolution_m (float or None) – Raster resolution in metres, or None for a non-raster product.

  • vertical_datum (str) – Vertical datum.

  • retrieved_utc (str) – Source retrieval time.

  • source_tile_ids (list of str) – Source tile ids.

  • source_layer_ids (list of int) – Source layer ids.

  • licence_id (str) – Source licence.

  • derived (bool) – Whether the product is derived.

  • lineage (list of str, optional) – Processing lineage notes.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

brushline.integrations.lidar.bundle_reference() → dict[str, object][source]

Return the committed bundle contract reference.

Returns:

dict of str to object – Schema, pin, required keys, product kinds, and consumer rules.

brushline.integrations.lidar.load_lidar_bundle(bundle_dir: Path, *, expected_femic_version: str = '0.2.0a1') → LidarBundleManifest[source]

Load and validate a FEMIC LiDAR bundle.

Parameters:
  • bundle_dir (Path) – Bundle directory.

  • expected_femic_version (str, optional) – Exact producer version.

Returns:

LidarBundleManifest – Validated manifest.

Raises:

LidarBundleError – When the bundle is invalid.

brushline.integrations.lidar.product_provenance(manifest: LidarBundleManifest) → tuple[LidarProductProvenance, ...][source]

Return source-preserving provenance for every product.

Parameters:

manifest (LidarBundleManifest) – Validated manifest.

Returns:

tuple of LidarProductProvenance – One provenance record per product.

brushline.integrations.lidar.validate_lidar_bundle(bundle_dir: Path, *, expected_femic_version: str = '0.2.0a1') → LidarBundleValidation[source]

Validate a FEMIC product bundle without reading a payload.

Parameters:
  • bundle_dir (Path) – Bundle directory containing manifest.json.

  • expected_femic_version (str, optional) – Exact FEMIC producer version. Defaults to the pinned boundary.

Returns:

LidarBundleValidation – Manifest, errors, warnings, and counts.

brushline.integrations.lidar.write_bundle_reference(path: Path) → Path[source]

Write the bundle contract reference as formatted JSON.

Parameters:

path (Path) – Destination JSON path.

Returns:

Path – The written path.