"""This module implements abstractions for geospatial, polygonal shapes in WGS84 and local cartesian
coordinates using shapely."""
#
# Copyright (c) Simon Kohaut, Honda Research Institute Europe GmbH, Felix Divo, and contributors
#
# This file is part of ProMis and licensed under the BSD 3-Clause License.
# You should have received a copy of the BSD 3-Clause License along with ProMis.
# If not, see https://opensource.org/license/bsd-3-clause/.
#
# Standard Library
from math import degrees, radians
from typing import Any, TypeVar
# Third Party
from numpy import array, asarray, isfinite, ndarray, vstack
from shapely import get_coordinates, points, transform
from shapely.geometry import LinearRing
from shapely.geometry import Polygon as ShapelyPolygon
# ProMis
from promis.geo.geospatial import Geospatial
from promis.geo.helpers import meters_to_radians, radians_to_meters
from promis.geo.location import CartesianLocation, PolarLocation
from promis.models import Gaussian
#: Helper to define <Polar|Cartesian>Location operatios within base class
DerivedPolygon = TypeVar("DerivedPolygon", bound="Polygon")
def _ring_to_locations(ring: LinearRing) -> list[CartesianLocation]:
"""Creates the locations along a ring of a shapely polygon, building their points at once."""
coordinates = get_coordinates(ring)
return [
CartesianLocation(x, y, geometry=point) for (x, y), point in zip(coordinates, points(coordinates))
]
class Polygon(Geospatial):
def __init__(
self,
locations: list[PolarLocation | CartesianLocation],
holes: list[list[PolarLocation | CartesianLocation]] | None = None,
location_type: str | None = None,
name: str | None = None,
identifier: int | None = None,
covariance: ndarray | None = None,
) -> None:
# Assertions on the given locations
assert len(locations) >= 3, "A polygon must contain at least three points!"
# Setup attributes
self.locations = locations
self.holes = holes if holes else []
# Closes the ring by connecting last and first position
if locations[0].x != locations[-1].x or locations[0].y != locations[-1].y:
self.locations.append(locations[0])
for hole in self.holes:
if hole[0].x != hole[-1].x or hole[0].y != hole[-1].y:
hole.append(hole[0])
# Setup Gaussian distribution for sampling the polygon
self.covariance = covariance
# Setup Geospatial
super().__init__(location_type=location_type, name=name, identifier=identifier)
@property
def locations(self) -> list[PolarLocation | CartesianLocation]:
"""The points that make up the border of this polygon, with the first one repeated last."""
if self._locations is None:
self._locations, self._holes = self._locations_from_geometry()
return self._locations
@locations.setter
def locations(self, value: list[PolarLocation | CartesianLocation]) -> None:
self._locations = value
@property
def holes(self) -> list[list[PolarLocation | CartesianLocation]]:
"""The points that make up the holes in this polygon, each with the first one repeated last."""
if self._holes is None:
self._locations, self._holes = self._locations_from_geometry()
return self._holes
@holes.setter
def holes(self, value: list[list[PolarLocation | CartesianLocation]]) -> None:
self._holes = value
def _locations_from_geometry(
self,
) -> tuple[list[PolarLocation | CartesianLocation], list[list[PolarLocation | CartesianLocation]]]:
"""Builds the border and hole locations of a polygon that was created from its geometry."""
raise NotImplementedError(f"{type(self).__name__} is always created from its locations")
def __setstate__(self, state: dict[str, Any]) -> None:
# Pickles may store the locations and holes as plain attributes
if "locations" in state:
state["_locations"] = state.pop("locations")
if "holes" in state:
state["_holes"] = state.pop("holes")
self.__dict__.update(state)
@property
def covariance(self) -> ndarray:
return self._covariance
@covariance.setter
def covariance(self, value: ndarray | None) -> None:
self._covariance = value
self._distribution = None
@property
def distribution(self) -> Gaussian | None:
"""The Gaussian this shape's translation is sampled from, or None if it is exact.
Built on first access; see :attr:`promis.geo.location.Location.distribution`.
"""
if self._distribution is None and self._covariance is not None:
self._distribution = Gaussian(vstack([0.0, 0.0]), self._covariance)
return self._distribution
@property
def __geo_interface__(self) -> dict[str, Any]:
exterior = [(location.x, location.y) for location in self.locations]
interiors = [[(location.x, location.y) for location in hole] for hole in self.holes]
coordinates = [exterior] + interiors
return {
"type": "Polygon",
"coordinates": coordinates,
}
def sample(self, number_of_samples: int = 1) -> list[DerivedPolygon]:
"""Sample a polar polygon given this polygon's uncertainty.
Args:
number_of_samples: How many samples to draw
Returns:
The set of sampled polygons, each with same name, identifier etc.
"""
# Check if a distribution is given
if self.distribution is None:
return [
type(self)(
self.locations,
self.holes,
self.location_type,
self.name,
self.identifier,
self.covariance,
)
] * number_of_samples
# Gather all the sampled polygons
sampled_polygons = []
for sample in self.distribution.sample(number_of_samples).T:
# Translate each border location by sampled translation
sampled_locations = [location + vstack(sample) for location in self.locations]
# Translate each internal border location by sampled translation
sampled_holes = [
[location + vstack(sample) for location in hole] for hole in self.holes
]
sampled_polygons.append(
type(self)(
sampled_locations,
sampled_holes,
self.location_type,
self.name,
self.identifier,
self.covariance,
)
)
return sampled_polygons
[docs]
class PolarPolygon(Polygon):
"""A polygon based on WGS84 coordinates.
An object with only a single point may be represented by
a polygon with three times the same location.
Examples:
Lets first create the perimeter of the polygon
as a list of PolarLocation objects.
>>> locations = [PolarLocation(-1.0, 1.0), PolarLocation(1.0, 1.0),
... PolarLocation(1.0, -1.0), PolarLocation(-1.0, -1.0)]
Now, we can build a polygon from these locations like so:
>>> polygon = PolarPolygon(locations)
Given another list of locations, e.g.,
>>> holes = [[PolarLocation(-0.5, 0.5), PolarLocation(0.5, 0.5),
... PolarLocation(0.5, -0.5), PolarLocation(-0.5, -0.5)]]
we can also build a polygon that contains holes:
>>> polygon = PolarPolygon(locations, holes)
Given a covariance of this polygons translation, random samples can be drawn.
>>> from numpy import eye
>>> polygon = PolarPolygon(locations, covariance=eye(2))
>>> random_samples = polygon.sample(10)
PolarPolygons can also be created from numpy data.
>>> from numpy import array
>>> locations = array([[-1.0, 1.0, 1.0, -1.0], [1.0, 1.0, -1.0, -1.0]])
>>> polygon = PolarPolygon.from_numpy(locations)
Finally, a PolarPolygon can be turned into a CartesianPolygon
given a reference origin in polar coordinates.
>>> origin = PolarLocation(0.0, 0.0)
>>> cartesian_polygon = polygon.to_cartesian(origin)
Args:
locations: The points that make up this polygon; see :attr:`~.locations`
holes: The points that make up holes in this polygon
location_type: The type of this polygon
name: An optional name of this polygon
identifier: The polygon's optional unique identifier, in :math:`[0, 2**63)`
covariance: An optional matrix representing the variance of this polygon's
latitude and longitude respectively
"""
def __init__(
self,
locations: list[PolarLocation],
holes: list[list[PolarLocation]] | None = None,
location_type: str | None = None,
name: str | None = None,
identifier: int | None = None,
covariance: ndarray | None = None,
) -> None:
# Setup Polygon
super().__init__(locations, holes, location_type, name, identifier, covariance)
[docs]
@classmethod
def from_numpy(cls, data: ndarray, *args, **kwargs) -> "PolarPolygon":
"""Create a polygon from a numpy representation.
Args:
data: An array with shape ``(2, number_of_locations)``
args: Positional arguments to be passed to the new polygon
kwargs: Keyword arguments to be passed to the new polygon
Returns:
The polygon created from the given coordinates and other parameters
Raises:
:class:`AssertionError`: If the shape or content of ``data`` is invalid
See Also:
:meth:`~to_numpy`
"""
# Assert that data is a vertical stack of two finite values
assert len(data.shape) == 2
assert data.shape[0] == 2
assert isfinite(data).all()
# Return appropriate polygon type
return cls(
[PolarLocation(x, y) for (x, y) in data.T],
*args,
**kwargs,
)
[docs]
def to_cartesian(self, origin: PolarLocation) -> "CartesianPolygon":
"""Projects the polygon to a Cartesian one according to a given global reference.
Args:
origin: The reference point by which to project onto the local tangent plane
Returns:
The cartesian representation of this polygon with the given reference point being set
"""
return CartesianPolygon(
[location.to_cartesian(origin) for location in self.locations],
[[location.to_cartesian(origin) for location in hole] for hole in self.holes],
location_type=self.location_type,
name=self.name,
identifier=self.identifier,
covariance=radians_to_meters(
array(
[radians(degree) for degree in self.distribution.covariance.reshape(4)]
).reshape(2, 2)
)
if self.distribution is not None
else None,
origin=origin,
)
def __repr__(self) -> str:
locations = ", ".join(str(loc) for loc in self.locations)
return f"PolarPolygon(locations=[{locations}]{self._repr_extras})"
[docs]
class CartesianPolygon(Polygon):
"""A cartesian polygon based on local coordinates with an optional global reference.
Examples:
Lets first create the perimeter of the polygon as a list of CartesianLocation objects.
>>> locations = [CartesianLocation(-1.0, 1.0), CartesianLocation(1.0, 1.0),
... CartesianLocation(1.0, -1.0), CartesianLocation(-1.0, -1.0)]
Now, we can build a polygon from these locations like so:
>>> polygon = CartesianPolygon(locations)
Given another list of locations, e.g.,
>>> holes = [[CartesianLocation(-0.5, 0.5), CartesianLocation(0.5, 0.5),
... CartesianLocation(0.5, -0.5), CartesianLocation(-0.5, -0.5)]]
we can also build a polygon that contains holes:
>>> polygon = CartesianPolygon(locations, holes)
Given a covariance of this polygons translation, random samples can be drawn.
>>> from numpy import eye
>>> polygon = CartesianPolygon(locations, covariance=eye(2))
>>> random_samples = polygon.sample(10)
CartesianPolygons can also be created from numpy data.
>>> from numpy import array
>>> locations = array([[-1.0, 1.0, 1.0, -1.0], [1.0, 1.0, -1.0, -1.0]])
>>> polygon = CartesianPolygon.from_numpy(locations)
Finally, a CartesianPolygon can be turned into a PolarPolygon
given a reference origin in polar coordinates.
>>> origin = PolarLocation(49.873163174, 8.653830718)
>>> polar_polygon = polygon.to_polar(origin)
Args:
locations: The list of locations that this shape consists of; see :attr:`~.locations`
holes: The points that make up holes in this polygon
location_type: The type of this polygon
name: The name of this polygon
identifier: The polygon's optional unique identifier, in :math:`[0, 2**63)`
covariance: An optional matrix representing the variance of this polygon's
latitude and longitude respectively
origin: A reference that can be used to project this cartesian representation (back)
into a polar one
"""
# Shapely Polygon has some abstract methods we do not override here
def __init__(
self,
locations: list[CartesianLocation],
holes: list[list[CartesianLocation]] | None = None,
location_type: str | None = None,
name: str | None = None,
identifier: int | None = None,
covariance: ndarray | None = None,
origin: PolarLocation | None = None,
) -> None:
# Setup attributes
self.origin = origin
if holes is not None:
self.geometry = ShapelyPolygon(
[location.geometry.coords[0] for location in locations],
[[location.geometry.coords[0] for location in hole] for hole in holes],
)
else:
self.geometry = ShapelyPolygon([location.geometry.coords[0] for location in locations])
# Setup Polygon
Polygon.__init__(self, locations, holes, location_type, name, identifier, covariance)
[docs]
@classmethod
def from_geometry(
cls,
geometry: ShapelyPolygon,
location_type: str | None = None,
name: str | None = None,
identifier: int | None = None,
covariance: ndarray | None = None,
origin: PolarLocation | None = None,
) -> "CartesianPolygon":
"""Create a polygon from a shapely polygon.
The polygon's :attr:`~locations` and :attr:`~holes` are only built from the geometry
when they are first accessed, which keeps creating many polygons cheap.
Args:
geometry: The shapely polygon in local coordinates
location_type: The type of this polygon
name: The name of this polygon
identifier: The polygon's optional unique identifier, in :math:`[0, 2**63)`
covariance: An optional matrix representing the variance of this polygon's
east and north coordinates respectively
origin: A reference that can be used to project this cartesian representation (back)
into a polar one
Returns:
The polygon with the given geometry and other parameters
"""
polygon = cls.__new__(cls)
polygon.origin = origin
polygon.geometry = geometry
polygon._locations = None
polygon._holes = None
polygon.covariance = covariance
Geospatial.__init__(polygon, location_type=location_type, name=name, identifier=identifier)
return polygon
def _locations_from_geometry(self) -> tuple[list[CartesianLocation], list[list[CartesianLocation]]]:
return _ring_to_locations(self.geometry.exterior), [
_ring_to_locations(ring) for ring in self.geometry.interiors
]
[docs]
def sample(self, number_of_samples: int = 1) -> list["CartesianPolygon"]:
"""Sample polygons given this polygon's uncertainty.
Each sample translates the whole geometry at once, and builds its locations only
when they are accessed, since spatial relations only need the geometry.
Args:
number_of_samples: How many samples to draw
Returns:
The set of sampled polygons, each with same name, identifier etc.
"""
# Check if a distribution is given
if self.distribution is None:
return super().sample(number_of_samples)
sampled_polygons = []
for translation in self.distribution.sample(number_of_samples).T:
geometry = transform(self.geometry, lambda coordinates: coordinates + translation)
sampled_polygons.append(
CartesianPolygon.from_geometry(
geometry, self.location_type, self.name, self.identifier, self.covariance, self.origin
)
)
return sampled_polygons
[docs]
@classmethod
def from_numpy(cls, data: ndarray, *args, **kwargs) -> "CartesianPolygon":
"""Create a polygon from a numpy representation.
Args:
data: An array with shape ``(2, number_of_locations)``
args: Positional arguments to be passed to the new polygon
kwargs: Keyword arguments to be passed to the new polygon
Returns:
The polygon created from the given coordinates and other parameters
Raises:
:class:`AssertionError`: If the shape or content of ``data`` is invalid
See Also:
:meth:`~to_numpy`
"""
# Assert that data is a vertical stack of two finite values
assert len(data.shape) == 2
assert data.shape[0] == 2
assert isfinite(data).all()
# Transform the holes too, if given
if args and isinstance(args[0], list):
args[0] = [[CartesianLocation(x, y) for x, y in hole.T] for hole in args[0]]
elif "holes" in kwargs:
kwargs["holes"] = [
[CartesianLocation(x, y) for x, y in hole.T] for hole in kwargs["holes"]
]
# Return appropriate polygon type
return cls(
[CartesianLocation(x, y) for (x, y) in data.T],
*args,
**kwargs,
)
[docs]
def to_polar(self, origin: PolarLocation | None = None) -> PolarPolygon:
"""Computes the polar representation of this shape.
Args:
origin: The global reference to be used for back-projection, must be set if and only if
:attr:`~promis.geo.CartesianPolygon.origin` is ``None``
Returns:
The global, polar representation of this geometry
"""
# Check that one origin point is given
if origin is None:
if self.origin is None:
raise ValueError(
"You need to provide an explicit origin when the instance does not have one"
)
origin = self.origin
elif self.origin is not None and origin is not self.origin:
raise ValueError(
"You provided an explicit origin while the instance already has a different one"
)
# Hole locations to polar
holes = [[location.to_polar(origin) for location in hole] for hole in self.holes]
# Return appropriate Polygon in polar coordinates
return PolarPolygon(
[location.to_polar(origin) for location in self.locations],
holes,
location_type=self.location_type,
name=self.name,
identifier=self.identifier,
covariance=array(
[degrees(rad) for rad in meters_to_radians(self.distribution.covariance).reshape(4)]
).reshape(2, 2)
if self.distribution is not None
else None,
)
[docs]
def plot(self, axis, **kwargs) -> None:
"""Plots this polygon using Matplotlib.
Args:
axis: The axis object to use for plotting
kwargs: Keyword arguments to pass to Matplotlib
"""
# Plotting is optional and matplotlib is slow to load
from matplotlib.collections import PatchCollection
from matplotlib.patches import PathPatch
from matplotlib.path import Path
path = Path.make_compound_path(
Path(asarray(self.geometry.exterior.coords)[:, :2]),
*[Path(asarray(ring.coords)[:, :2]) for ring in self.geometry.interiors],
)
patch = PathPatch(path, **kwargs)
collection = PatchCollection([patch], **kwargs)
axis.add_collection(collection, autolim=True)
axis.autoscale_view()
[docs]
def distance(self, other: Any) -> float:
return self.geometry.distance(other.geometry)
[docs]
def send_to_gui(self, ip: str, port: int, timeout: float):
raise NotImplementedError("Cartesian Polygon does not have geospatial feature to send to gui!")
def __repr__(self) -> str:
origin = f", origin={self.origin}" if self.origin is not None else ""
locations = ", ".join(f"({x}, {y})" for x, y in self.geometry.exterior.coords)
return f"CartesianPolygon(locations=[{locations}]{origin}{self._repr_extras})"
def __str__(self) -> str:
# This is required to override shapely.geometry.Polygon.__str__()
return self.__repr__()
[docs]
@classmethod
def make_centered_box(
cls,
width: float,
height: float,
offset: CartesianLocation = CartesianLocation(0, 0),
**kwargs,
) -> "CartesianPolygon":
"""Generates a box centered around a given offset.
Args:
width: The width of the map in meters
height: The height of the map in meters
kwargs: Additional keyword arguments to pass to the polygon, such as an origin
Returns:
The box as a polygon
"""
return cls(
[
# clockwise: top-left, ...
CartesianLocation(east=offset.east - width / 2, north=offset.north + height / 2),
CartesianLocation(east=offset.east + width / 2, north=offset.north + height / 2),
CartesianLocation(east=offset.east + width / 2, north=offset.north - height / 2),
CartesianLocation(east=offset.east - width / 2, north=offset.north - height / 2),
],
**kwargs,
)