femic.lidar.catalog Module

The femic.lidar.catalog module owns FEMIC’s LidarBC discovery contract. It describes the public source family, maps FEMIC products to direct tile layers, normalizes tile-index records, selects tiles for a BC Albers AOI, records every paginated request, and writes a provenance-carrying selection manifest. It does not download tile bytes or process rasters.

Use this page when you are debugging LidarBC selection or the provenance fields that later product packaging depends on.

Start Here If…

Use this page first if you are trying to:

  • understand which LidarBC layers feed point_cloud, dem, and dsm;

  • debug an AOI that returns no tiles or too many tiles;

  • inspect the licence, CRS, vertical datum, and accuracy metadata that travel with a selected tile; or

  • extend the selection manifest before P79.8 packages a product bundle.

Typical Usage

from pathlib import Path
from femic.lidar import discover_lidarbc_tiles, write_lidar_selection_manifest

selection = discover_lidarbc_tiles(
    (1148000, 391900, 1149900, 393500),
    ("point_cloud", "dem", "dsm"),
)
write_lidar_selection_manifest(
    selection,
    Path("metadata/lidar/lidarbc_selection.json"),
)

Key Entry Surfaces

  • LIDARBC_SOURCE Frozen source-family descriptor with portal, catalogue, index, licence, native CRS, supported/derived products, and storage boundary.

  • lidarbc_layers_for_product() Map a direct FEMIC product to its LidarBC tile-index layers.

  • normalize_bbox_epsg3005() Validate a BC Albers AOI bounding box.

  • bbox_intersects() Test positive-area overlap, excluding edge-touching tiles.

  • tile_from_arcgis_feature() Normalize one feature-service record into a LidarTile.

  • discover_lidarbc_tiles() Discover all selected tiles for an AOI and product set.

  • write_lidar_selection_manifest() Persist the selection as reviewed JSON.

Cross-References

LidarBC source discovery, tile-index parsing, and AOI selection contracts.

The module treats the public LidarBC feature service as a discovery surface only. It does not download tile bytes or reproject/resample source rasters. Those boundaries belong to the later materialization and product phases.

exception femic.lidar.catalog.LidarCatalogError[source]

Bases: RuntimeError

Raised when a LiDAR source contract or discovery request is invalid.

class femic.lidar.catalog.LidarProductLayer(product, layer_id, layer_name, grid_scale)[source]

Bases: object

One direct-download layer in a LiDAR source tile index.

Parameters:
  • product (str)

  • layer_id (int)

  • layer_name (str)

  • grid_scale (str | None)

grid_scale: str | None
layer_id: int
layer_name: str
product: str
to_dict()[source]

Return the layer as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.lidar.catalog.LidarSourceFamily(source_id, title, portal_url, catalogue_url, index_item_url, feature_service_url, licence_id, licence_url, native_crs, supported_products, derived_products, metadata_caveat, storage_boundary, notes=())[source]

Bases: object

An explicit public LiDAR source contract.

Parameters:
  • source_id (str)

  • title (str)

  • portal_url (str)

  • catalogue_url (str)

  • index_item_url (str)

  • feature_service_url (str)

  • licence_id (str)

  • licence_url (str)

  • native_crs (str)

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

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

  • metadata_caveat (str)

  • storage_boundary (str)

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

catalogue_url: str
derived_products: tuple[str, ...]
feature_service_url: str
index_item_url: str
licence_id: str
licence_url: str
metadata_caveat: str
native_crs: str
notes: tuple[str, ...] = ()
portal_url: str
source_id: str
storage_boundary: str
supported_products: tuple[str, ...]
title: str
to_dict()[source]

Return the source contract as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.lidar.catalog.LidarTile(source_id, product, layer_id, object_id, filename, maptile, storage_path, download_url, accuracy_report_url, info_file, grid_scale, acquisition_year, projection, spacing, point_density_ppm2, contract_id, operator_name, operator_number, vertical_datum, point_format, point_classes, bbox_epsg3005, area_m2)[source]

Bases: object

One normalized tile-index record with provenance fields.

Parameters:
  • source_id (str)

  • product (str)

  • layer_id (int)

  • object_id (int)

  • filename (str)

  • maptile (str | None)

  • storage_path (str | None)

  • download_url (str | None)

  • accuracy_report_url (str | None)

  • info_file (str | None)

  • grid_scale (str | None)

  • acquisition_year (int | None)

  • projection (str | None)

  • spacing (str | None)

  • point_density_ppm2 (int | None)

  • contract_id (str | None)

  • operator_name (str | None)

  • operator_number (str | None)

  • vertical_datum (str | None)

  • point_format (str | None)

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

  • bbox_epsg3005 (tuple[float, float, float, float])

  • area_m2 (float | None)

