Merge branch 'master' into feature/cell-index

Author: jmr

.github/workflows/go.yml

@@ -0,0 +1,28 @@
+# This workflow will checkout, build, and run the tests for the Go S2 project.
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-go
+
+name: Go Build and Test
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Go
+      uses: actions/setup-go@v5
+      with:
+        go-version-file: 'go.mod'
+
+    - name: Build
+      run: go build -v ./...
+
+    - name: Test
+      run: go test -v ./...

README.md

@@ -4,7 +4,7 @@ S2 is a library for spherical geometry that aims to have the same robustness,
 flexibility, and performance as the best planar geometry libraries.
 
 This is a library for manipulating geometric shapes. Unlike many geometry
-libraries, S2 is primarily designed to work with _spherical geometry_, i.e.,
+libraries, S2 is primarily designed to work with *spherical geometry*, i.e.,
 shapes drawn on a sphere rather than on a planar 2D map. (In fact, the name S2
 is derived from the mathematical notation for the unit sphere *S²*.) This makes
 it especially suitable for working with geographic data.
@@ -92,109 +92,150 @@ This library is principally a port of the
 where it makes sense. We detail the progress of this port below relative to that
 C++ library.
 
+Legend:
+
+*   ✅ - Feature Complete
+*   🟡 - Mostly Complete
+*   ❌ - Not available
+
 ## [ℝ¹](https://godoc.org/github.com/golang/geo/r1) - One-dimensional Cartesian coordinates
 
-Full parity with C++.
+C++ Type   | Go
+:--------- | ---
+R1Interval | ✅
 
 ## [ℝ²](https://godoc.org/github.com/golang/geo/r2) - Two-dimensional Cartesian coordinates
 
-Full parity with C++.
+C++ Type | Go
+:------- | ---
+R2Point  | ✅
+R2Rect   | ✅
 
 ## [ℝ³](https://godoc.org/github.com/golang/geo/r3) - Three-dimensional Cartesian coordinates
 
-Full parity with C++.
+C++ Type      | Go
+:------------ | ---
+R3Vector      | ✅
+R3ExactVector | ✅
+Matrix3x3     | ✅
 
 ## [S¹](https://godoc.org/github.com/golang/geo/s1) - Circular Geometry
 
-Full parity with C++.
+C++ Type     | Go
+:----------- | ---
+S1Angle      | ✅
+S1ChordAngle | ✅
+S1Interval   | ✅
 
 ## [S²](https://godoc.org/github.com/golang/geo/s2) - Spherical Geometry
 
