brushline.model.corridor

The corridor graph contract: corridors, segments, spans, treatment units, access points, structures, service standards, and the graph validator.

Corridor graph contract: corridors, segments, spans, treatment units, access, and structures.

The segment is the decision unit. A span is an ordered, contiguous run of segments between access points. A treatment unit is a set of segments scheduled and contracted together. The graph validator checks the stable ids, the references, the sequence order, the length conservation, the access links, the structure links, and the service standards.

class brushline.model.corridor.CorridorValidation(errors: tuple[str, ...], warnings: tuple[str, ...], counts: dict[str, int | float])[source]

Bases: object

The outcome of validating a corridor graph.

Parameters:
  • errors (tuple of str) – Named errors. An empty tuple means the graph is valid.

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

  • counts (dict of str to int or float) – Object counts and total segment length.

property is_valid: bool

Return whether the graph passed every check.

Returns:

bool – True when there are no errors.

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

Return a JSON-ready report.

Returns:

dict of str to object – Validity, errors, warnings, and counts.

class brushline.model.corridor.ServiceStandard(*, service_standard_id: Annotated[str, MinLen(min_length=1)], max_height_m: Annotated[float, Gt(gt=0)], min_clearance_m: Annotated[float, Ge(ge=0)], access_required: bool = True)[source]

Bases: BaseModel

A vegetation service standard for a segment.

Parameters:
  • service_standard_id (str) – Stable identifier.

  • max_height_m (float) – Maximum allowed vegetation height in metres. Must be positive.

  • min_clearance_m (float) – Minimum required clearance in metres. Must be non-negative.

  • access_required (bool, optional) – Whether the segment must remain accessible. Defaults to True.

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

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

class brushline.model.corridor.Corridor(*, corridor_id: Annotated[str, MinLen(min_length=1)], name: Annotated[str, MinLen(min_length=1)], asset_type: Literal['transmission', 'pipeline', 'railway', 'road', 'other'], length_m: Annotated[float, Gt(gt=0)], crs: Annotated[str, MinLen(min_length=1)])[source]

Bases: BaseModel

A linear asset and the land managed along it.

Parameters:
  • corridor_id (str) – Stable identifier.

  • name (str) – Human-readable name.

  • asset_type ({"transmission", "pipeline", "railway", "road", "other"}) – Asset class.

  • length_m (float) – Total corridor length in metres. Must be positive.

  • crs (str) – Coordinate reference system.

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

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

class brushline.model.corridor.Segment(*, segment_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], corridor_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], span_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], treatment_unit_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], sequence: ~typing.Annotated[int, ~annotated_types.Ge(ge=0)], length_m: ~typing.Annotated[float, ~annotated_types.Gt(gt=0)], geometry_wkt: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], service_standard_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], access_point_id: str | None = None, structure_ids: list[str] = <factory>)[source]

Bases: BaseModel

A length of corridor with stable site, access, and management attributes.

Parameters:
  • segment_id (str) – Stable identifier and decision key.

  • corridor_id (str) – Owning corridor.

  • span_id (str) – Owning span.

  • treatment_unit_id (str) – Owning treatment unit.

  • sequence (int) – Zero-based position within the span.

  • length_m (float) – Segment length in metres. Must be positive.

  • geometry_wkt (str) – LINESTRING or MULTILINESTRING geometry in the corridor CRS.

  • service_standard_id (str) – Service standard that applies to the segment.

  • access_point_id (str or None, optional) – Nearest access point, when one is known.

  • structure_ids (list of str, optional) – Structures on or adjacent to the segment.

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

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

class brushline.model.corridor.Span(*, span_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], corridor_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], segment_ids: ~typing.Annotated[list[str], ~annotated_types.MinLen(min_length=1)], access_point_ids: list[str] = <factory>)[source]

Bases: BaseModel

An ordered, contiguous run of segments between access points.

Parameters:
  • span_id (str) – Stable identifier.

  • corridor_id (str) – Owning corridor.

  • segment_ids (list of str) – Ordered segment identifiers. At least one is required.

  • access_point_ids (list of str, optional) – Access points that serve the span.

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

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

