Project import generated by Copybara.

PiperOrigin-RevId: 755519727

Author: S2 Authors

README.md

@@ -57,6 +57,50 @@ varying degrees of completeness and maturity. This Java implementation is
 heavily used within Google and is generally mature, aside from the newest
 features, but is not as complete as C++.
 
+## 2025 Q2 Release Highlights
+
+Over 100 additional classes have been ported from C++, as well as more methods
+on existing classes. There have been performance improvements and bug fixes, as
+well as many Javadoc improvements. Some changes are not backward compatible.
+
+A few highlights:
+
+*   S2Builder, S2BooleanOperation, and supporting classes have been ported from
+    C++.
+
+*   S2RobustCellClipper and its supporting classes have been ported from C++.
+
+*   S2ValidationQueries has been ported from C++, with internal classes
+    S2ValidQuery (for validating that geometry is compatible with
+    S2BooleanOperation) and S2LegacyValidQuery (for validating that geometry is
+    compatible with the S2Polygon and S2Polyline isValid() methods).
+
+*   S2 now depends on Fastutil (https://fastutil.di.unimi.it/) and Guava's
+    Truth library (https://truth.dev/).
+
+*   S2 used to support three possible projections from cell space to cube space:
+    linear, tangent, and quadratic. In practice, only quadratic was used, and it
+    is now the only supported option. See S2Projections.java for more details.
+
+*   Many Java assertions that were formerly commented out are now present. These
+    typically match DCHECKs in the C++ implementation. Work is ongoing to enable
+    more of these.
+
+*   A global boolean "S2.skipAssertions" is provided to allow deliberate
+    construction of invalid S2 Objects when Java assertions are enabled, for
+    testing. Use via GeometryTestCase.unsafeCreate() and related methods.
+
+*   The "robustCrossProd" implementation is now truly robust.
+
+*   An internal "primitives" subpackage provides some low-level collections and
+    other utility classes. These are not intended to be used by clients. They
+    may be removed in future releases.
+
+*   S2Polyline no longer implements S2Shape directly, but provides a shape()
+    method. Also, single-vertex S2Polylines are now considered to represent
+    degenerate lines, which are not empty. When viewed as a S2Shape, they have
+    one edge with two identical vertices.
+
 ## 2022 Q4 Release Highlights
 
 Many improvements have been made to the Java implementation of S2 since the last

benchmarks/pom.xml

@@ -43,12 +43,6 @@
       <version>${project.parent.version}</version>
     </dependency>
 
-    <dependency>
-      <groupId>com.google.geometry</groupId>
-      <artifactId>s2-geometry-testdatagenerator</artifactId>
-      <version>${project.parent.version}</version>
-    </dependency>
-
     <dependency>
       <groupId>org.openjdk.jmh</groupId>
       <artifactId>jmh-core</artifactId>

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

@@ -15,17 +15,14 @@
  */
 package com.google.common.geometry.benchmarks;
 
-import static com.google.common.geometry.S2Projections.PROJ;
+import static com.google.common.geometry.S2Projections.MAX_DIAG;
 import static com.google.common.geometry.TestDataGenerator.kmToAngle;
 import static java.util.concurrent.TimeUnit.MICROSECONDS;
 import static java.util.concurrent.TimeUnit.SECONDS;
 
 import com.google.common.geometry.PrimitiveArrays.Bytes;
 import com.google.common.geometry.PrimitiveArrays.Cursor;
 import com.google.common.geometry.S1Angle;
-import com.google.common.geometry.S1ChordAngle;
-import com.google.common.geometry.S2BestDistanceTarget;
-import com.google.common.geometry.S2BestEdgesQueryBase;
 import com.google.common.geometry.S2Cap;
 import com.google.common.geometry.S2Cell;
 import com.google.common.geometry.S2CellId;
@@ -84,12 +81,6 @@ public abstract static class BestEdgeQueryWithTargets {
     // The number of edges in 'index'. Stored here to avoid repeated counting.
     public int numIndexEdges;
 
-    // The query built on the index.
-    public abstract S2BestEdgesQueryBase<S1ChordAngle> query();
-
-    // Targets to query against the index.
-    public abstract ArrayList<? extends S2BestDistanceTarget<S1ChordAngle>> targets();
-
     // If the index is encoded, this is the list of shapes in it, which are encoded separately.
     public List<S2Shape> shapes;
   }
@@ -379,7 +370,7 @@ protected S2Cell getTargetCell(BestEdgeQueryWithTargets output, S2Cap targetCap)
           chooseTargetFromIndex
               ? data.sampleCell(output.index)
               : S2CellId.fromPoint(targetCap.axis())
-                  .parent(PROJ.maxDiag.getClosestLevel(targetCap.radius().radians()));
+                  .parent(MAX_DIAG.getClosestLevel(targetCap.radius().radians()));
       return new S2Cell(cellId);
     }
 
@@ -410,7 +401,7 @@ protected S2ShapeIndex getTargetIndex(BestEdgeQueryWithTargets output, S2Cap tar
         targetIndex = factory.getShape(targetCap, numTargetEdges);
       }
 
-      targetIndex.iterator(); // Force an index build.
+      targetIndex.applyUpdates();
       return targetIndex;
     }
 

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