-Approximately ~40% complete.
-
-**Complete** These files have full parity with the C++ implementation.
-
-*   Cap
-*   Cell
-*   CellID
-*   CellUnion
-*   ContainsVertexQuery
-*   ConvexHullQuery
-*   CrossingEdgeQuery
-*   LatLng
-*   matrix3x3
-*   Metric
-*   PaddedCell
-*   Point
-*   PointCompression
-*   Region
-*   RegionCoverer
-*   RegionUnion
-*   s2edge_clipping
-*   s2edge_crosser
-*   s2edge_crossings
-*   s2edge_distances
-*   edgeVectorShape
-*   laxLoop
-*   laxPolyline
-*   s2projections - Helpers for projecting points between R2 and S2.
-*   s2rect_bounder
-*   s2stuv.go (s2coords.h in C++) - This file is a collection of helper and
-    conversion methods to and from ST-space, UV-space, and XYZ-space.
-*   s2wedge_relations
-*   ShapeIndex
-*   idSetLexicon,sequenceLexicon
-
-**Mostly Complete** Files that have almost all of the features of the original
-C++ code, and are reasonably complete enough to use in live code. Up to date
-listing of the incomplete methods are documented at the end of each file.
-
-*   EdgeQuery/Closest/Furthest - missing Project, GetEdge
-*   ContainsPointQuery - missing visit edges
-*   laxPolygon
-*   Loop - Loop is mostly complete now. Missing Project, Distance, Union, etc.
-*   Polyline - Missing InitTo... methods, NearlyCoversPolyline
-*   Rect (AKA s2latlngrect in C++) - Missing Centroid, InteriorContains.
-*   s2_test.go (AKA s2testing and s2textformat in C++) - Missing Fractal test
-    shape generation. This file is a collection of testing helper methods.
-*   s2edge_distances - Missing Intersection
-
-**In Progress** Files that have some work done, but are probably not complete
-enough for general use in production code.
-
-*   CellIndex - A queryable index of CellIDs.
-*   Polygon - Polygons with multiple loops are supported. It fully implements
-    Shape and Region, but it's missing most other methods. (Area, Centroid,
-    Distance, Projection, Intersection, Union, Contains, Normalized, etc.)
-*   PolylineSimplifier - Initial work has begun on this.
-*   s2predicates.go - This file is a collection of helper methods used by other
-    parts of the library.
-*   s2shapeutil - Initial elements added. Missing VisitCrossings.
-
-**Not Started Yet.** These files (and their associated unit tests) have
-dependencies on most of the In Progress files before they can begin to be
-started.
-
-*   BooleanOperation - used when assembling polygons and loops.
-*   Builder - This is a robust tool for creating the various Shape types from
-    collection of simpler S2 types.
-*   BuilderClosedSetNormalizer
-*   BuilderFindPolygonDegneracies
-*   BuilderGraph
-*   BuilderLayers
-*   BuilderSnapFunctions
-*   BuilderTesting
-*   Centroids
-*   ClosestPointQuery
-*   EdgeTesselator
-*   LoopMeasures
-*   PointIndex
-*   PointRegion
-*   PointUtil
-*   PolygonMeasures
-*   RegionIntersection
-*   RegionTermIndexer
-*   ShapeIndexRegion - Allows ShapeIndexes to be used as Regions for things like
+### Basic Types
+
+C++ Type             | Go
+:------------------- | ---
+S2Cap                | ✅
+S2Cell               | ✅
+S2CellId             | ✅
+S2CellIdVector       | ❌
+S2CellIndex          | 🟡
+S2CellUnion          | ✅
+S2Coords             | ✅
+S2DensityTree        | ❌
+S2DistanceTarget     | ✅
+S2EdgeVector         | ✅
+S2LatLng             | ✅
+S2LatLngRect         | ✅
+S2LaxLoop            | 🟡
+S2LaxPolygon         | 🟡
+S2LaxPolyline        | 🟡
+S2Loop               | ✅
+S2PaddedCell         | ✅
+S2Point              | ✅
+S2PointIndex         | ❌
+S2PointSpan          | ❌
+S2PointRegion        | ❌
+S2PointVector        | ✅
+S2Polygon            | 🟡
+S2Polyline           | ✅
+S2R2Rect             | ❌
+S2Region             | ✅
+S2RegionCoverer      | ✅
+S2RegionIntersection | ❌
+S2RegionUnion        | ✅
+S2Shape              | ✅
+S2ShapeIndex         | ✅
+S2ShapeIndexRegion   | ❌
+EncodedLaxPolygon    | ❌
+EncodedLaxPolyline   | ❌
+EncodedShapeIndex    | ❌
+EncodedStringVector  | ❌
+EncodedUintVector    | ❌
+IdSetLexicon         | ❌
+ValueSetLexicon      | ❌
+SequenceLexicon      | ❌
+LaxClosedPolyline    | ❌
+VertexIDLaxLoop      | ❌
+
+### Query Types
+
+C++ Type             | Go
+:------------------- | ---
+S2ChainInterpolation | ❌
+S2ClosestCell        | ❌
+S2FurthestCell       | ❌
+S2ClosestEdge        | ✅
+S2FurthestEdge       | ✅
+S2ClosestPoint       | ❌
+S2FurthestPoint      | ❌
+S2ContainsPoint      | ✅
+S2ContainsVertex     | ✅
+S2ConvexHull         | ✅
+S2CrossingEdge       | ✅
+S2HausdorffDistance  | ❌
+S2ShapeNesting       | ❌
+
+### Supporting Types
+
+C++ Type                         | Go
+:------------------------------- | ---
+S2BooleanOperation               | ❌
+S2BufferOperation                | ❌
+S2Builder                        | ❌
+S2BuilderClosedSetNormalizer     | ❌
+S2BuilderFindPolygonDegeneracies | ❌
+S2BuilderGraph                   | ❌
+S2BuilderLayers                  | ❌
+S2BuilderSnapFunctions           | ❌
+S2BuilderTesting                 | ❌
+S2Builderutil\*                  | ❌
+S2Coder                          | ❌
+S2EdgeClipping                   | ✅
+S2EdgeCrosser                    | ✅
+S2EdgeCrossings                  | ✅
+S2EdgeDistances                  | ✅
+S2EdgeTessellator                | ✅
+S2LoopMeasures                   | ❌
+S2Measures                       | ✅
+S2MemoryTracker                  | ❌
+S2Metrics                        | ❌
+S2PointUtil                      | 🟡
+S2PolygonBuilder                 | ❌
+S2PolylineAlignment              | ❌
+S2PolylineMeasures               | ✅
+S2PolylineSimplifier             | ❌
+S2Predicates                     | ✅
+S2Projections                    | ❌
+S2rectBounder                    | ❌
+S2RegionTermIndexer              | ❌
+S2ShapeIndexMeasures             | ❌
+S2ShapeIndexUtil\*               | 🟡
+S2ShapeMeasures                  | ❌
+S2ShapeUtil\*                    | 🟡
+S2Stats                          | ❌
+S2Testing                        | ✅
+S2TextFormat                     | ✅
+S2WedgeRelations                 | ✅
+S2WindingOperation               | ❌
 
 ### Encode/Decode
 

