brails.types.region_boundary module

This module defines RegionBoundary class to store region boundary polygons.

RegionBoundary(input_dict)

A class for retrieving the bounding polygon of a specified region.
class brails.types.region_boundary.RegionBoundary(input_dict)

Bases: object

A class for retrieving the bounding polygon of a specified region.

This class processes input data, validates it, and provides functionality to obtain the region boundary based on the given data. The input must specify the type of region (e.g., location name or polygon) and the corresponding data.

To import the RegionBoundary class, you can use one of the following approaches:

Using the importer utility:

from brails import Importer

importer = Importer()
region_boundary_class = importer.get_class("RegionBoundary")

Or by direct import:

from brails.types.region_boundary import RegionBoundary
Parameters:

  • input_type (str) – The type of the region (e.g., ‘locationName’, ‘locationPolygon’).

  • query_area (str or tuple) – Description of the region, validated according to the specified type. Either a location name, e.g., ‘Berkeley, CA’, or a tuple, such as (-93.27968, 30.22733, -93.14492, 30.15774)

get_boundary()

Return the boundary of the region based on the provided input type.

This method processes the region’s data based on its type and returns the corresponding boundary. If the type is ‘locationName’, it fetches the region boundary from an external data source. If the type is ‘locationPolygon’, it converts the provided coordinates (bounding box) into a Shapely polygon.

Returns:

A tuple containing, in sequence:

  1. A Shapely geometry representing the region boundary.

  2. A human-readable description of the query area.

  3. An optional identifier (e.g., OSM ID) if available.

Return type:

Tuple[BaseGeometry, str, Optional[Union[int, str]]]

Raises:

RuntimeError – If input type is unexpectedly invalid.

Examples

Fetch boundary information based on the provided location name.

>>> from brails import Importer
>>> importer = Importer()
>>> region_boundary_class = importer.get_class("RegionBoundary")
>>> rb = region_boundary_class(
...     {'type': 'locationName', 'data': 'Berkeley, CA'}
... )
>>> geom, desc, osm_id = rb.get_boundary()
Searching for Berkeley, CA...
Found Berkeley, Alameda County, California, United States
>>> print(geom.bounds)
(-122.3686918, 37.8356877, -122.2341962, 37.9066896)
>>> print(desc)
Berkeley
>>> print(osm_id)
2833528

Get region boundary data for a bounding box.

>>> coords = (-122.3, 37.85, -122.25, 37.9)
>>> rb = region_boundary_class(
...     {'type': 'locationPolygon', 'data': coords}
... )
>>> geom, desc, osm_id = rb.get_boundary()
>>> geom.geom_type
'Polygon'
>>> print(desc)
the bounding box: (-122.3, 37.85, -122.25, 37.9)
class brails.types.region_boundary.RegionInput(dataType, validationConditions, errorMessage)

Bases: object

Input configuration for a specific region type.

Parameters:

  • dataType (type) – The expected data type for the input (e.g., str, tuple).

  • validationConditions (function) – A function that validates the input data based on the expected data type.

  • errorMessage (str) – The error message to be raised when the validation fails for the input data.

Example

>>> location_name_input = RegionInput(
...     dataType=str,
...     validationConditions=lambda data, dataType: isinstance(
...         data,
...         dataType
...     ),
...     errorMessage="'data' must be a string"
... )