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:
BaseModelThe 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:
BaseModelCoverage 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:
BaseModelOne 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:
ValueErrorRaised 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:
BaseModelThe 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:
BaseModelA 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:
BaseModelOne 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.