brushline.integrations.lidar_coverage

The LiDAR evidence, applicability, coverage-state, and gap adapter: request and entry models, the coverage assessment, and the P2.5 coverage/gap validator.

LiDAR coverage, applicability, and observation-gap reporting.

The adapter maps point-cloud, DEM, CHM, field-plot, and model-card evidence into the P2.5 coverage states and gap report. It does not read a payload, download a product, or impute a missing value. A required missing, stale, or out-of-domain evidence item is explicit and can stop the state build.

class brushline.integrations.lidar_coverage.Applicability(*, model_card_id: str | None = None, in_domain: bool = True, reason: str = '')[source]

Bases: BaseModel

The model-card applicability of one evidence item.

Parameters:
  • model_card_id (str or None) – Model card id.

  • in_domain (bool, optional) – Whether the evidence is inside the model domain. Defaults to True.

  • reason (str, optional) – Why the evidence is out of domain.

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

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

class brushline.integrations.lidar_coverage.LidarCoverageConfig(*, state_year: Annotated[int, Ge(ge=1900), Le(le=2200)] = 2026, max_age_years: Annotated[int, Ge(ge=0)] = 10, min_coverage_pct: Annotated[float, Ge(ge=0), Le(le=100)] = 50.0, min_valid_pixel_pct: Annotated[float, Ge(ge=0), Le(le=100)] = 80.0)[source]

Bases: BaseModel

Coverage and recency rules.

Parameters:
  • state_year (int, optional) – Target state year. Defaults to 2026.

  • max_age_years (int, optional) – Maximum acquisition age for a contemporary observation. Defaults to 10.

  • min_coverage_pct (float, optional) – Minimum usable coverage. Defaults to 50.

  • min_valid_pixel_pct (float, optional) – Minimum valid-pixel percentage. Defaults to 80.

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

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

class brushline.integrations.lidar_coverage.LidarCoverageEntry(*, segment_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], kind: str, state: str, required: bool, coverage_pct: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)], source_coverage_pct: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)], valid_pixel_pct: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)] = None, acquisition_date: ~datetime.date | None = None, vintage: str = '', evidence: str = '', reason: str = '', model_card_id: str | None = None, applicability: ~brushline.integrations.lidar_coverage.Applicability = <factory>, recommended_action: str = '')[source]

Bases: BaseModel

One segment/evidence coverage decision.

Parameters:
  • segment_id (str) – Segment id.

  • kind (str) – Evidence kind.

  • state (str) – One of the six coverage states.

  • required (bool) – Whether a gap stops the build.

  • coverage_pct (float) – Usable coverage after the valid-pixel rule.

  • source_coverage_pct (float) – Source coverage before the valid-pixel rule.

  • valid_pixel_pct (float or None) – Valid-pixel percentage.

  • acquisition_date (datetime.date or None) – Acquisition date.

  • vintage (str) – Acquisition year or empty.

  • evidence (str) – Evidence reference.

  • reason (str) – Missing or non-observed reason.

  • model_card_id (str or None) – Model card id.

  • applicability (Applicability) – Model-card applicability.

  • recommended_action (str) – Next action.

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

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

exception brushline.integrations.lidar_coverage.LidarCoverageError[source]

Bases: ValueError

Raised when the LiDAR coverage request is inconsistent.

class brushline.integrations.lidar_coverage.LidarCoverageReport(*, schema_version: Literal['brushline.lidar-coverage.v1'] = 'brushline.lidar-coverage.v1', created_utc: datetime, request: LidarCoverageRequest, entries: list[LidarCoverageEntry] = <factory>, coverage: CoverageReport, gaps: GapReport)[source]

Bases: BaseModel

The LiDAR coverage report and its P2.5 gap view.

Parameters:
  • schema_version ({"brushline.lidar-coverage.v1"}) – Report schema version.

  • created_utc (datetime) – Timezone-aware creation time.

  • request (LidarCoverageRequest) – Request and evidence.

  • entries (list of LidarCoverageEntry) – Segment/evidence decisions.

  • coverage (CoverageReport) – P2.5 coverage view.

  • gaps (GapReport) – P2.5 gap and stop/continue decision.

model_config = {'extra': 'forbid'}

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

class brushline.integrations.lidar_coverage.LidarCoverageRequest(*, aoi: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], plan_id: str = 'lidar-coverage', segment_ids: ~typing.Annotated[list[str], ~annotated_types.MinLen(min_length=1)], observations: list[~brushline.integrations.lidar_coverage.LidarEvidence] = <factory>, required_kinds: list[str] = <factory>, optional_kinds: list[str] = <factory>, config: ~brushline.integrations.lidar_coverage.LidarCoverageConfig = <factory>)[source]

Bases: BaseModel

A request to assess LiDAR coverage and applicability.

Parameters:
  • aoi (str) – AOI reference.

  • plan_id (str, optional) – Report plan id.

  • segment_ids (list of str) – Segment ids.

  • observations (list of LidarEvidence) – Available evidence.

  • required_kinds (list of str, optional) – Evidence kinds whose absence stops the build.

  • optional_kinds (list of str, optional) – Evidence kinds whose absence is a caveat.

  • config (LidarCoverageConfig, optional) – Coverage and recency 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_coverage.LidarEvidence(*, segment_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], kind: str, acquisition_date: ~datetime.date, coverage_pct: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)], valid_pixel_pct: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)] = None, applicability: ~brushline.integrations.lidar_coverage.Applicability = <factory>, evidence: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], excluded: bool = False, reason: str = '', source: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], source_version: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)])[source]

Bases: BaseModel

One acquisition or observation for a segment.

Parameters:
  • segment_id (str) – Segment id.

  • kind (str) – Evidence kind.

  • acquisition_date (datetime.date) – Acquisition date.

  • coverage_pct (float) – Source coverage percentage.

  • valid_pixel_pct (float or None) – Valid-pixel percentage, when the producer records it.

  • applicability (Applicability, optional) – Model-card applicability.

  • evidence (str) – Evidence reference, such as a bundle or product id.

  • excluded (bool, optional) – Whether the evidence is deliberately excluded.

  • reason (str, optional) – Exclusion or caveat reason.

  • source (str) – Source name.

  • source_version (str) – Source version.

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

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

brushline.integrations.lidar_coverage.assess_lidar_coverage(request: LidarCoverageRequest, *, created_utc: datetime | None = None) → LidarCoverageReport[source]

Assess LiDAR evidence, coverage, applicability, and gaps.

Parameters:
  • request (LidarCoverageRequest) – Segment ids, observations, expected kinds, and rules.

  • created_utc (datetime, optional) – Report time. Defaults to the current UTC time.

Returns:

LidarCoverageReport – Per-evidence decisions, the P2.5 coverage view, and the gap report.

brushline.integrations.lidar_coverage.validate_lidar_coverage(report: LidarCoverageReport) → ContractValidation[source]

Validate the LiDAR coverage entries and their P2.5 reports.

Parameters:

report (LidarCoverageReport) – Report to validate.

Returns:

ContractValidation – Errors, warnings, and counts.