class brushline.model.corridor.TreatmentUnit(*, treatment_unit_id: Annotated[str, MinLen(min_length=1)], corridor_id: Annotated[str, MinLen(min_length=1)], segment_ids: Annotated[list[str], MinLen(min_length=1)], contract_start_year: int, contract_end_year: int)[source]

Bases: BaseModel

A set of segments scheduled and contracted together.

Parameters:
  • treatment_unit_id (str) – Stable identifier.

  • corridor_id (str) – Owning corridor.

  • segment_ids (list of str) – Segments in the unit. At least one is required.

  • contract_start_year (int) – First year of the contract window.

  • contract_end_year (int) – Last year of the contract window.

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

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

class brushline.model.corridor.AccessPoint(*, access_point_id: Annotated[str, MinLen(min_length=1)], corridor_id: Annotated[str, MinLen(min_length=1)], kind: Literal['road', 'trail', 'landing', 'water', 'other'], location_wkt: Annotated[str, MinLen(min_length=1)])[source]

Bases: BaseModel

An access point that serves a span or a segment.

Parameters:
  • access_point_id (str) – Stable identifier.

  • corridor_id (str) – Owning corridor.

  • kind ({"road", "trail", "landing", "water", "other"}) – Access class.

  • location_wkt (str) – POINT geometry in the corridor CRS.

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

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

class brushline.model.corridor.Structure(*, structure_id: Annotated[str, MinLen(min_length=1)], corridor_id: Annotated[str, MinLen(min_length=1)], segment_id: Annotated[str, MinLen(min_length=1)], structure_type: Annotated[str, MinLen(min_length=1)], clearance_m: Annotated[float, Ge(ge=0)])[source]

Bases: BaseModel

An asset structure on or adjacent to a segment.

Parameters:
  • structure_id (str) – Stable identifier.

  • corridor_id (str) – Owning corridor.

  • segment_id (str) – Segment that carries or abuts the structure.

  • structure_type (str) – Structure class, such as tower, pole, valve, or crossing.

  • clearance_m (float) – Required clearance in metres. Must be non-negative.

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

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

class brushline.model.corridor.CorridorNetwork(*, schema_version: ~typing.Literal['brushline.corridor.v1'] = 'brushline.corridor.v1', crs: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], corridors: ~typing.Annotated[list[~brushline.model.corridor.Corridor], ~annotated_types.MinLen(min_length=1)], segments: ~typing.Annotated[list[~brushline.model.corridor.Segment], ~annotated_types.MinLen(min_length=1)], spans: ~typing.Annotated[list[~brushline.model.corridor.Span], ~annotated_types.MinLen(min_length=1)], treatment_units: ~typing.Annotated[list[~brushline.model.corridor.TreatmentUnit], ~annotated_types.MinLen(min_length=1)], access_points: list[~brushline.model.corridor.AccessPoint] = <factory>, structures: list[~brushline.model.corridor.Structure] = <factory>, service_standards: ~typing.Annotated[list[~brushline.model.corridor.ServiceStandard], ~annotated_types.MinLen(min_length=1)])[source]

Bases: BaseModel

The root corridor graph contract.

Parameters:
  • crs (str) – Coordinate reference system for every geometry.

  • corridors (list of Corridor) – Corridors in the network.

  • segments (list of Segment) – Decision segments.

  • spans (list of Span) – Ordered spans.

  • treatment_units (list of TreatmentUnit) – Contracted treatment units.

  • access_points (list of AccessPoint) – Access points.

  • structures (list of Structure) – Asset structures.

  • service_standards (list of ServiceStandard) – Service standards.

model_config = {'extra': 'forbid'}

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

brushline.model.corridor.validate_corridor_network(network: CorridorNetwork, *, length_tolerance_m: float = 0.01) → CorridorValidation[source]

Validate the corridor graph’s ids, references, order, and length conservation.

Parameters:
  • network (CorridorNetwork) – The graph to validate.

  • length_tolerance_m (float, optional) – Allowed absolute difference between a corridor length and the sum of its segments. Defaults to 0.01 metres.

Returns:

CorridorValidation – Errors, warnings, and object counts.