@@ -0,0 +1,76 @@
+/*
+ * Copyright 2024 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.google.common.geometry.benchmarks;
+
+import static java.util.concurrent.TimeUnit.NANOSECONDS;
+import static java.util.concurrent.TimeUnit.SECONDS;
+
+import com.google.common.geometry.primitives.DisjointSet;
+import org.openjdk.jmh.annotations.Benchmark;
+import org.openjdk.jmh.annotations.BenchmarkMode;
+import org.openjdk.jmh.annotations.Level;
+import org.openjdk.jmh.annotations.Measurement;
+import org.openjdk.jmh.annotations.Mode;
+import org.openjdk.jmh.annotations.OutputTimeUnit;
+import org.openjdk.jmh.annotations.Param;
+import org.openjdk.jmh.annotations.Scope;
+import org.openjdk.jmh.annotations.Setup;
+import org.openjdk.jmh.annotations.State;
+import org.openjdk.jmh.annotations.Warmup;
+
+/**
+ * Benchmark for {@link DisjointSet}.
+ */
+public final class DisjointSetBenchmark {
+
+  private DisjointSetBenchmark() { }
+
+  /** Benchmark state that sets up a disjoint set with consecutive Integer values. */
+  @State(Scope.Thread)
+  @BenchmarkMode(Mode.AverageTime)
+  @OutputTimeUnit(NANOSECONDS)
+  @Warmup(iterations = 3, time = 5, timeUnit = SECONDS)
+  @Measurement(iterations = 5, time = 5, timeUnit = SECONDS)
+  public static class ConsecutiveIntegerState extends S2BenchmarkBaseState {
+    @Param({"64", "512", "4096", "32768", "262144"})
+    int numElements;
+
+    private final DisjointSet<Integer> set = new DisjointSet<>(numElements);
+
+    @Setup(Level.Trial)
+    @Override
+    public void setup() {
+      super.setup();
+    }
+
+    /**
+     * Measures the amount of time it takes to add numElements, union consecutive sets together, and
+     * then find the root of the first element. Equivalent to BM_FindRoot in the C++ implementation.
+     */
+    @Benchmark
+    public int findRoot() {
+      set.clear();
+      for (int i = 0; i < numElements; i++) {
+        set.add(i);
+      }
+      for (int i = 0; i < numElements; i++) {
+        set.union(i, i + 1);
+      }
+
+      return set.findRoot(1);
+    }
+  }
+}

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

@@ -23,7 +23,6 @@
 import com.google.common.geometry.S2Cap;
 import com.google.common.geometry.S2Point;
 import com.google.common.geometry.TestDataGenerator;
-import java.io.IOException;
 import org.openjdk.jmh.annotations.Benchmark;
 import org.openjdk.jmh.annotations.BenchmarkMode;
 import org.openjdk.jmh.annotations.Level;
@@ -65,7 +64,7 @@ public static class AngleState extends S2BenchmarkBaseState {
 
     @Setup(Level.Trial)
     @Override
-    public void setup() throws IOException {
+    public void setup() {
       super.setup();
       a = data.getRandomPoint();
       S2Cap sampleCapNearParallel = S2Cap.fromAxisAngle(a, capSize);

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

@@ -45,7 +45,7 @@ public class S2BenchmarkBaseState {
    * Reinitializes the TestDataGenerator, which reinitializes the contained Random to a known state.
    * This is equivalent to calling data.resetSeed().
    */
-  public void setup() throws IOException {
+  public void setup() {
     data = new TestDataGenerator();
   }
 
@@ -81,7 +81,6 @@ public abstract static class ContainsPointBaseState extends S2BenchmarkBaseState
     protected static final int NUM_QUERY_SAMPLES = 10;
     protected static final int NUM_POLYGONS = 5;
 
-    protected boolean preindexOption;
     protected List<S2Polygon> polygons = new ArrayList<>(NUM_POLYGONS);
     protected List<List<S2Point>> queries = new ArrayList<>(NUM_POLYGONS);
     protected int polygonIndex;
@@ -97,8 +96,6 @@ protected void setupPolygonsAndQueries(
         int totalNumVertices,
         boolean preindexOption)
         throws IOException {
-      // Saved so subclasses can use it to index their polygons.
-      this.preindexOption = preindexOption;
       polygons.clear();
       queries.clear();
 
@@ -149,7 +146,6 @@ protected S2Point currentQuery() {
    */
   public abstract static class PolygonListState extends S2BenchmarkBaseState {
     protected static final int NUM_POLYGONS = 10;
-    protected boolean preindexOption;
     protected ArrayList<S2Polygon> polygons = new ArrayList<>(NUM_POLYGONS);
     protected ArrayList<S2Polygon> copies = new ArrayList<>(NUM_POLYGONS);
     protected ArrayList<S2Polygon> bounds = new ArrayList<>(NUM_POLYGONS);
@@ -163,7 +159,6 @@ protected void setupPolygons(
         boolean preindexOption)
         throws IOException {
       super.setup();
-      this.preindexOption = preindexOption;
 
       polygons.clear();
       copies.clear();