s2: Add Polyline.Uninterpolate.

Signed-off-by: David Symonds <dsymonds@golang.org>

Author: rsned

README.md

@@ -150,7 +150,7 @@ listing of the incomplete methods are documented at the end of each file.
 *   ContainsPointQuery - missing visit edges
 *   laxPolygon
 *   Loop - Loop is mostly complete now. Missing Project, Distance, Union, etc.
-*   Polyline - Missing Interpolate, etc.
+*   Polyline - Missing InitTo... methods, NearlyCoversPolyline
 *   Rect (AKA s2latlngrect in C++) - Missing Centroid, InteriorContains.
 *   RegionCoverer - canonicalize
 *   s2_test.go (AKA s2testing and s2textformat in C++) - Missing Fractal test

s2/polyline.go

@@ -556,11 +556,34 @@ func (p *Polyline) Interpolate(fraction float64) (Point, int) {
 	return (*p)[len(*p)-1], len(*p)
 }
 
+// Uninterpolate is the inverse operation of Interpolate. Given a point on the
+// polyline, it returns the ratio of the distance to the point from the
+// beginning of the polyline over the length of the polyline. The return
+// value is always betwen 0 and 1 inclusive.
+//
+// The polyline should not be empty.  If it has fewer than 2 vertices, the
+// return value is zero.
+func (p *Polyline) Uninterpolate(point Point, nextVertex int) float64 {
+	if len(*p) < 2 {
+		return 0
+	}
+
+	var sum s1.Angle
+	for i := 1; i < nextVertex; i++ {
+		sum += (*p)[i-1].Distance((*p)[i])
+	}
+	lengthToPoint := sum + (*p)[nextVertex-1].Distance(point)
+	for i := nextVertex; i < len(*p); i++ {
+		sum += (*p)[i-1].Distance((*p)[i])
+	}
+	// The ratio can be greater than 1.0 due to rounding errors or because the
+	// point is not exactly on the polyline.
+	return minFloat64(1.0, float64(lengthToPoint/sum))
+}
+
 // TODO(roberts): Differences from C++.
-// UnInterpolate
 // NearlyCoversPolyline
 // InitToSnapped
 // InitToSimplified
-// IsValid
 // SnapLevel
 // encode/decode compressed

s2/polyline_test.go

@@ -584,8 +584,50 @@ func TestPolylineInterpolate(t *testing.T) {
 	}
 }
 
+func TestPolylineUninterpolate(t *testing.T) {
+	vertices := []Point{PointFromCoords(1, 0, 0)}
+	line := Polyline(vertices)
+	if got, want := line.Uninterpolate(PointFromCoords(0, 1, 0), 1), 0.0; !float64Eq(got, want) {
+		t.Errorf("Uninterpolate on a polyline with 2 or fewer vertices should return 0, got %v", got)
+	}
+
+	vertices = append(vertices,
+		PointFromCoords(0, 1, 0),
+		PointFromCoords(0, 1, 1),
+		PointFromCoords(0, 0, 1),
+	)
+	line = Polyline(vertices)
+
+	interpolated, nextVertex := line.Interpolate(-0.1)
+	if got, want := line.Uninterpolate(interpolated, nextVertex), 0.0; !float64Eq(got, want) {
+		t.Errorf("line.Uninterpolate(%v, %d) = %v, want %v", interpolated, nextVertex, got, want)
+	}
+	interpolated, nextVertex = line.Interpolate(0.0)
+	if got, want := line.Uninterpolate(interpolated, nextVertex), 0.0; !float64Eq(got, want) {
+		t.Errorf("line.Uninterpolate(%v, %d) = %v, want %v", interpolated, nextVertex, got, want)
+	}
+	interpolated, nextVertex = line.Interpolate(0.5)
+	if got, want := line.Uninterpolate(interpolated, nextVertex), 0.5; !float64Eq(got, want) {
+		t.Errorf("line.Uninterpolate(%v, %d) = %v, want %v", interpolated, nextVertex, got, want)
+	}
+	interpolated, nextVertex = line.Interpolate(0.75)
+	if got, want := line.Uninterpolate(interpolated, nextVertex), 0.75; !float64Eq(got, want) {
+		t.Errorf("line.Uninterpolate(%v, %d) = %v, want %v", interpolated, nextVertex, got, want)
+	}
+	interpolated, nextVertex = line.Interpolate(1.1)
+	if got, want := line.Uninterpolate(interpolated, nextVertex), 1.0; !float64Eq(got, want) {
+		t.Errorf("line.Uninterpolate(%v, %d) = %v, want %v", interpolated, nextVertex, got, want)
+	}
+
+	// Check that the return value is clamped to 1.0.
+	if got, want := line.Uninterpolate(PointFromCoords(0, 1, 0), len(line)), 1.0; !float64Eq(got, want) {
+		t.Errorf("line.Uninterpolate(%v, %d) = %v, want %v", PointFromCoords(0, 1, 0), len(line), got, want)
+	}
+}
+
 // TODO(roberts): Test differences from C++:
-// UnInterpolate
+// InitToSnapped
+// InitToSimplified
 //
 // PolylineCoveringTest
 //    PolylineOverlapsSelf