brails.utils.geo_tools module

This module defines a class for geospatial analysis and operations.

GeoTools()

A collection of static methods for geospatial analysis and operations.

class brails.utils.geo_tools.GeoTools

Bases: object

A collection of static methods for geospatial analysis and operations.

The GeoTools class provides various utility functions to perform common geospatial tasks, including distance calculations, polygon meshing, plotting, and GeoJSON file handling. The methods leverage Shapely geometries to operate on points and polygons, making it suitable for geographical data manipulation and visualization.

Methods:

haversine_dist(p1: tuple, p2: tuple) -> float:

Calculate the Haversine distance between two geographical points.

mesh_polygon(polygon: Polygon, rows: int, cols: int) ->

list[Polygon]: Split a polygon into a grid of individual rectangular polygons.

plot_polygon_cells(bpoly: Polygon | MultiPolygon,

rectangles: list[Polygon], output_file: str = ‘’): Plot a polygon/its rectangular mesh, optionally saving the plot.

write_polygon_to_geojson(poly: Polygon | MultiPolygon,

output_file: str): Write a Shapely Polygon or MultiPolygon to a GeoJSON file.

match_points_to_polygons(points: list, polygons: list) ->

tuple[list, dict]: Match points to polygons and return the correspondence data.

static haversine_dist(p1: Tuple[float, float], p2: Tuple[float, float]) → float

Calculate the Haversine distance between two points.

This function computes the shortest distance over the earth’s surface between two points specified by their latitude and longitude.

Args:

p1 (tuple):

The first point as a list containing two floating-point values, where the first element is the latitude and the second is the longitude of the point in degrees.

p2 (tuple):

The second point as a list containing two floating-point values, where the first element is the latitude and the second is the longitude of the point in degrees.

Returns:

float:

The Haversine distance between the two points in feet.

static is_box(geometry: Polygon) → bool

Determine whether a given Shapely geometry is a rectangular box.

A box is defined as a Polygon with exactly four corners and opposite sides being equal. This function checks if the geometry is a Polygon with 5 coordinates (the 5th being a duplicate of the first to close the polygon), and verifies that opposite sides are equal, ensuring that the polygon is rectangular.

Args:

geometry (Polygon):

A Shapely Polygon object to be checked.

Returns:

bool:

True if the Polygon is a rectangular box, False otherwise.

Raises:

TypeError:

If the input is not a Shapely Polygon object.

static match_points_to_polygons(points: List[Point], polygons: List[Polygon]) → Tuple[List[Point], Dict[str, Point], List[int]]

Match points to polygons and return the correspondence data.

This function finds Shapely points that fall within given polygons. If multiple points exist within a polygon, it selects the point closest to the polygon’s centroid.

Args:

points (list):

A list of Shapely points.

polygons (list):

A list of polygon coordinates defined in EPSG 4326 (longitude, latitude).

Returns:

tuple[list, dict, list]:

• A list of matched Shapely Point geometries.

• A dictionary mapping each polygon (represented as a string)

  to the corresponding matched point.

• A list of the indices of polygons matched to points, with

  each index listed in the same order as the list of points.

static mesh_polygon(polygon: Polygon, rows: int, cols: int) → List[Polygon]

Split a Spolygon into a grid of individual rectangular polygons.

This function divides the area of the input polygon into a specified number of rows and columns, creating a mesh of rectangular cells. Each cell is checked for intersection with the input polygon, and only the intersecting parts are returned.

Args:

polygon (Polygon):

A Shapely polygon to be meshed.

rows (int):

The number of rows to divide the polygon into.

cols (int):

The number of columns to divide the polygon into.

Returns:

list[Polygon]:

A list of Shapely polygons representing the individual rectangular cells that mesh the input polygon.

static plot_polygon_cells(bpoly: Polygon | MultiPolygon, rectangles: List[Polygon], output_file: str = '')

Plot a polygon and its rectangular mesh, optionally saving the plot.

Args:

bpoly (Polygon | MultiPolygon):

A Shapely polygon or MultiPolygon to plot.

rectangles (list[Polygon]):

A list of Shapely polygons representing the rectangular cells that mesh input polygon.

output_file (str, optional):

Filename to save the plot as a PNG image. If empty string, the plot is not saved.

Raises:

ValueError:

If output_file is provided and an invalid filename is given.

static write_polygon_to_geojson(poly: Polygon | MultiPolygon, output_file: str)

Write a Shapely Polygon or MultiPolygon to a GeoJSON file.

Args:

poly (Union[Polygon, MultiPolygon]):

A Shapely Polygon or MultiPolygon to be written.

output_file (str):

The output filename for the GeoJSON file.

Notes:

• This method does not perform validation on the geometry.

• The file extension will be replaced with ‘.geojson’ if not present.