go.mod

@@ -1,3 +1,5 @@
 module github.com/golang/geo
 
-go 1.12
+go 1.21
+
+require github.com/google/go-cmp v0.7.0 // indirect

go.sum

@@ -0,0 +1,2 @@
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=

r1/interval.go

@@ -165,7 +165,8 @@ func (i Interval) ApproxEqual(other Interval) bool {
 
 // DirectedHausdorffDistance returns the Hausdorff distance to the given interval. For two
 // intervals x and y, this distance is defined as
-//     h(x, y) = max_{p in x} min_{q in y} d(p, q).
+//
+//	h(x, y) = max_{p in x} min_{q in y} d(p, q).
 func (i Interval) DirectedHausdorffDistance(other Interval) float64 {
 	if i.IsEmpty() {
 		return 0

r3/precisevector.go

@@ -20,10 +20,18 @@ import (
 )
 
 const (
-	// prec is the number of bits of precision to use for the Float values.
-	// To keep things simple, we use the maximum allowable precision on big
-	// values. This allows us to handle all values we expect in the s2 library.
-	prec = big.MaxPrec
+	// MaxPrec is the number of bits of precision to use for the Float values.
+	// To keep things simple, we match the limit used in the C++ library.
+	// This allows us to handle all values we expect in the s2 library.
+	MaxPrec = 64 << 20 // see C++'s util/math/exactfloat/exactfloat.h
+
+	// MaxExp is the maximum exponent supported.  If a value has an exponent larger than
+	// this, it is replaced by infinity (with the appropriate sign).
+	MaxExp = 200 * 1000 * 1000 // About 10**(60 million)
+
+	// MinExp is the minimum exponent supported.  If a value has an exponent less than
+	// this, it is replaced by zero (with the appropriate sign).
+	MinExp = -MaxExp // About 10**(-60 million)
 )
 
 // define some commonly referenced values.
@@ -37,28 +45,28 @@ var (
 // are integer multiples of integer powers of 2.
 func precStr(s string) *big.Float {
 	// Explicitly ignoring the bool return for this usage.
-	f, _ := new(big.Float).SetPrec(prec).SetString(s)
+	f, _ := new(big.Float).SetPrec(MaxPrec).SetString(s)
 	return f
 }
 
 func precInt(i int64) *big.Float {
-	return new(big.Float).SetPrec(prec).SetInt64(i)
+	return new(big.Float).SetPrec(MaxPrec).SetInt64(i)
 }
 
 func precFloat(f float64) *big.Float {
-	return new(big.Float).SetPrec(prec).SetFloat64(f)
+	return new(big.Float).SetPrec(MaxPrec).SetFloat64(f)
 }
 
 func precAdd(a, b *big.Float) *big.Float {
-	return new(big.Float).SetPrec(prec).Add(a, b)
+	return new(big.Float).SetPrec(MaxPrec).Add(a, b)
 }
 
 func precSub(a, b *big.Float) *big.Float {
-	return new(big.Float).SetPrec(prec).Sub(a, b)
+	return new(big.Float).SetPrec(MaxPrec).Sub(a, b)
 }
 
 func precMul(a, b *big.Float) *big.Float {
-	return new(big.Float).SetPrec(prec).Mul(a, b)
+	return new(big.Float).SetPrec(MaxPrec).Mul(a, b)
 }
 
 // PreciseVector represents a point in ℝ³ using high-precision values.
@@ -196,3 +204,8 @@ func (v PreciseVector) SmallestComponent() Axis {
 	}
 	return ZAxis
 }
+
+// IsZero reports if this vector is exactly 0 efficiently.
+func (v PreciseVector) IsZero() bool {
+	return v.X.Sign() == 0 && v.Y.Sign() == 0 && v.Z.Sign() == 0
+}