From bb73ae19e777b2e731f51aac102c87b4179e6935 Mon Sep 17 00:00:00 2001 From: Benjamin Morel Date: Sat, 6 Nov 2021 20:10:29 +0100 Subject: [PATCH] Deprecate GeometryEngineRegistry & convenience methods --- CHANGELOG.md | 51 ++++++++++++++++++++++++++++++++++++ src/Curve.php | 7 +++++ src/Geometry.php | 54 +++++++++++++++++++++++++++++++++++++++ src/MultiCurve.php | 4 +++ src/MultiSurface.php | 4 +++ src/Point.php | 2 ++ src/PolyhedralSurface.php | 4 +++ src/Surface.php | 4 +++ 8 files changed, 130 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3eab274..7d3df5b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,56 @@ # Changelog +## [0.7.2](https://github.com/brick/geo/releases/tag/0.7.2) - 2022-10-10 + +🗑️ **Deprecations** + +**The `GeometryEngineRegistry` class has been deprecated.** All convenience methods on Geometry classes that rely on the +`GeometryEngineRegistry` are deprecated, and **will be removed in version `0.8`**. + +You should now explicitly call the `GeometryEngine`, that you can get injected with your dependency injection container. + +Deprecated methods: + +- `Curve::isClosed()` +- `Curve::isRing()` +- `Curve::length()` +- `Geometry::boundary()` +- `Geometry::buffer()` +- `Geometry::centroid()` +- `Geometry::contains()` +- `Geometry::convexHull()` +- `Geometry::crosses()` +- `Geometry::difference()` +- `Geometry::disjoint()` +- `Geometry::distance()` +- `Geometry::equals()` +- `Geometry::envelope()` +- `Geometry::intersection()` +- `Geometry::intersects()` +- `Geometry::isSimple()` +- `Geometry::isValid()` +- `Geometry::locateAlong()` +- `Geometry::locateBetween()` +- `Geometry::maxDistance()` +- `Geometry::overlaps()` +- `Geometry::relate()` +- `Geometry::simplify()` +- `Geometry::snapToGrid()` +- `Geometry::symDifference()` +- `Geometry::touches()` +- `Geometry::transform()` +- `Geometry::union()` +- `Geometry::within()` +- `MultiCurve::isClosed()` +- `MultiCurve::length()` +- `MultiSurface::area()` +- `MultiSurface::pointOnSurface()` +- `Point::azimuth()` +- `PolyhedralSurface::boundingPolygons()` +- `PolyhedralSurface::isClosed()` +- `Surface::area()` +- `Surface::pointOnSurface()` + ## [0.7.1](https://github.com/brick/geo/releases/tag/0.7.1) - 2021-11-06 🐛 **Fixes** diff --git a/src/Curve.php b/src/Curve.php index a0fc0ea..8c5ff2c 100644 --- a/src/Curve.php +++ b/src/Curve.php @@ -28,6 +28,8 @@ public function dimension() : int /** * Returns the length of this Curve in its associated spatial reference. * + * @deprecated Please use `$geometryEngine->length()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -56,6 +58,8 @@ abstract public function endPoint() : Point; * * The curve is closed if `startPoint()` == `endPoint()`. * + * @deprecated Please use `$geometryEngine->isClosed()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -73,6 +77,9 @@ public function isClosed() : bool * The curve is closed if its start point is equal to its end point. * The curve is simple if it does not pass through the same point more than once. * + * @deprecated Please use `$geometryEngine->isClosed() && $geometryEngine->isSimple()`. + * Note that the next version (v0.8) will have a `$geometryEngine->isRing()` method. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. diff --git a/src/Geometry.php b/src/Geometry.php index e8d48b8..87fbe56 100644 --- a/src/Geometry.php +++ b/src/Geometry.php @@ -190,6 +190,8 @@ public function SRID() : int * the maximums. In some cases, this coordinate will be outside the range of * validity for the Spatial Reference System. * + * @deprecated Please use `$geometryEngine->envelope()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -248,6 +250,8 @@ public function isEmpty() : bool * * For example, a polygon with self-intersecting rings is invalid. * + * @deprecated Please use `$geometryEngine->isValid()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -263,6 +267,8 @@ public function isValid() : bool * A geometry is simple if it has no anomalous geometric points, * such as self intersection or self tangency. * + * @deprecated Please use `$geometryEngine->isSimple()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -294,6 +300,8 @@ public function isMeasured() : bool * Because the result of this function is a closure, and hence topologically closed, * the resulting boundary can be represented using representational Geometry primitives. * + * @deprecated Please use `$geometryEngine->boundary()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -308,6 +316,8 @@ public function boundary() : Geometry * * Some geometry engines only support this method on surfaces. * + * @deprecated Please use `$geometryEngine->centroid()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -320,6 +330,8 @@ public function centroid() : Point /** * Returns whether this geometry is spatially equal to another geometry. * + * @deprecated Please use `$geometryEngine->equals()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -335,6 +347,8 @@ public function equals(Geometry $geometry) : bool * The geometries are disjoint if they do not share any space together. * This is the opposite of `intersects()`. * + * @deprecated Please use `$geometryEngine->disjoint()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -350,6 +364,8 @@ public function disjoint(Geometry $geometry) : bool * The geometries intersect if they share any portion of space. * This is the opposite of `disjoint()`. * + * @deprecated Please use `$geometryEngine->intersects()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -364,6 +380,8 @@ public function intersects(Geometry $geometry) : bool * * The geometries touch if they have at least one point in common, but their interiors do not intersect. * + * @deprecated Please use `$geometryEngine->touches()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -378,6 +396,8 @@ public function touches(Geometry $geometry) : bool * * The geometries cross if they have some, but not all, interior points in common. * + * @deprecated Please use `$geometryEngine->crosses()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -392,6 +412,8 @@ public function crosses(Geometry $geometry) : bool * * This is the inverse of `contains()`: `$a->within($b) == $b->contains($a)`. * + * @deprecated Please use `$geometryEngine->within()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -406,6 +428,8 @@ public function within(Geometry $geometry) : bool * * This is the inverse of `within()`: `$a->contains($b) == $b->within($a)`. * + * @deprecated Please use `$geometryEngine->contains()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -420,6 +444,8 @@ public function contains(Geometry $geometry) : bool * * The geometries overlap if they share space, but are not completely contained by each other. * + * @deprecated Please use `$geometryEngine->overlaps()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -439,6 +465,8 @@ public function overlaps(Geometry $geometry) : bool * * @see http://en.wikipedia.org/wiki/DE-9IM * + * @deprecated Please use `$geometryEngine->relate()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -451,6 +479,8 @@ public function relate(Geometry $geometry, string $matrix) : bool /** * Returns a derived geometry collection value that matches the specified m coordinate value. * + * @deprecated Please use `$geometryEngine->locateAlong()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -463,6 +493,8 @@ public function locateAlong(float $mValue) : Geometry /** * Returns a derived geometry collection value that matches the specified range of m coordinate values inclusively. * + * @deprecated Please use `$geometryEngine->locateBetween()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -481,6 +513,8 @@ public function locateBetween(float $mStart, float $mEnd) : Geometry * that the distance between these 2 points is the returned distance * between their geometries. * + * @deprecated Please use `$geometryEngine->distance()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -499,6 +533,8 @@ public function distance(Geometry $geometry) : float * some relatively small error in this distance, but it should be near the * resolution of the coordinates used. * + * @deprecated Please use `$geometryEngine->buffer()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -515,6 +551,8 @@ public function buffer(float $distance) : Geometry * One can think of the convex hull as the geometry you get by wrapping an elastic band around a set of geometries. * This is different from a concave hull which is analogous to shrink-wrapping your geometries. * + * @deprecated Please use `$geometryEngine->convexHull()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -529,6 +567,8 @@ public function convexHull() : Geometry * * The intersection is the shared portion of the two geometries. * + * @deprecated Please use `$geometryEngine->intersection()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -541,6 +581,8 @@ public function intersection(Geometry $geometry) : Geometry /** * Returns a geometry that represents the union of this geometry and another geometry. * + * @deprecated Please use `$geometryEngine->union()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -553,6 +595,8 @@ public function union(Geometry $geometry) : Geometry /** * Returns a geometry that represents the difference of this geometry and another geometry. * + * @deprecated Please use `$geometryEngine->difference()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -568,6 +612,8 @@ public function difference(Geometry $geometry) : Geometry * The result is a geometry that represents the portions of the two geometries that do not intersect. * It is called a symmetric difference because `$a->symDifference($b) == $b->symDifference($a)`. * + * @deprecated Please use `$geometryEngine->symDifference()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -580,6 +626,8 @@ public function symDifference(Geometry $geometry) : Geometry /** * Snap all points of this geometry to a regular grid. * + * @deprecated Please use `$geometryEngine->snapToGrid()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -592,6 +640,8 @@ public function snapToGrid(float $size) : Geometry /** * Returns a simplified version of this geometry using the Douglas-Peucker algorithm. * + * @deprecated Please use `$geometryEngine->simplify()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -604,6 +654,8 @@ public function simplify(float $tolerance) : Geometry /** * Returns the 2-dimensional largest distance between two geometries in projected units. * + * @deprecated Please use `$geometryEngine->maxDistance()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -616,6 +668,8 @@ public function maxDistance(Geometry $geometry) : float /** * Returns a new geometry with its coordinates transformed to a different spatial reference system. * + * @deprecated Please use `$geometryEngine->transform()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. diff --git a/src/MultiCurve.php b/src/MultiCurve.php index 4caff1f..f50f38b 100644 --- a/src/MultiCurve.php +++ b/src/MultiCurve.php @@ -33,6 +33,8 @@ abstract class MultiCurve extends GeometryCollection * * The MultiCurve is considered closed if each element curve is closed. * + * @deprecated Please use `$geometryEngine->isClosed()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -47,6 +49,8 @@ public function isClosed() : bool * * The length is equal to the sum of the lengths of the element Curves. * + * @deprecated Please use `$geometryEngine->length()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. diff --git a/src/MultiSurface.php b/src/MultiSurface.php index 1430395..7b6e3a2 100644 --- a/src/MultiSurface.php +++ b/src/MultiSurface.php @@ -28,6 +28,8 @@ abstract class MultiSurface extends GeometryCollection /** * Returns the area of this MultiSurface, as measured in the spatial reference system of this MultiSurface. * + * @deprecated Please use `$geometryEngine->area()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -40,6 +42,8 @@ public function area() : float /** * Returns a Point guaranteed to be on this MultiSurface. * + * @deprecated Please use `$geometryEngine->pointOnSurface()`. + * * @noproxy * * @psalm-suppress LessSpecificReturnStatement diff --git a/src/Point.php b/src/Point.php index eedd3f3..e1f4b54 100644 --- a/src/Point.php +++ b/src/Point.php @@ -338,6 +338,8 @@ public function getIterator() : ArrayIterator * The azimuth is an angle measured from the north, and is positive clockwise: * North = 0; East = π/2; South = π; West = 3π/2. * + * @deprecated Please use `$geometryEngine->azimuth()`. + * * @param Point $subject Point representing subject of observation. * * @return float Azimuth of the subject relative to the observer. diff --git a/src/PolyhedralSurface.php b/src/PolyhedralSurface.php index 69245e4..e902954 100644 --- a/src/PolyhedralSurface.php +++ b/src/PolyhedralSurface.php @@ -113,6 +113,8 @@ public function patches() : array /** * Returns the collection of polygons in this surface that bounds the given polygon 'p' for any polygon 'p' in the surface. * + * @deprecated Please use `$geometryEngine->boundingPolygons()`. + * * @noproxy * * @psalm-suppress LessSpecificReturnStatement @@ -126,6 +128,8 @@ public function boundingPolygons(Polygon $p) : MultiPolygon } /** + * @deprecated Please use `$geometryEngine->isClosed()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. diff --git a/src/Surface.php b/src/Surface.php index 0fc79f8..e341aca 100644 --- a/src/Surface.php +++ b/src/Surface.php @@ -39,6 +39,8 @@ public function dimension() : int /** * Returns the area of this Surface, as measured in the spatial reference system of this Surface. * + * @deprecated Please use `$geometryEngine->area()`. + * * @noproxy * * @throws GeometryEngineException If the operation is not supported by the geometry engine. @@ -51,6 +53,8 @@ public function area() : float /** * Returns a Point guaranteed to be on this Surface. * + * @deprecated Please use `$geometryEngine->pointOnSurface()`. + * * @noproxy * * @psalm-suppress LessSpecificReturnStatement