accuracy_report_url: str | None
acquisition_year: int | None
area_m2: float | None
bbox_epsg3005: tuple[float, float, float, float]
contract_id: str | None
download_url: str | None
filename: str
grid_scale: str | None
info_file: str | None
layer_id: int
maptile: str | None
object_id: int
operator_name: str | None
operator_number: str | None
point_classes: tuple[int, ...]
point_density_ppm2: int | None
point_format: str | None
product: str
projection: str | None
source_id: str
spacing: str | None
storage_path: str | None
property tile_id: str

Return a stable tile identity within the source index.

to_dict()[source]

Return the tile as a JSON-serializable mapping.

Return type:

dict[str, object]

vertical_datum: str | None
class femic.lidar.catalog.LidarTileSelection(source, generated_utc, aoi_bbox_epsg3005, products, tiles, request_urls=(), warnings=(), schema_version='femic.lidar.selection.v1')[source]

Bases: object

An AOI-scoped, provenance-carrying LiDAR tile selection manifest.

Parameters:
  • source (LidarSourceFamily)

  • generated_utc (str)

  • aoi_bbox_epsg3005 (tuple[float, float, float, float])

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

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

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

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

  • schema_version (str)

aoi_bbox_epsg3005: tuple[float, float, float, float]
generated_utc: str
products: tuple[str, ...]
request_urls: tuple[str, ...] = ()
schema_version: str = 'femic.lidar.selection.v1'
source: LidarSourceFamily
property tile_count: int

Return the number of selected tiles.

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

Return the selection manifest as a JSON-serializable mapping.

Return type:

dict[str, object]

property total_area_m2: float

Return the summed indexed tile area in square metres.

warnings: tuple[str, ...] = ()
femic.lidar.catalog.bbox_intersects(first, second)[source]

Return whether two BC Albers boxes overlap with positive area.

Edge-touching tiles are excluded. Both inputs are validated and normalized before the comparison.

Parameters:
  • first (Sequence[object])

  • second (Sequence[object])

Return type:

bool

femic.lidar.catalog.build_lidarbc_tile_query_url(layer_id, *, aoi_bbox_epsg3005, page_size=2000, result_offset=0, feature_service_url='https://services6.arcgis.com/ubm4tcTYICKBpist/arcgis/rest/services/LiDAR_BC_S3_Public/FeatureServer')[source]

Build one paginated LidarBC tile-index query URL.

The query asks the feature service for an EPSG:3005 envelope intersection and returns geometry and attributes in EPSG:3005.

Parameters:
  • layer_id (int)

  • aoi_bbox_epsg3005 (Sequence[object])

  • page_size (int)

  • result_offset (int)

  • feature_service_url (str)

Return type:

str

femic.lidar.catalog.discover_lidarbc_tiles(aoi_bbox_epsg3005, products, *, page_size=2000, max_pages_per_layer=100, timeout_sec=60.0, generated_utc=None)[source]

Discover LidarBC tiles intersecting an AOI.

Derived products such as CHM are recorded as warnings because they have no direct LidarBC tile-index layer. Discovery only reads the public feature service; it never downloads tile payloads.

Raises:

LidarCatalogError – If a product is unsupported, the service returns an error, or pagination exceeds max_pages_per_layer.

Parameters:
  • aoi_bbox_epsg3005 (Sequence[object])

  • products (Sequence[str])

  • page_size (int)

  • max_pages_per_layer (int)

  • timeout_sec (float)

  • generated_utc (str | None)

Return type:

LidarTileSelection

femic.lidar.catalog.lidarbc_layers_for_product(product)[source]

Return the direct-download layers for one LidarBC product.

Raises:

LidarCatalogError – If the product is derived or unsupported as a direct tile layer.

Parameters:

product (str)

Return type:

tuple[LidarProductLayer, …]

femic.lidar.catalog.normalize_bbox_epsg3005(value)[source]

Validate and normalize a BC Albers bounding box.

Parameters:

value (Sequence[object]) – Four finite numbers in minx,miny,maxx,maxy order, in EPSG:3005.

Returns:

The normalized bounding box.

Return type:

tuple of float

Raises:

LidarCatalogError – If the value is not four finite numbers with minx < maxx and miny < maxy.

femic.lidar.catalog.tile_from_arcgis_feature(feature, *, product, layer_id)[source]

Normalize one ArcGIS tile-index feature into a LidarTile.

Raises:

LidarCatalogError – If required identity fields or usable geometry are missing, or if the product does not match the declared layer.

Parameters:
  • feature (Mapping[str, object])

  • product (str)

  • layer_id (int)

Return type:

LidarTile

femic.lidar.catalog.write_lidar_selection_manifest(selection, path)[source]

Write a selection manifest as reviewed, pretty-printed JSON.

Parameters:
Return type:

Path