brails.utils.input_validator module
This module provides a utility class for validating input data in BRAILS.
A utility class for validating BRAILS geospatial input data. |
- class brails.utils.input_validator.InputValidator
Bases:
object
A utility class for validating BRAILS geospatial input data.
This class provides static methods to validate various geospatial data structures such as points, linestrings, polygons, and their multi-geometries, ensuring conformance with geographic coordinate standards (longitude/latitude).
It also includes a lightweight utility for checking whether a file path points to an image file based on its extension, without opening the file.
All methods are designed to validate nested lists of floats representing coordinates, with specific rules for each geometry type.
To import the
InputValidator
class, use:from brails.utils import InputValidator
- static is_box(geometry)
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.
- Parameters:
geometry (Polygon) – A Shapely Polygon to be checked.
- Returns:
True
if thegeometry
is a rectangular box,False
otherwise.- Return type:
bool
- Raises:
TypeError – If the input is not a Shapely Polygon
Examples
>>> from shapely.geometry import Polygon >>> # A rectangle: >>> rect = Polygon([(0, 0), (2, 0), (2, 1), (0, 1), (0, 0)]) >>> GeoTools.is_box(rect) True
>>> # A non-rectangle polygon: >>> poly = Polygon([(0, 0), (1, 0), (2, 1), (0, 1), (0, 0)]) >>> GeoTools.is_box(poly) False
- static is_float(input_value)
Check if the given input_value can be converted to a float.
- Parameters:
input_value (Any) – The input value to check.
- Returns:
True
if theinput_value
can be converted to afloat
,False
otherwise.- Return type:
bool
Examples
>>> InputValidator.is_float('3.14') True
>>> InputValidator.is_float('abc') False
>>> InputValidator.is_float(None) False
>>> InputValidator.is_float(10) True
- static is_image(filepath)
Perform a lightweight check to determine if the file is an image.
This function checks that the path exists, is a file, and has a valid image file extension. It does not open or validate the contents of the file, so it cannot detect corrupted or mislabeled files.
- Parameters:
filepath (str) – The path to the file to check.
- Returns:
True
if thefilepath
points to a file with a supported image extension, otherwiseFalse
.- Return type:
bool
Examples
>>> InputValidator.is_image('example.jpg') # Assuming file exists True
>>> InputValidator.is_image('document.pdf') False
>>> InputValidator.is_image('/path/to/missing.png') False
- static is_linestring(coordinates)
Determine whether the input represents a valid BRAILS linestring.
In BRAILS, a valid linestring must:
Be a list of coordinate pairs, where each pair is a
list
of exactly twofloat
values: [longitude, latitude].Contain at least two coordinate pairs.
Not be a nested structure beyond one level (i.e., must be a
list
oflist
, not alist
oflist
oflist
).The first and last coordinate pairs must not be the same (i.e., the linestring must not be closed, to avoid confusion with a polygon).
This function strictly rejects inputs with excessive nesting, such as multilinestrings (i.e.,
list
oflist
of coordinate pairs).- Parameters:
coordinates (list[list[float]]) – A list of coordinate pairs forming a linestring.
- Returns:
True
if the coordinates represent a linestring,False
otherwise.- Return type:
bool
Examples
>>> InputValidator.is_linestring([ ... [-122.4, 37.75], ... [-122.39, 37.76] ... ]) True
>>> InputValidator.is_linestring([ ... [-122.4, 37.75], ... [-122.39, 37.76], ... [-122.4, 37.75] ... ]) False
>>> InputValidator.is_linestring([ ... [[-122.4, 37.75], [-122.39, 37.76]] ... ]) False
- static is_multilinestring(coordinates)
Determine whether the given coordinates represent a multilinestring.
In BRAILS, a multilinestring is defined as a
list
of valid linestrings, each with at least 2 points and not forming a closed loop.- Parameters:
coordinates (list[list[list[float]]]) – A list of linestrings, each represented as a list of coordinate pairs.
- Returns:
True
if the coordinates represent a multilinestring,False
otherwise.- Return type:
bool
Examples
>>> InputValidator.is_multilinestring([ ... [ ... [-122.4, 37.75], ... [-122.4, 37.76], ... [-122.39, 37.76], ... [-122.39, 37.75] ... ], ... [ ... [-122.38, 37.74], ... [-122.38, 37.75], ... [-122.37, 37.75], ... [-122.37, 37.74] ... ] ... ]) True
>>> InputValidator.is_multilinestring([ ... [ ... [-122.4, 37.75], ... [-122.4, 37.76], ... [-122.39, 37.76], ... [-122.39, 37.75] ... ] ... ]) False
- static is_multipolygon(coordinates)
Determine whether given coordinates represent a BRAILS multipolygon.
In BRAILS, a multipolygon is defined as a
list
of valid polygons, where each polygon is a closed loop with at least 3 points.- Parameters:
coordinates (list[list[list[float]]]) – A list of polygons, each represented as a list of coordinate pairs.
- Returns:
True
if the coordinates represent a multipolygon,False
otherwise.- Return type:
bool
Examples
>>> InputValidator.is_multipolygon([ ... [ ... [-122.4, 37.75], ... [-122.4, 37.76[ list(coord) for line in geom.geoms for coord in line.coords ]], ... [-122.39, 37.76], ... [-122.39, 37.75], ... [-122.4, 37.75] ... ], ... [ ... [-122.38, 37.74], ... [-122.38, 37.75], ... [-122.37, 37.75], ... [-122.37, 37.74], ... [-122.38, 37.74] ... ] ... ]) True
>>> InputValidator.is_multipolygon([ ... [ ... [-122.4, 37.75], ... [-122.4, 37.76], ... [-122.39, 37.76], ... [-122.39, 37.75] ... ] ... ]) False
- static is_point(coordinates)
Determine whether the given coordinates represent a point.
In BRAILS, a point is defined as a single coordinate pair.
- Parameters:
coordinates (list[list[float]]) – A list containing coordinate pairs [latitude, longitude].
- Returns:
True
if the coordinates represent a point,False
otherwise.- Return type:
bool
Examples
>>> InputValidator.is_point([[-122.4, 37.75]]) True
>>> InputValidator.is_point([ ... [-122.4, 37.75], ... [-122.39, 37.76] ... ]) False
- static is_polygon(coordinates)
Determine whether the input represents a valid BRAILS polygon geometry.
A valid polygon must:
Be a
list
of coordinate pairs.Each coordinate pair must be a
list
of exactly twofloat
values: [longitude, latitude].Contain at least three coordinate pairs, plus a fourth that closes the shape.
The first and last coordinate pairs must be the same (i.e., the polygon must form a closed loop).
The structure must be exactly one level deep: a
list
of coordinate pairs, not alist
oflist
of coordinatelist
.
This function performs structural and type checks and uses
validate_coordinates()
to ensure coordinate validity.- Parameters:
coordinates (list[list[float]]) – A list of coordinate pairs forming a polygon.
- Returns:
True
if the coordinates represent a polygon,False
otherwise.- Return type:
bool
Examples
>>> InputValidator.is_polygon([ ... [-122.4, 37.75], ... [-122.4, 37.76], ... [-122.39, 37.76], ... [-122.39, 37.75], ... [-122.4, 37.75] ... ]) True
>>> InputValidator.is_polygon([ ... [-122.4, 37.75], ... [-122.4, 37.76], ... [-122.39, 37.76], ... [-122.39, 37.75] ... ]) False
- static validate_coordinates(coordinates)
Validate input for coordinates.
- Parameters:
coordinates (list[list[float]]) – A two-dimensional list representing the geometry in
[[lon1, lat1], [lon2, lat2], ..., [lonN, latN]]
format.- Returns:
A tuple containing:
A boolean indicating if all coordinates are valid.
A message string describing any issues found, or confirming validation success.
- Return type:
tuple[bool, str]
Examples
>>> InputValidator.validate_coordinates([-122.4, 37.75]) (True, 'Coordinate pair is valid.')
>>> InputValidator.validate_coordinates([ ... [-122.4, 37.75], ... [-122.4, 37.76], ... [-122.39, 37.76], ... [-122.39, 37.75], ... [-122.4, 37.75] ... ]) (True, 'Coordinates input is valid')
>>> InputValidator.validate_coordinates("invalid") (False, 'Coordinates input is not a list')