Added support for simplifier monitor

This allows code calling the GeometrySimplifier to be notified
of events related to the simplification algorithm.
For example, the project geometry-simplifier-debug uses these events to draw images and create videos of the simplification process.
And the tests for the simplifier use this to collect data to make further assertions on the results.

Author: craigtaverner

libs/geo/src/main/java/org/elasticsearch/geometry/simplify/GeometrySimplifier.java

@@ -23,13 +23,17 @@ public abstract class GeometrySimplifier<T extends Geometry> {
     protected final int maxPoints;
     protected final SimplificationErrorCalculator calculator;
     protected final PointError[] points;
+    protected final Monitor monitor;
     protected int length;
+    protected String description;
 
     protected final PriorityQueue<PointError> queue = new PriorityQueue<>();
 
-    public GeometrySimplifier(int maxPoints, SimplificationErrorCalculator calculator) {
+    protected GeometrySimplifier(String description, int maxPoints, SimplificationErrorCalculator calculator, Monitor monitor) {
+        this.description = description;
         this.maxPoints = maxPoints;
         this.calculator = calculator;
+        this.monitor = monitor;
         this.points = new PointError[maxPoints];
         this.length = 0;
     }
@@ -61,9 +65,11 @@ public void consume(double x, double y) {
             // Remove point with lowest error
             PointError toRemove = queue.remove();
             removeAndAdd(toRemove.index, pointError);
+            notifyMonitorPointRemoved(toRemove);
         } else {
             this.points[length] = pointError;
             length++;
+            notifyMonitorPointAdded();
         }
     }
 
@@ -134,22 +140,100 @@ public String toString() {
         }
 
         @Override
-        public double getX() {
+        public double x() {
             return x;
         }
 
         @Override
-        public double getY() {
+        public double y() {
             return y;
         }
     }
 
+    /**
+     * Implementation of this interface will receive calls with internal data at each step of the
+     * simplification algorithm. This is of use for debugging complex cases, as well as gaining insight
+     * into the way the algorithm works. Data provided in the callback includes:
+     * <ul>
+     *     <li>String description of current process</li>
+     *     <li>List of points in current simplification</li>
+     *     <li>Last point removed from the simplification</li>
+     * </ul>
+     * mode, list of points representing the current linked-list of internal nodes used for
+     * triangulation, and a list of triangles so far created by the algorithm.
+     */
+    public interface Monitor {
+        /** Every time a point is added to the collection, this method sends the resulting state */
+        void pointAdded(String status, List<SimplificationErrorCalculator.PointLike> points);
+
+        /** Every time a point is added and another is removed from the collection, this method sends the resulting state */
+        void pointRemoved(
+            String status,
+            List<SimplificationErrorCalculator.PointLike> points,
+            SimplificationErrorCalculator.PointLike removed,
+            double error,
+            SimplificationErrorCalculator.PointLike previous,
+            SimplificationErrorCalculator.PointLike next
+        );
+
+        /**
+         * When a new simplification or sub-simplification starts, this provides a description of the simplification,
+         * as well as the current maxPoints target for this simplification. For a single simplification, maxPoints
+         * will simply be the value passed to the constructor, but compound simplifications will calculate smaller
+         * numbers for sub-simplifications (eg. holes in polygons, or shells in multi-polygons).
+         */
+        void startSimplification(String description, int maxPoints);
+
+        /**
+         * When simplification or sub-simplification is completed, this is called.
+         */
+        void endSimplification(String description, List<SimplificationErrorCalculator.PointLike> points);
+    }
+
+    protected void notifyMonitorSimplificationStart() {
+        if (monitor != null) {
+            monitor.startSimplification(description, maxPoints);
+        }
+    }
+
+    protected void notifyMonitorSimplificationEnd() {
+        if (monitor != null) {
+            monitor.endSimplification(description, getCurrentPoints());
+        }
+    }
+
+    protected void notifyMonitorPointRemoved(PointError removed) {
+        if (monitor != null) {
+            PointError previous = points[removed.index - 1];
+            PointError next = points[removed.index];
+            monitor.pointRemoved(description + ".addAndRemovePoint()", getCurrentPoints(), removed, removed.error, previous, next);
+        }
+    }
+
+    protected void notifyMonitorPointAdded() {
+        if (monitor != null) {
+            monitor.pointAdded(description + ".addPoint()", getCurrentPoints());
+        }
+    }
+
+    private List<SimplificationErrorCalculator.PointLike> getCurrentPoints() {
+        ArrayList<SimplificationErrorCalculator.PointLike> simplification = new ArrayList<>();
+        for (int i = 0; i < length; i++) {
+            simplification.add(points[i]);
+        }
+        return simplification;
+    }
+
     /**
      * Simplifies a Line geometry to the specified maximum number of points.
      */
     public static class LineStrings extends GeometrySimplifier<Line> {
         public LineStrings(int maxPoints, SimplificationErrorCalculator calculator) {
-            super(maxPoints, calculator);
+            this(maxPoints, calculator, null);
+        }
+
+        public LineStrings(int maxPoints, SimplificationErrorCalculator calculator, Monitor monitor) {
+            super("LineString", maxPoints, calculator, monitor);
         }
 
         @Override
@@ -158,9 +242,11 @@ public Line simplify(Line line) {
                 return line;
             }
             reset();
+            notifyMonitorSimplificationStart();
             for (int i = 0; i < line.length(); i++) {
                 consume(line.getX(i), line.getY(i));
             }
+            notifyMonitorSimplificationEnd();
             return produce();
         }
 
@@ -185,7 +271,11 @@ public Line produce() {
      */
     public static class LinearRings extends GeometrySimplifier<LinearRing> {
         public LinearRings(int maxPoints, SimplificationErrorCalculator calculator) {
-            super(maxPoints, calculator);
+            this(maxPoints, calculator, null);
+        }
+
+        public LinearRings(int maxPoints, SimplificationErrorCalculator calculator, Monitor monitor) {
+            super("LinearRing", maxPoints, calculator, monitor);
             assert maxPoints >= 4;
         }
 
@@ -195,9 +285,11 @@ public LinearRing simplify(LinearRing ring) {
                 return ring;
             }
             reset();
+            notifyMonitorSimplificationStart();
             for (int i = 0; i < ring.length(); i++) {
                 consume(ring.getX(i), ring.getY(i));
             }
+            notifyMonitorSimplificationEnd();
             return produce();
         }
 
@@ -221,7 +313,11 @@ public static class Polygons extends GeometrySimplifier<Polygon> {
         ArrayList<GeometrySimplifier<LinearRing>> holeSimplifiers = new ArrayList<>();
 
         public Polygons(int maxPoints, SimplificationErrorCalculator calculator) {
-            super(maxPoints, calculator);
+            this(maxPoints, calculator, null);
+        }
+
+        public Polygons(int maxPoints, SimplificationErrorCalculator calculator, Monitor monitor) {
+            super("Polygon", maxPoints, calculator, monitor);
         }
 
         @Override
@@ -237,17 +333,20 @@ public Polygon simplify(Polygon geometry) {
                 return geometry;
             }
             reset();
+            notifyMonitorSimplificationStart();
             for (int i = 0; i < ring.length(); i++) {
                 consume(ring.getX(i), ring.getY(i));
             }
             for (int i = 0; i < geometry.getNumberOfHoles(); i++) {
                 LinearRing hole = geometry.getHole(i);
                 double simplificationFactor = (double) maxPoints / ring.length();
                 int maxHolePoints = Math.max(4, (int) (simplificationFactor * hole.length()));
-                LinearRings holeSimplifier = new LinearRings(maxHolePoints, calculator);
+                LinearRings holeSimplifier = new LinearRings(maxHolePoints, calculator, this.monitor);
+                holeSimplifier.description = "Polygon.Hole";
                 holeSimplifiers.add(holeSimplifier);
                 holeSimplifier.simplify(hole);
             }
+            notifyMonitorSimplificationEnd();
             return produce();
         }
 
@@ -267,7 +366,7 @@ private List<LinearRing> produceHoles() {
      * It does not make use of its own simplifier capabilities.
      * The largest inner polygon is simplified to the specified maxPoints, while the rest are simplified
      * to a maxPoints value that is a fraction of their size compared to the largest size.
-     *
+     * <p>
      * Note that this simplifier cannot work in streaming mode.
      * Since a MultiPolygon can contain more than one polygon,
      * the <code>consume(Point)</code> method would not know which polygon to add to.
@@ -279,7 +378,11 @@ public static class MultiPolygons extends GeometrySimplifier<MultiPolygon> {
         ArrayList<Integer> indexes = new ArrayList<>();
 
         public MultiPolygons(int maxPoints, SimplificationErrorCalculator calculator) {
-            super(maxPoints, calculator);
+            this(maxPoints, calculator, null);
+        }
+
+        public MultiPolygons(int maxPoints, SimplificationErrorCalculator calculator, Monitor monitor) {
+            super("MultiPolygon", maxPoints, calculator, monitor);
         }
 
         @Override
@@ -296,18 +399,21 @@ public MultiPolygon simplify(MultiPolygon geometry) {
                 Polygon polygon = geometry.get(i);
                 maxPolyLength = Math.max(maxPolyLength, polygon.getPolygon().length());
             }
+            notifyMonitorSimplificationStart();
             for (int i = 0; i < geometry.size(); i++) {
                 Polygon polygon = geometry.get(i);
                 double simplificationFactor = (double) maxPoints / maxPolyLength;
                 int maxPolyPoints = Math.max(4, (int) (simplificationFactor * polygon.getPolygon().length()));
-                Polygons simplifier = new Polygons(maxPolyPoints, calculator);
+                Polygons simplifier = new Polygons(maxPolyPoints, calculator, monitor);
+                simplifier.description = "MultiPolygon.Polygon[" + i + "]";
                 simplifier.simplify(polygon);
                 if (simplifier.length > 0) {
                     // Invalid polygons (all points co-located) will not be simplified
                     polygonSimplifiers.add(simplifier);
                     indexes.add(i);
                 }
             }
+            notifyMonitorSimplificationEnd();
             return produce();
         }
 

libs/geo/src/main/java/org/elasticsearch/geometry/simplify/SimplificationErrorCalculator.java

@@ -14,15 +14,16 @@ public interface SimplificationErrorCalculator {
     double calculateError(PointLike left, PointLike middle, PointLike right);
 
     interface PointLike {
-        double getX();
+        double x();
 
-        double getY();
+        double y();
     }
 
     static SimplificationErrorCalculator byName(String calculatorName) {
         return switch (calculatorName.toLowerCase(Locale.ROOT)) {
             case "cartesiantrianglearea" -> new CartesianTriangleAreaCalculator();
             case "trianglearea" -> new TriangleAreaCalculator();
+            case "triangleheight" -> new TriangleHeightCalculator();
             case "frecheterror" -> new FrechetErrorCalculator();
             default -> throw new IllegalArgumentException("Unknown geometry simplification error calculator: " + calculatorName);
         };
@@ -35,10 +36,10 @@ class CartesianTriangleAreaCalculator implements SimplificationErrorCalculator {
 
         @Override
         public double calculateError(PointLike left, PointLike middle, PointLike right) {
-            double xb = middle.getX() - left.getX();
-            double yb = middle.getY() - left.getY();
-            double xc = right.getX() - left.getX();
-            double yc = right.getY() - left.getY();
+            double xb = middle.x() - left.x();
+            double yb = middle.y() - left.y();
+            double xc = right.x() - left.x();
+            double yc = right.y() - left.y();
             return 0.5 * Math.abs(xb * yc - xc * yb);
         }
     }
@@ -70,7 +71,39 @@ public double calculateError(PointLike left, PointLike middle, PointLike right)
         }
 
         private double distance(PointLike a, PointLike b) {
-            return SloppyMath.haversinMeters(a.getY(), a.getX(), b.getY(), b.getX());
+            return SloppyMath.haversinMeters(a.y(), a.x(), b.y(), b.x());
+        }
+    }
+
+    /**
+     * Calculate the triangle area using geographic coordinates and Herons formula (side lengths)
+     * as described at https://en.wikipedia.org/wiki/Area_of_a_triangle, but scale the area down
+     * by the inverse of the length of the base (left-right), which estimates the height of the triangle.
+     */
+    class TriangleHeightCalculator implements SimplificationErrorCalculator {
+
+        @Override
+        public double calculateError(PointLike left, PointLike middle, PointLike right) {
+            // Calculate side lengths using approximate haversine
+            double a = distance(left, right);
+            double b = distance(right, middle);
+            double c = distance(middle, left);
+            // semi-perimeter
+            double s = 0.5 * (a + b + c);  // Semi-perimeter
+            double da = s - a;
+            double db = s - b;
+            double dc = s - c;
+            if (da >= 0 && db >= 0 && dc >= 0) {
+                // Herons formula, scaled by 1/a
+                return 2.0 * Math.sqrt(s * da * db * dc) / a;
+            } else {
+                // rounding errors can cause flat triangles to have negative values, leading to NaN areas
+                return 0.0;
+            }
+        }
+
+        private double distance(PointLike a, PointLike b) {
+            return SloppyMath.haversinMeters(a.y(), a.x(), b.y(), b.x());
         }
     }
 
@@ -79,15 +112,15 @@ class FrechetErrorCalculator implements SimplificationErrorCalculator {
         @Override
         public double calculateError(PointLike left, PointLike middle, PointLike right) {
             // Offset coordinates so left is at the origin
-            double rightX = right.getX() - left.getX();
-            double rightY = right.getY() - left.getY();
+            double rightX = right.x() - left.x();
+            double rightY = right.y() - left.y();
             if (Math.abs(rightX) > 1e-10 || Math.abs(rightY) > 1e-10) {
                 // Rotate coordinates so that left->right is horizontal
                 double len = Math.sqrt(rightX * rightX + rightY * rightY);
                 double cos = rightX / len;
                 double sin = rightY / len;
-                double middleX = middle.getX() - left.getX();
-                double middleY = middle.getY() - left.getY();
+                double middleX = middle.x() - left.x();
+                double middleY = middle.y() - left.y();
                 double middleXrotated = middleX * cos + middleY * sin;
                 double middleYrotated = middleY * cos - middleX * sin;
                 double rightXrotated = rightX * cos + rightY * sin;

libs/geo/src/test/java/org/elasticsearch/geometry/simplify/GeometrySimplifierCartesianTriangleAreaTests.java

@@ -8,11 +8,19 @@
 
 package org.elasticsearch.geometry.simplify;
 
+import org.elasticsearch.geometry.Line;
+
 public class GeometrySimplifierCartesianTriangleAreaTests extends GeometrySimplifierTests {
     private SimplificationErrorCalculator calculator = new SimplificationErrorCalculator.CartesianTriangleAreaCalculator();
 
     @Override
     protected SimplificationErrorCalculator calculator() {
         return calculator;
     }
+
+    protected void assertLineWithNarrowSpikes(Line simplified, int spikeCount) {
+        // The cartesian triangle area destroys most spikes, saving only two
+        assertLineSpikes("Cartesian", simplified, 2);
+    }
+
 }

libs/geo/src/test/java/org/elasticsearch/geometry/simplify/GeometrySimplifierFrechetTests.java

@@ -8,11 +8,18 @@
 
 package org.elasticsearch.geometry.simplify;
 
+import org.elasticsearch.geometry.Line;
+
 public class GeometrySimplifierFrechetTests extends GeometrySimplifierTests {
     private SimplificationErrorCalculator calculator = new SimplificationErrorCalculator.FrechetErrorCalculator();
 
     @Override
     protected SimplificationErrorCalculator calculator() {
         return calculator;
     }
+
+    protected void assertLineWithNarrowSpikes(Line simplified, int spikeCount) {
+        // The frechet distance can save all spikes
+        assertLineSpikes("Frechet", simplified, spikeCount);
+    }
 }