brails.utils.input_validator module

This module provides a utility class for validating input data in BRAILS.

InputValidator()

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 the geometry 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 the input_value can be converted to a float , 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 the filepath points to a file with a supported image extension, otherwise False.
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 two float values: [longitude, latitude].
Contain at least two coordinate pairs.
Not be a nested structure beyond one level (i.e., must be a list of list, not a list of list of list).
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 of list 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],
...         [-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 two float 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 a list of list of coordinate list.

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')