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: list, p2: list) -> 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 and 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: list, p2: list) → 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 (list): 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 (list): 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 match_points_to_polygons(points: list, polygons: list) → tuple[list, dict, list]

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 fout 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 (Polygon | MultiPolygon): A Shapely polygon or MultiPolygon to

be written.

output_file (str): The output filename for the GeoJSON file.