Project import generated by Copybara.

PiperOrigin-RevId: 538225776

Author: S2 Authors

benchmarks/src/com/google/common/geometry/BestEdgesBenchmarkHarness.java

@@ -74,7 +74,7 @@ public enum FactoryType {
   }
 
   /**
-   * A container for an index, an closest or furthest edge query on that index, and a set of targets
+   * A container for an index, a closest or furthest edge query on that index, and a set of targets
    * to test with.
    */
   public abstract static class BestEdgeQueryWithTargets {

benchmarks/src/com/google/common/geometry/S2EdgeUtilBenchmark.java

@@ -15,15 +15,16 @@
  */
 package com.google.common.geometry.benchmarks;
 
+import static java.lang.Math.PI;
 import static java.util.concurrent.TimeUnit.NANOSECONDS;
 import static java.util.concurrent.TimeUnit.SECONDS;
 
+import com.google.common.geometry.S1Angle;
+import com.google.common.geometry.S1ChordAngle;
 import com.google.common.geometry.S2EdgeUtil;
 import com.google.common.geometry.S2Point;
 import com.google.errorprone.annotations.CheckReturnValue;
 import java.io.IOException;
-import java.util.ArrayList;
-import java.util.List;
 import org.openjdk.jmh.annotations.Benchmark;
 import org.openjdk.jmh.annotations.BenchmarkMode;
 import org.openjdk.jmh.annotations.Level;
@@ -41,33 +42,55 @@
 public class S2EdgeUtilBenchmark {
   private S2EdgeUtilBenchmark() {}
 
-  /** Benchmarks the crossing functions on a list of randomly generated points. */
+  /** Benchmarks the interpolation and crossing functions on a list of randomly generated points. */
   @State(Scope.Thread)
   @BenchmarkMode(Mode.AverageTime)
   @OutputTimeUnit(NANOSECONDS)
-  @Warmup(iterations = 3, time = 15, timeUnit = SECONDS)
-  @Measurement(iterations = 5, time = 15, timeUnit = SECONDS)
+  @Warmup(iterations = 3, time = 10, timeUnit = SECONDS)
+  @Measurement(iterations = 10, time = 10, timeUnit = SECONDS)
   public static class BenchmarkCrossingState extends S2BenchmarkBaseState {
-    protected static final int NUM_POINTS = 400;
+    // We want to avoid cache effects, so these arrays should be small enough to fit in L1 cache.
+    // An S2Point is at most 40 bytes, so 250 will take about ~10 KiB.
+    protected static final int NUM_POINTS = 250;
+    protected static final int NUM_ANGLES = 120;
+
+    // Randomly selected values between 0 and 1.
+    protected double[] fractions = new double[NUM_ANGLES];
+    // Randomly selected angles between 0 and PI/4.
+    protected S1Angle[] angles = new S1Angle[NUM_ANGLES];
+    protected S1ChordAngle[] chordAngles = new S1ChordAngle[NUM_ANGLES];
+
+    // Randomly selected points.
+    protected S2Point[] points = new S2Point[NUM_POINTS];
+    // Precomputed S1Angle distances between successive points.
+    protected S1Angle[] precomputedS1Angle = new S1Angle[NUM_POINTS];
 
-    protected List<S2Point> points;
     protected int pointIndex;
+    protected int distanceIndex;
     protected S2Point a;
     protected S2Point b;
 
     @Setup(Level.Trial)
     @Override
     public void setup() throws IOException {
       super.setup();
-      // We want to avoid cache effects, so numPoints should be small enough so that the points can
-      // be in L1 cache.  The size of an S2Point is at most 40 bytes, so 400 will only take at most
-      // ~16 KiB of 64 KiB of L1 cache.
-      points = new ArrayList<>(NUM_POINTS);
       for (int i = 0; i < NUM_POINTS; ++i) {
-        points.add(data.getRandomPoint());
+        points[i] = data.getRandomPoint();
+      }
+      for (int i = 0; i < NUM_POINTS; ++i) {
+        S2Point a = points[i];
+        S2Point b = points[(i + 1) % NUM_POINTS];
+        precomputedS1Angle[i] = new S1Angle(a, b);
       }
       pointIndex = 0;
 
+      for (int i = 0; i < NUM_ANGLES; ++i) {
+        fractions[i] = data.uniform(0, 1);
+        angles[i] = S1Angle.radians(data.uniform(0, PI / 4));
+        chordAngles[i] = S1ChordAngle.fromS1Angle(angles[i]);
+      }
+      distanceIndex = 0;
+
       // Approximately 1/4th of points will cross the edge 'ab'.
       a = data.getRandomPoint();
       b = S2Point.neg(a).add(new S2Point(0.1, 0.1, 0.1)).normalize();
@@ -80,17 +103,17 @@ public void setup() throws IOException {
      *
      * <p>For example, one test run found the following:
      * <ul>
-     * <li> 37.787 +/- 0.499 ns/op for benchmarkOverhead.
+     * <li> 37.787 +/- 0.499 ns/op for benchmarkFourPointOverhead.
      * <li>117.601 +/- 15.786 ns/op for edgeOrVertexCrossing, so true cost is 79 +/- 16 ns.
      * <li>113.949 +/- 1.507 ns/op for robustCrossing, so true cost is 76 +/- 2 ns.
      * </ul>
      */
     @Benchmark
-    public int benchmarkOverhead(Blackhole bh) {
-      S2Point a = points.get((pointIndex + 0) % NUM_POINTS);
-      S2Point b = points.get((pointIndex + 1) % NUM_POINTS);
-      S2Point c = points.get((pointIndex + 2) % NUM_POINTS);
-      S2Point d = points.get((pointIndex + 3) % NUM_POINTS);
+    public int benchmarkFourPointOverhead(Blackhole bh) {
+      S2Point a = points[(pointIndex + 0) % NUM_POINTS];
+      S2Point b = points[(pointIndex + 1) % NUM_POINTS];
+      S2Point c = points[(pointIndex + 2) % NUM_POINTS];
+      S2Point d = points[(pointIndex + 3) % NUM_POINTS];
       pointIndex = (pointIndex + 1) % NUM_POINTS;
       bh.consume(a);
       bh.consume(b);
@@ -102,21 +125,21 @@ public int benchmarkOverhead(Blackhole bh) {
     /** Benchmarks a single call to edgeOrVertexCrossing() with random points. */
     @Benchmark
     public boolean edgeOrVertexCrossing() {
-      S2Point a = points.get((pointIndex + 0) % NUM_POINTS);
-      S2Point b = points.get((pointIndex + 1) % NUM_POINTS);
-      S2Point c = points.get((pointIndex + 2) % NUM_POINTS);
-      S2Point d = points.get((pointIndex + 3) % NUM_POINTS);
+      S2Point a = points[(pointIndex + 0) % NUM_POINTS];
+      S2Point b = points[(pointIndex + 1) % NUM_POINTS];
+      S2Point c = points[(pointIndex + 2) % NUM_POINTS];
+      S2Point d = points[(pointIndex + 3) % NUM_POINTS];
       pointIndex = (pointIndex + 1) % NUM_POINTS;
       return S2EdgeUtil.edgeOrVertexCrossing(a, b, c, d);
     }
 
     /** Benchmarks a single call to robustCrossing() with random points. */
     @Benchmark
     public int robustCrossing() {
-      S2Point a = points.get((pointIndex + 0) % NUM_POINTS);
-      S2Point b = points.get((pointIndex + 1) % NUM_POINTS);
-      S2Point c = points.get((pointIndex + 2) % NUM_POINTS);
-      S2Point d = points.get((pointIndex + 3) % NUM_POINTS);
+      S2Point a = points[(pointIndex + 0) % NUM_POINTS];
+      S2Point b = points[(pointIndex + 1) % NUM_POINTS];
+      S2Point c = points[(pointIndex + 2) % NUM_POINTS];
+      S2Point d = points[(pointIndex + 3) % NUM_POINTS];
       pointIndex = (pointIndex + 1) % NUM_POINTS;
       return S2EdgeUtil.robustCrossing(a, b, c, d);
     }
@@ -128,11 +151,94 @@ public int robustCrossing() {
      */
     @Benchmark
     public void edgeCrosser100RobustCrossings(Blackhole bh) {
-      S2EdgeUtil.EdgeCrosser crosser = new S2EdgeUtil.EdgeCrosser(a, b, points.get(0));
+      S2EdgeUtil.EdgeCrosser crosser = new S2EdgeUtil.EdgeCrosser(a, b, points[0]);
       for (int r = 100; r > 0; --r) {
-        S2Point d = points.get(r % NUM_POINTS);
+        S2Point d = points[r % NUM_POINTS];
         bh.consume(crosser.robustCrossing(d));
       }
     }
+
+    /**
+     * Measures overhead due to iterating through and obtaining two S2Points with this benchmark
+     * State. Subtract the time measured by this benchmark from the interpolation benchmarks below
+     * to get a more accurate measure of their real cost.
+     */
+    @Benchmark
+    public int benchmarkTwoPointOverhead(Blackhole bh) {
+      S2Point a = points[(pointIndex + 0) % NUM_POINTS];
+      S2Point b = points[(pointIndex + 1) % NUM_POINTS];
+      pointIndex = (pointIndex + 1) % NUM_POINTS;
+      bh.consume(a);
+      bh.consume(b);
+      return pointIndex;
+    }
+
+    /** Benchmarks a single call to interpolate() with random points and distances. */
+    @Benchmark
+    public S2Point interpolate() {
+      S2Point a = points[(pointIndex + 0) % NUM_POINTS];
+      S2Point b = points[(pointIndex + 1) % NUM_POINTS];
+      double t = fractions[distanceIndex % NUM_ANGLES];
+      pointIndex = (pointIndex + 1) % NUM_POINTS;
+      distanceIndex = (distanceIndex + 1) % NUM_ANGLES;
+      return S2EdgeUtil.interpolate(t, a, b);
+    }
+
+    /**
+     * Benchmarks {@link S2EdgeUtil#getPointOnLine(S2Point, S2Point, S1Angle)} with random
+     * points and distances.
+     */
+    @Benchmark
+    public S2Point getPointOnLineS1Angle() {
+      S2Point a = points[(pointIndex + 0) % NUM_POINTS];
+      S2Point b = points[(pointIndex + 1) % NUM_POINTS];
+      S1Angle angle = angles[distanceIndex % NUM_ANGLES];
+      pointIndex = (pointIndex + 1) % NUM_POINTS;
+      distanceIndex = (distanceIndex + 1) % NUM_ANGLES;
+      return S2EdgeUtil.getPointOnLine(a, b, angle);
+    }
+
+    /**
+     * Benchmarks {@link S2EdgeUtil#getPointOnLine(S2Point, S2Point, S1Angle)} with random
+     * points and distances.
+     */
+    @Benchmark
+    public S2Point getPointOnLineS1ChordAngle() {
+      S2Point a = points[(pointIndex + 0) % NUM_POINTS];
+      S2Point b = points[(pointIndex + 1) % NUM_POINTS];
+      S1ChordAngle chordAngle = chordAngles[distanceIndex % NUM_ANGLES];
+      pointIndex = (pointIndex + 1) % NUM_POINTS;
+      distanceIndex = (distanceIndex + 1) % NUM_ANGLES;
+      return S2EdgeUtil.getPointOnLine(a, b, chordAngle);
+    }
+
+    /**
+     * Benchmarks {@link S2EdgeUtil#interpolateAtDistance(S1Angle, S2Point, S2Point)} with random
+     * points and distances.
+     */
+    @Benchmark
+    public S2Point interpolateAtDistance() {
+      S2Point a = points[(pointIndex + 0) % NUM_POINTS];
+      S2Point b = points[(pointIndex + 1) % NUM_POINTS];
+      S1Angle angle = angles[distanceIndex % NUM_ANGLES];
+      pointIndex = (pointIndex + 1) % NUM_POINTS;
+      distanceIndex = (distanceIndex + 1) % NUM_ANGLES;
+      return S2EdgeUtil.interpolateAtDistance(angle, a, b);
+    }
+
+    /**
+     * Benchmarks {@link S2EdgeUtil#interpolateAtDistance(S1Angle, S2Point, S2Point, S1Angle)} with
+     * precomputed S1Angle distance AB for random points and distances.
+     */
+    @Benchmark
+    public S2Point interpolateAtDistanceWithPrecomputedS1AngleAB() {
+      S2Point a = points[(pointIndex + 0) % NUM_POINTS];
+      S2Point b = points[(pointIndex + 1) % NUM_POINTS];
+      S1Angle ab = precomputedS1Angle[pointIndex % NUM_POINTS];
+      S1Angle angle = angles[distanceIndex % NUM_ANGLES];
+      pointIndex = (pointIndex + 1) % NUM_POINTS;
+      distanceIndex = (distanceIndex + 1) % NUM_ANGLES;
+      return S2EdgeUtil.interpolateAtDistance(angle, a, b, ab);
+    }
   }
 }

benchmarks/src/com/google/common/geometry/S2LatLngRectBenchmark.java

@@ -87,7 +87,7 @@ public S2LatLngRect addS2LatLngsX8() {
     /**
      * Measures the time to create an empty S2LatLngRect.Builder, add 8 S2LatLngs to it, first
      * converting each to an S2Point, and then build and return the resulting S2LatLngRect.
-     * Note that converting S2Latlngs to S2Points before adding them to the builder is an bad idea.
+     * Note that converting S2Latlngs to S2Points before adding them to the builder is a bad idea.
      * The addPoint(S2Point) call immediately converts them back to S2LatLngs, and these two
      * conversions make it about 8 times slower than adding S2LatLngs directly.
      */

library/pom.xml

@@ -31,6 +31,11 @@
   <packaging>jar</packaging>
 
   <dependencies>
+    <dependency>
+      <groupId>com.google.errorprone</groupId>
+      <artifactId>error_prone_annotations</artifactId>
+      <version>${errorprone.version}</version>
+    </dependency>
     <dependency>
       <groupId>com.google.guava</groupId>
       <artifactId>guava</artifactId>

library/src/com/google/common/geometry/BigPoint.java

@@ -36,6 +36,11 @@ final strictfp class BigPoint implements Comparable<BigPoint> {
     this.z = z;
   }
 
+  /** Returns the negative of this point. */
+  public BigPoint neg() {
+    return new BigPoint(x.negate(), y.negate(), z.negate());
+  }
+
   /** Returns an S2Point by rounding 'this' to double precision. */
   S2Point toS2Point() {
     return new S2Point(x.doubleValue(), y.doubleValue(), z.doubleValue());

library/src/com/google/common/geometry/LittleEndianInput.java

@@ -39,10 +39,13 @@ public byte readByte() throws IOException {
   /**
    * Reads a fixed size of bytes from the input.
    *
-   * @param size the number of bytes to read.
+   * @param size the number of bytes to read. May be zero.
    * @throws IOException if past end of input or error in underlying stream
    */
   public byte[] readBytes(final int size) throws IOException {
+    if (size < 0) {
+      throw new IOException("Attempt to read " + size + " bytes");
+    }
     byte[] result = new byte[size];
     int numRead = input.read(result);
     if (numRead < size) {

library/src/com/google/common/geometry/Platform.java

@@ -28,12 +28,16 @@ final class Platform {
 
   private Platform() {}
 
-  /** @see Math#IEEEremainder(double, double) */
+  /**
+   * @see Math#IEEEremainder(double, double)
+   */
   static double IEEEremainder(double f1, double f2) {
     return Math.IEEEremainder(f1, f2);
   }
 
-  /** @see Math#getExponent(double) */
+  /**
+   * @see Math#getExponent(double)
+   */
   static int getExponent(double d) {
     return Math.getExponent(d);
   }
@@ -116,19 +120,25 @@ public static long doubleHash(double value) {
    * techniques have been exhausted.
    */
   public static int sign(S2Point a, S2Point b, S2Point c) {
-    Real bycz = Real.mul(b.y, c.z);
-    Real bzcy = Real.mul(b.z, c.y);
-    Real bzcx = Real.mul(b.z, c.x);
-    Real bxcz = Real.mul(b.x, c.z);
-    Real bxcy = Real.mul(b.x, c.y);
-    Real bycx = Real.mul(b.y, c.x);
-    Real bcx = bycz.sub(bzcy);
-    Real bcy = bzcx.sub(bxcz);
-    Real bcz = bxcy.sub(bycx);
-    Real x = bcx.mul(a.x);
-    Real y = bcy.mul(a.y);
-    Real z = bcz.mul(a.z);
-    return x.add(y).add(z).signum();
+    try {
+      Real bycz = Real.strictMul(b.y, c.z);
+      Real bzcy = Real.strictMul(b.z, c.y);
+      Real bzcx = Real.strictMul(b.z, c.x);
+
+      Real bxcz = Real.strictMul(b.x, c.z);
+      Real bxcy = Real.strictMul(b.x, c.y);
+      Real bycx = Real.strictMul(b.y, c.x);
+
+      Real bcx = bycz.sub(bzcy);
+      Real bcy = bzcx.sub(bxcz);
+      Real bcz = bxcy.sub(bycx);
+      Real x = bcx.strictMul(a.x);
+      Real y = bcy.strictMul(a.y);
+      Real z = bcz.strictMul(a.z);
+      return x.add(y).add(z).signum();
+    } catch (ArithmeticException unused) {
+      return 0;
+    }
   }
 
   /**

library/src/com/google/common/geometry/PrimitiveArrays.java

@@ -291,8 +291,8 @@ public int length() {
     /**
      * Decodes and returns this array as an {@code int[]}.
      *
-     * <p>Throws an {@link IllegalArgumentException} if any value in this array is < {@link
-     * Integer#MIN_VALUE} or > {@link Integer#MAX_VALUE}.
+     * <p>Throws an {@link IllegalArgumentException} if any value in this array is less than {@link
+     * Integer#MIN_VALUE} or greater than {@link Integer#MAX_VALUE}.
      */
     default int[] toIntArray() {
       int[] result = new int[length()];
@@ -320,5 +320,12 @@ public static class Cursor {
     public long remaining() {
       return limit - position;
     }
+
+    /** Sets the cursor position to 'position' and returns this cursor. */
+    public Cursor seek(long position) {
+      Preconditions.checkArgument(position >= 0 && position < limit);
+      this.position = position;
+      return this;
+    }
   }
 }

library/src/com/google/common/geometry/Projection.java

@@ -55,7 +55,8 @@ default S2Point unproject(R2Vector p) {
   /**
    * Returns the point obtained by interpolating the given fraction of the distance along the line
    * from A to B. Almost all projections should use the default implementation of this method, which
-   * simply interpolates linearly in R2 space. Fractions < 0 or > 1 result in extrapolation instead.
+   * simply interpolates linearly in R2 space. Fractions less than 0 or greater than 1 result in
+   * extrapolation instead.
    *
    * <p>The only reason to override this method is if you want edges to be defined as something
    * other than straight lines in the 2D projected coordinate system. For example, using a