"""This module implements abstractions for geospatial PolyLines
in WGS84 and local coordinate frames."""
#
# 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, isfinite, ndarray, vstack
from shapely import get_coordinates, points, transform
from shapely.geometry import LineString
# 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
DerivedPolyLine = TypeVar("DerivedPolyLine", bound="PolyLine")
[docs]
class PolyLine(Geospatial):
def __init__(
self,
locations: list[PolarLocation | CartesianLocation],
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) >= 2, "A PolyLine must contain at least two points!"
# Setup attributes
self.locations = locations
# 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 this polyline."""
if self._locations is None:
self._locations = self._locations_from_geometry()
return self._locations
@locations.setter
def locations(self, value: list[PolarLocation | CartesianLocation]) -> None:
self._locations = value
def _locations_from_geometry(self) -> list[PolarLocation | CartesianLocation]:
"""Builds the locations of a polyline 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 as a plain attribute
if "locations" in state:
state["_locations"] = state.pop("locations")
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]:
return {
"type": "LineString",
"coordinates": [(location.x, location.y) for location in self.locations],
}
[docs]
def sample(self, number_of_samples: int = 1) -> list[DerivedPolyLine]:
"""Sample PolyLines given this PolyLine's uncertainty.
Args:
number_of_samples: How many samples to draw
Returns:
The set of sampled PolyLines, each with same name, identifier etc.
"""
# Check if a distribution is given
if self.distribution is None:
return [
type(self)(
self.locations, self.location_type, self.name, self.identifier, self.covariance
)
] * number_of_samples
# Gather all the sampled PolyLines
sampled_polylines = []
for sample in self.distribution.sample(number_of_samples).T:
# Translate each polyline location by sampled translation
sampled_locations = [location + vstack(sample) for location in self.locations]
sampled_polylines.append(
type(self)(
sampled_locations,
self.location_type,
self.name,
self.identifier,
self.covariance,
)
)
return sampled_polylines
[docs]
def to_numpy(self) -> ndarray:
"""Converts the coordinates defining this polyline into a :class:`numpy.ndarray`.
Returns:
An array with shape ``(number of locations, 2)``, where each location
is represented by a pair of ``(longitude, latitude)``, each in degrees.
See Also:
:meth:`~from_numpy`
"""
return array(
[(location.x, location.y) for location in self.locations],
dtype="float64",
order="C",
)
[docs]
class PolarPolyLine(PolyLine):
"""A polyline (line string) based on WGS84 coordinates.
Note:
This class does not yet support simplification as it was not required so far.
Args:
locations: The two or more points that make up this polyline; see :attr:`~.locations`
location_type: The type of this polygon
name: An optional name of this polygon
identifier: The polyline's optional unique identifier, in :math:`[0, 2**63)`
uncertainty: An optional value representing the variance of this polyline's
latitudes and longitudes respectively
"""
def __init__(
self,
locations: list[PolarLocation],
location_type: str | None = None,
name: str | None = None,
identifier: int | None = None,
covariance: ndarray | None = None,
) -> None:
# Setup PolyLine
super().__init__(locations, location_type, name, identifier, covariance)
[docs]
def to_cartesian(self, origin: PolarLocation) -> "CartesianPolyLine":
"""Projects this polyline to a Cartesian one according to the given global reference.
Args:
origin: The reference by which to project onto the local tangent plane
Returns:
The cartesian representation of this polyline with the given reference point being set
"""
# convert to cartesian
coordinates = self.to_numpy()
coordinates[:, 0], coordinates[:, 1] = origin.projection(
coordinates[:, 0], coordinates[:, 1]
)
return CartesianPolyLine.from_numpy(
coordinates,
origin=origin,
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,
)
[docs]
@classmethod
def from_numpy(cls, data: ndarray, *args, **kwargs) -> "PolarPolyLine":
"""Create a polar polyline from a numpy representation.
Args:
data: An array with shape ``(number of locations, 2)``, where each location
is represented by a pair of ``(longitude, latitude)``, each in degrees.
*args: Positional arguments to be passed to :class:`~PolarPolyLine`
**kwargs: Keyword arguments to be passed to :class:`~PolarPolyLine`
Returns:
The polar polyline created from the given coordinates an other parameters
Raises:
:class:`AssertionError`: If the shape of ``array`` is invalid
See Also:
:meth:`~to_numpy`
"""
assert len(data.shape) == 2
assert data.shape[1] == 2
assert isfinite(data).all()
return cls(
[PolarLocation(x, y) for (x, y) in data],
*args,
**kwargs,
)
def __repr__(self) -> str:
locations = ", ".join(str(loc) for loc in self.locations)
return f"PolarPolyLine(locations=[{locations}]{self._repr_extras})"
[docs]
class CartesianPolyLine(PolyLine):
"""A Cartesian polyline (line string) in local coordinates.
Args:
locations: The list of two or more locations that
this shape consists of; see :attr:`~locations`
location_type: The type of this polyline
name: The name of this polyline
identifier: The polyline's optional unique identifier, in :math:`[0, 2**63)`
origin: A reference that can be used to project this cartesian representation (back)
into a polar one
covariance: An optional value representing the variance of this polyline's
east and north coordinates respectively
"""
def __init__(
self,
locations: list[CartesianLocation],
location_type: str | None = None,
name: str | None = None,
identifier: int | None = None,
covariance: ndarray | None = None,
origin: PolarLocation | None = None,
):
# Setup attributes
self.origin = origin
self.geometry = LineString([location.geometry.coords[0] for location in locations])
# Setup PolyLine
PolyLine.__init__(self, locations, location_type, name, identifier, covariance)
[docs]
@classmethod
def from_geometry(
cls,
geometry: LineString,
location_type: str | None = None,
name: str | None = None,
identifier: int | None = None,
covariance: ndarray | None = None,
origin: PolarLocation | None = None,
) -> "CartesianPolyLine":
"""Create a polyline from a shapely line string.
The polyline's :attr:`~locations` are only built from the geometry when they are first
accessed, which keeps creating many polylines cheap.
Args:
geometry: The shapely line string in local coordinates
location_type: The type of this polyline
name: The name of this polyline
identifier: The polyline's optional unique identifier, in :math:`[0, 2**63)`
covariance: An optional value representing the variance of this polyline'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 polyline with the given geometry and other parameters
"""
polyline = cls.__new__(cls)
polyline.origin = origin
polyline.geometry = geometry
polyline._locations = None
polyline.covariance = covariance
Geospatial.__init__(polyline, location_type=location_type, name=name, identifier=identifier)
return polyline
def _locations_from_geometry(self) -> list[CartesianLocation]:
coordinates = get_coordinates(self.geometry)
return [
CartesianLocation(x, y, geometry=point) for (x, y), point in zip(coordinates, points(coordinates))
]
[docs]
def sample(self, number_of_samples: int = 1) -> list["CartesianPolyLine"]:
"""Sample polylines given this polyline'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 polylines, each with same name, identifier etc.
"""
# Check if a distribution is given
if self.distribution is None:
return super().sample(number_of_samples)
sampled_polylines = []
for translation in self.distribution.sample(number_of_samples).T:
geometry = transform(self.geometry, lambda coordinates: coordinates + translation)
sampled_polylines.append(
CartesianPolyLine.from_geometry(
geometry, self.location_type, self.name, self.identifier, self.covariance, self.origin
)
)
return sampled_polylines
[docs]
def to_polar(self, origin: PolarLocation | None = None) -> PolarPolyLine:
"""Computes the polar representation of this polyline.
Args:
origin: The global reference to be used for back-projection, must be set if and only if
:attr:`~origin` is ``None``
Returns:
The global, polar representation of this polyline
"""
# Decide which origin to use
if origin is None:
if self.origin is None:
raise ValueError(
"Need to give 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(
"Provided an explicit origin while the instance already has a different one!"
)
# convert to cartesian
coordinates = self.to_numpy()
coordinates[:, 0], coordinates[:, 1] = origin.projection(
coordinates[:, 0], coordinates[:, 1], inverse=True
)
return PolarPolyLine.from_numpy(
coordinates,
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]
@classmethod
def from_numpy(cls, data: ndarray, *args, **kwargs) -> "CartesianPolyLine":
"""Create a Cartesian polyline from a numpy representation.
Args:
data: An array with shape ``(number of locations, 2)``, where each location
is represented by a pair of ``(east, north)``, each in degrees.
*args: Positional arguments to be passed to :class:`~CartesianPolyLine`
**kwargs: Keyword arguments to be passed to :class:`~CartesianPolyLine`
Returns:
The polar polyline created from the given coordinates an other parameters
Raises:
:class:`AssertionError`: If the shape of ``array`` is invalid
See Also:
:meth:`~to_numpy`
"""
assert len(data.shape) == 2
assert data.shape[1] == 2
assert isfinite(data).all()
return cls(
[CartesianLocation(x, y) for (x, y) in data],
*args,
**kwargs,
)
[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 PolyLine 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.coords)
return f"CartesianPolyLine(locations=[{locations}]{origin}{self._repr_extras})"
def __str__(self) -> str:
# this is required to override shapely.geometry.LineString.__str__()
return self.__repr__()