Deprecate GeometryEngineRegistry & convenience methods

brick · Oct 9, 2022 · bb73ae1 · bb73ae1
1 parent 8b7a8ee
commit bb73ae1
Show file tree

Hide file tree

Showing 8 changed files with 130 additions and 0 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.