@sentryware/s2-node 0.0.6

package/third_party/s2geometry/src/s2/s2shape_index_buffered_region.cc

@@ -0,0 +1,113 @@
+// Copyright 2017 Google Inc. All Rights Reserved.
+//
+// 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.
+//
+
+// Author: ericv@google.com (Eric Veach)
+
+#include "s2/s2shape_index_buffered_region.h"
+
+#include <algorithm>
+#include <vector>
+#include "s2/s2metrics.h"
+#include "s2/s2shape_index_region.h"
+
+using std::min;
+using std::vector;
+
+S2ShapeIndexBufferedRegion::S2ShapeIndexBufferedRegion() {
+}
+
+void S2ShapeIndexBufferedRegion::Init(const S2ShapeIndex* index,
+                                      S1ChordAngle radius) {
+  radius_ = radius;
+  radius_successor_ = radius.Successor();
+  query_.Init(index);
+  query_.mutable_options()->set_include_interiors(true);
+}
+
+S2ShapeIndexBufferedRegion* S2ShapeIndexBufferedRegion::Clone() const {
+  return new S2ShapeIndexBufferedRegion(&index(), radius_);
+}
+
+S2Cap S2ShapeIndexBufferedRegion::GetCapBound() const {
+  S2Cap orig_cap = MakeS2ShapeIndexRegion(&index()).GetCapBound();
+  return S2Cap(orig_cap.center(), orig_cap.radius() + radius_);
+}
+
+S2LatLngRect S2ShapeIndexBufferedRegion::GetRectBound() const {
+  S2LatLngRect orig_rect = MakeS2ShapeIndexRegion(&index()).GetRectBound();
+  return orig_rect.ExpandedByDistance(radius_.ToAngle());
+}
+
+void S2ShapeIndexBufferedRegion::GetCellUnionBound(vector<S2CellId> *cellids)
+    const {
+  // We start with a covering of the original S2ShapeIndex, and then expand it
+  // by replacing each cell with a block of 4 cells whose union contains the
+  // original cell buffered by the given radius.
+  //
+  // This increases the number of cells in the covering by a factor of 4 and
+  // increases the covered area by a factor of 16, so it is not a very good
+  // covering, but it is much better than always returning the 6 face cells.
+  vector<S2CellId> orig_cellids;
+  MakeS2ShapeIndexRegion(&index()).GetCellUnionBound(&orig_cellids);
+
+  double radians = radius_.ToAngle().radians();
+  int max_level = S2::kMinWidth.GetLevelForMinValue(radians) - 1;
+  if (max_level < 0) {
+    return S2Cap::Full().GetCellUnionBound(cellids);
+  }
+  cellids->clear();
+  for (S2CellId id : orig_cellids) {
+    if (id.is_face()) {
+      return S2Cap::Full().GetCellUnionBound(cellids);
+    }
+    id.AppendVertexNeighbors(min(max_level, id.level() - 1), cellids);
+  }
+}
+
+bool S2ShapeIndexBufferedRegion::Contains(const S2Cell& cell) const {
+  // To implement this method perfectly would require computing the directed
+  // Hausdorff distance, which is expensive (and not currently implemented).
+  // However the following heuristic is almost as good in practice and much
+  // cheaper to compute.
+
+  // Return true if the unbuffered region contains this cell.
+  if (MakeS2ShapeIndexRegion(&index()).Contains(cell)) return true;
+
+  // Otherwise approximate the cell by its bounding cap.
+  //
+  // NOTE(ericv): It would be slightly more accurate to first find the closest
+  // point in the indexed geometry to the cell, and then measure the actual
+  // maximum distance from that point to the cell (a poor man's Hausdorff
+  // distance).  But based on actual tests this is not worthwhile.
+  S2Cap cap = cell.GetCapBound();
+  if (radius_ < cap.radius()) return false;
+
+  // Return true if the distance to the cell center plus the radius of the
+  // cell's bounding cap is less than or equal to "radius_".
+  S2ClosestEdgeQuery::PointTarget target(cell.GetCenter());
+  return query_.IsDistanceLess(&target, radius_successor_ - cap.radius());
+}
+
+bool S2ShapeIndexBufferedRegion::MayIntersect(const S2Cell& cell) const {
+  // Return true if the distance is less than or equal to "radius_".
+  S2ClosestEdgeQuery::CellTarget target(cell);
+  return query_.IsDistanceLess(&target, radius_successor_);
+}
+
+bool S2ShapeIndexBufferedRegion::Contains(const S2Point& p) const {
+  S2ClosestEdgeQuery::PointTarget target(p);
+  // Return true if the distance is less than or equal to "radius_".
+  return query_.IsDistanceLess(&target, radius_successor_);
+}

package/third_party/s2geometry/src/s2/s2shape_index_buffered_region.h

@@ -0,0 +1,135 @@
+// Copyright 2017 Google Inc. All Rights Reserved.
+//
+// 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.
+//
+
+// Author: ericv@google.com (Eric Veach)
+
+#ifndef S2_S2SHAPE_INDEX_BUFFERED_REGION_H_
+#define S2_S2SHAPE_INDEX_BUFFERED_REGION_H_
+
+#include <vector>
+#include "s2/s2cap.h"
+#include "s2/s2cell.h"
+#include "s2/s2cell_union.h"
+#include "s2/s2closest_edge_query.h"
+#include "s2/s2latlng_rect.h"
+#include "s2/s2region.h"
+#include "s2/s2shape_index.h"
+
+// This class provides a way to expand an arbitrary collection of geometry by
+// a fixed radius (an operation variously known as "buffering", "offsetting",
+// or "Minkowski sum with a disc") in order to compute an S2CellId covering
+// (see S2RegionCoverer).  The resulting covering contains all points within
+// the given radius of any point in the original geometry.
+//
+// This class does not actually buffer the geometry; instead it implements the
+// S2Region API by computing the distance from candidate S2CellIds to the
+// original geometry.  If this distance is below the given radius then the
+// S2CellId intersects the buffered geometry.  For example, if the original
+// geometry consists of a single S2Point then the buffered geometry is exactly
+// equivalent to an S2Cap with the given radius.  (Note that the region is not
+// approximated as a polygonal loop.)
+//
+// Example usage:
+//
+// S2CellUnion GetBufferedCovering(const S2ShapeIndex& index, S1Angle radius) {
+//   S2RegionCoverer coverer;
+//   coverer.mutable_options()->set_max_cells(20);
+//   S2CellUnion covering;
+//   S2ShapeIndexBufferedRegion region(&index, radius);
+//   coverer.GetCovering(region, &covering);
+//   return covering;
+// }
+//
+// This class is not thread-safe.  To use it in parallel, each thread should
+// construct its own instance (this is not expensive).
+class S2ShapeIndexBufferedRegion final : public S2Region {
+ public:
+  // Default constructor; requires Init() to be called.
+  S2ShapeIndexBufferedRegion();
+
+  // Constructs a region representing all points within the given radius of
+  // any point in the given S2ShapeIndex.
+  S2ShapeIndexBufferedRegion(const S2ShapeIndex* index,
+                             S1ChordAngle radius);
+
+  // Convenience constructor that accepts an S1Angle for the radius.
+  // REQUIRES: radius >= S1Angle::Zero()
+  S2ShapeIndexBufferedRegion(const S2ShapeIndex* index, S1Angle radius)
+      : S2ShapeIndexBufferedRegion(index, S1ChordAngle(radius)) {}
+
+  // Equivalent to the constructor above.
+  void Init(const S2ShapeIndex* index, S1ChordAngle radius);
+
+  const S2ShapeIndex& index() const;
+  S1ChordAngle radius() const;
+
+  ////////////////////////////////////////////////////////////////////////
+  // S2Region interface (see s2region.h for details):
+
+  // Clone() returns a *shallow* copy; it does not make a copy of the
+  // underlying S2ShapeIndex.
+  S2ShapeIndexBufferedRegion* Clone() const override;
+
+  S2Cap GetCapBound() const override;
+  S2LatLngRect GetRectBound() const override;
+
+  // This method returns a small non-optimal covering that may include
+  // duplicate or overlapping cells.  It should not be used directly.
+  // Instead, use S2RegionCoverer::GetCovering or GetFastCovering.
+  void GetCellUnionBound(std::vector<S2CellId> *cellids) const override;
+
+  // The implementation is approximate but conservative; it always returns
+  // "false" if the cell is not contained by the buffered region, but it may
+  // also return false in some cases where "cell" is in fact contained.
+  bool Contains(const S2Cell& cell) const override;
+
+  // Returns true if any buffered shape intersects "cell" (to within a very
+  // small error margin).
+  bool MayIntersect(const S2Cell& cell) const override;
+
+  // Returns true if the given point is contained by the buffered region,
+  // i.e. if it is within the given radius of any original shape.
+  bool Contains(const S2Point& p) const override;
+
+ private:
+  S1ChordAngle radius_;
+
+  // In order to handle (radius_ == 0) corectly, we need to test whether
+  // distances are less than or equal to "radius_".  This is done by testing
+  // whether distances are less than radius_.Successor().
+  S1ChordAngle radius_successor_;
+
+  mutable S2ClosestEdgeQuery query_;  // This class is not thread-safe!
+};
+
+
+//////////////////   Implementation details follow   ////////////////////
+
+
+inline S2ShapeIndexBufferedRegion::S2ShapeIndexBufferedRegion(
+    const S2ShapeIndex* index, S1ChordAngle radius)
+    : radius_(radius), radius_successor_(radius.Successor()), query_(index) {
+  query_.mutable_options()->set_include_interiors(true);
+}
+
+inline const S2ShapeIndex& S2ShapeIndexBufferedRegion::index() const {
+  return query_.index();
+}
+
+inline S1ChordAngle S2ShapeIndexBufferedRegion::radius() const {
+  return radius_;
+}
+
+#endif  // S2_S2SHAPE_INDEX_BUFFERED_REGION_H_

package/third_party/s2geometry/src/s2/s2shape_index_buffered_region_test.cc

@@ -0,0 +1,162 @@
+// Copyright 2017 Google Inc. All Rights Reserved.
+//
+// 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.
+//
+
+// Author: ericv@google.com (Eric Veach)
+
+#include "s2/s2shape_index_buffered_region.h"
+
+#include <iostream>
+#include <memory>
+#include <gtest/gtest.h>
+#include "s2/third_party/absl/memory/memory.h"
+#include "s2/mutable_s2shape_index.h"
+#include "s2/s2cap.h"
+#include "s2/s2cell_union.h"
+#include "s2/s2polygon.h"
+#include "s2/s2region_coverer.h"
+#include "s2/s2shape_index.h"
+#include "s2/s2testing.h"
+#include "s2/s2text_format.h"
+
+using absl::make_unique;
+using s2textformat::MakeIndexOrDie;
+using s2textformat::MakePointOrDie;
+using std::cout;
+
+TEST(S2ShapeIndexBufferedRegion, EmptyIndex) {
+  // Test buffering an empty S2ShapeIndex.
+  MutableS2ShapeIndex index;
+  S1ChordAngle radius(S1Angle::Degrees(2));
+  S2ShapeIndexBufferedRegion region(&index, radius);
+  S2RegionCoverer coverer;
+  S2CellUnion covering = coverer.GetCovering(region);
+  EXPECT_TRUE(covering.empty());
+}
+
+TEST(S2ShapeIndexBufferedRegion, FullPolygon) {
+  // Test buffering an S2ShapeIndex that contains a full polygon.
+  auto index = MakeIndexOrDie("# # full");
+  S1ChordAngle radius(S1Angle::Degrees(2));
+  S2ShapeIndexBufferedRegion region(index.get(), radius);
+  S2RegionCoverer coverer;
+  S2CellUnion covering = coverer.GetCovering(region);
+  ASSERT_EQ(6, covering.num_cells());
+  for (S2CellId id : covering) {
+    EXPECT_TRUE(id.is_face());
+  }
+}
+
+TEST(S2ShapeIndexBufferedRegion, FullAfterBuffering) {
+  // Test a region that becomes the full polygon after buffering.
+  auto index = MakeIndexOrDie("0:0 | 0:90 | 0:180 | 0:-90 | 90:0 | -90:0 # #");
+  S1ChordAngle radius(S1Angle::Degrees(60));
+  S2ShapeIndexBufferedRegion region(index.get(), radius);
+  S2RegionCoverer coverer;
+  coverer.mutable_options()->set_max_cells(1000);
+  S2CellUnion covering = coverer.GetCovering(region);
+  ASSERT_EQ(6, covering.num_cells());
+  for (S2CellId id : covering) {
+    EXPECT_TRUE(id.is_face());
+  }
+}
+
+TEST(S2ShapeIndexBufferedRegion, PointZeroRadius) {
+  // Test that buffering a point using a zero radius produces a non-empty
+  // covering.  (This requires using "less than or equal to" distance tests.)
+  auto index = MakeIndexOrDie("34:25 # #");
+  S2ShapeIndexBufferedRegion region(index.get(), S1ChordAngle::Zero());
+  S2RegionCoverer coverer;
+  S2CellUnion covering = coverer.GetCovering(region);
+  EXPECT_EQ(1, covering.num_cells());
+  for (S2CellId id : covering) {
+    EXPECT_TRUE(id.is_leaf());
+  }
+}
+
+TEST(S2ShapeIndexBufferedRegion, BufferedPointVsCap) {
+  // Compute an S2Cell covering of a buffered S2Point, then make sure that the
+  // covering is equivalent to the corresponding S2Cap.
+  auto index = MakeIndexOrDie("3:5 # #");
+  S2Point point = MakePointOrDie("3:5");
+  S1ChordAngle radius(S1Angle::Degrees(2));
+  S2ShapeIndexBufferedRegion region(index.get(), radius);
+  S2RegionCoverer coverer;
+  coverer.mutable_options()->set_max_cells(50);
+  S2CellUnion covering = coverer.GetCovering(region);
+  S2Cap equivalent_cap(point, radius);
+  S2Testing::CheckCovering(equivalent_cap, covering, true);
+}
+
+// Verifies that an arbitrary S2ShapeIndex is buffered correctly, by first
+// converting the covering to an S2Polygon and then checking that (a) the
+// S2Polygon contains the original geometry and (b) the distance between the
+// original geometry and the boundary of the S2Polygon is at least "radius".
+//
+// The "radius" parameter is an S1Angle for convenience.
+// TODO(ericv): Add Degrees, Radians, etc, methods to S1ChordAngle?
+void TestBufferIndex(const string& index_str, S1Angle radius_angle,
+                     S2RegionCoverer* coverer) {
+  auto index = MakeIndexOrDie(index_str);
+  S1ChordAngle radius(radius_angle);
+  S2ShapeIndexBufferedRegion region(index.get(), radius);
+  S2CellUnion covering = coverer->GetCovering(region);
+  S2_LOG(INFO) << "Covering uses " << covering.num_cells()
+            << " cells vs. max of " << coverer->options().max_cells();
+  if (S2_VLOG_IS_ON(2)) {
+    // Output the cells in the covering for visualization purposes.
+    for (S2CellId id : covering) {
+      cout << "\nS2Polygon: " << s2textformat::ToString(S2Polygon(S2Cell(id)));
+    }
+    cout << "\n\n" << std::flush;
+  }
+  // Compute an S2Polygon representing the union of the cells in the covering.
+  S2Polygon covering_polygon;
+  covering_polygon.InitToCellUnionBorder(covering);
+  MutableS2ShapeIndex covering_index;
+  covering_index.Add(make_unique<S2Polygon::Shape>(&covering_polygon));
+
+  // (a) Check that the covering contains the original index.
+  EXPECT_TRUE(S2BooleanOperation::Contains(covering_index, *index));
+
+  // (b) Check that the distance between the boundary of the covering and the
+  // the original indexed geometry is at least "radius".
+  S2ClosestEdgeQuery query(&covering_index);
+  query.mutable_options()->set_include_interiors(false);
+  S2ClosestEdgeQuery::ShapeIndexTarget target(index.get());
+  EXPECT_FALSE(query.IsDistanceLess(&target, radius));
+}
+
+TEST(S2ShapeIndexBufferedRegion, PointSet) {
+  // Test buffering a set of points.
+  S2RegionCoverer coverer;
+  coverer.mutable_options()->set_max_cells(100);
+  TestBufferIndex("10:20 | 10:23 | 10:26 # #", S1Angle::Degrees(5), &coverer);
+}
+
+TEST(S2ShapeIndexBufferedRegion, Polyline) {
+  // Test buffering a polyline.
+  S2RegionCoverer coverer;
+  coverer.mutable_options()->set_max_cells(100);
+  TestBufferIndex("# 10:5, 20:30, -10:60, -60:100 #",
+                  S1Angle::Degrees(2), &coverer);
+}
+
+TEST(S2ShapeIndexBufferedRegion, PolygonWithHole) {
+  // Test buffering a polygon with a hole.
+  S2RegionCoverer coverer;
+  coverer.mutable_options()->set_max_cells(100);
+  TestBufferIndex("# # 10:10, 10:100, 70:0; 11:11, 69:0, 11:99",
+                  S1Angle::Degrees(2), &coverer);
+}

package/third_party/s2geometry/src/s2/s2shape_index_measures.cc

@@ -0,0 +1,92 @@
+// Copyright 2018 Google Inc. All Rights Reserved.
+//
+// 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.
+//
+
+// Author: ericv@google.com (Eric Veach)
+
+#include "s2/s2shape_index_measures.h"
+
+#include "s2/s2shape_measures.h"
+
+namespace S2 {
+
+int GetDimension(const S2ShapeIndex& index) {
+  int dim = -1;
+  for (int i = 0; i < index.num_shape_ids(); ++i) {
+    S2Shape* shape = index.shape(i);
+    if (shape) dim = std::max(dim, shape->dimension());
+  }
+  return dim;
+}
+
+int GetNumPoints(const S2ShapeIndex& index) {
+  int count = 0;
+  for (int i = 0; i < index.num_shape_ids(); ++i) {
+    S2Shape* shape = index.shape(i);
+    if (shape && shape->dimension() == 0) {
+      count += shape->num_edges();
+    }
+  }
+  return count;
+}
+
+S1Angle GetLength(const S2ShapeIndex& index) {
+  S1Angle length;
+  for (int i = 0; i < index.num_shape_ids(); ++i) {
+    S2Shape* shape = index.shape(i);
+    if (shape) length += S2::GetLength(*shape);
+  }
+  return length;
+}
+
+S1Angle GetPerimeter(const S2ShapeIndex& index) {
+  S1Angle perimeter;
+  for (int i = 0; i < index.num_shape_ids(); ++i) {
+    S2Shape* shape = index.shape(i);
+    if (shape) perimeter += S2::GetPerimeter(*shape);
+  }
+  return perimeter;
+}
+
+double GetArea(const S2ShapeIndex& index) {
+  double area = 0;
+  for (int i = 0; i < index.num_shape_ids(); ++i) {
+    S2Shape* shape = index.shape(i);
+    if (shape) area += S2::GetArea(*shape);
+  }
+  return area;
+}
+
+double GetApproxArea(const S2ShapeIndex& index) {
+  double area = 0;
+  for (int i = 0; i < index.num_shape_ids(); ++i) {
+    S2Shape* shape = index.shape(i);
+    if (shape) area += S2::GetApproxArea(*shape);
+  }
+  return area;
+}
+
+S2Point GetCentroid(const S2ShapeIndex& index) {
+  int dim = GetDimension(index);
+  S2Point centroid;
+  for (int i = 0; i < index.num_shape_ids(); ++i) {
+    S2Shape* shape = index.shape(i);
+    if (shape && shape->dimension() == dim) {
+      centroid += S2::GetCentroid(*shape);
+    }
+  }
+  return centroid;
+}
+
+}  // namespace S2

package/third_party/s2geometry/src/s2/s2shape_index_measures.h

@@ -0,0 +1,100 @@
+// Copyright 2018 Google Inc. All Rights Reserved.
+//
+// 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.
+//
+
+// Author: ericv@google.com (Eric Veach)
+//
+// Defines various angle and area measures for S2ShapeIndex objects.  In
+// general, these methods return the sum of the corresponding measure for the
+// S2Shapes in the index.
+
+#ifndef S2_S2SHAPE_INDEX_MEASURES_H_
+#define S2_S2SHAPE_INDEX_MEASURES_H_
+
+#include "s2/s1angle.h"
+#include "s2/s2point.h"
+#include "s2/s2shape_index.h"
+
+namespace S2 {
+
+// Returns the maximum dimension of any shape in the index.  Returns -1 if the
+// index does not contain any shapes.
+//
+// Note that the dimension does *not* depend on whether the shapes in the
+// index contain any points; for example, the dimension of an empty point set
+// is 0, and the dimension of an empty polygon is 2.
+int GetDimension(const S2ShapeIndex& index);
+
+// Returns the number of points (objects of dimension zero) in the index.
+// Note that polyline and polygon vertices are *not* included in this count.
+int GetNumPoints(const S2ShapeIndex& index);
+
+// Returns the total length of all polylines in the index.  Returns zero if no
+// polylines are present.
+//
+// All edges are modeled as spherical geodesics.  The result can be converted
+// to a distance on the Earth's surface (with a worst-case error of 0.562%
+// near the equator) using the functions in s2earth.h.
+S1Angle GetLength(const S2ShapeIndex& index);
+
+// Returns the total perimeter of all polygons in the index (including both
+// "shells" and "holes").  Returns zero if no polygons are present.
+//
+// All edges are modeled as spherical geodesics.  The result can be converted
+// to a distance on the Earth's surface (with a worst-case error of 0.562%
+// near the equator) using the functions in s2earth.h.
+S1Angle GetPerimeter(const S2ShapeIndex& index);
+
+// Returns the total area of all polygons in the index.  Returns zero if no
+// polygons are present.  This method has good relative accuracy for both very
+// large and very small regions.  Note that the result may exceed 4*Pi if the
+// index contains overlapping polygons.
+//
+// All edges are modeled as spherical geodesics.  The result can be converted
+// to an area on the Earth's surface (with a worst-case error of 0.900% near
+// the poles) using the functions in s2earth.h.
+double GetArea(const S2ShapeIndex& index);
+
+// Like GetArea(), except that this method is faster and has more error.  The
+// additional error is at most 2.22e-15 steradians per vertex, which works out
+// to about 0.09 square meters per vertex on the Earth's surface.  For
+// example, a loop with 100 vertices has a maximum error of about 9 square
+// meters.  (The actual error is typically much smaller than this.)
+double GetApproxArea(const S2ShapeIndex& index);
+
+// Returns the centroid of all shapes whose dimension is maximal within the
+// index, multiplied by the measure of those shapes.  For example, if the
+// index contains points and polylines, then the result is defined as the
+// centroid of the polylines multiplied by the total length of those
+// polylines.  The points would be ignored when computing the centroid.
+//
+// The measure of a given shape is defined as follows:
+//
+//  - For dimension 0 shapes, the measure is shape->num_edges().
+//  - For dimension 1 shapes, the measure is GetLength(shape).
+//  - For dimension 2 shapes, the measure is GetArea(shape).
+//
+// Note that the centroid is not unit length, so you may need to call
+// Normalize() before passing it to other S2 functions.  Note that this
+// function returns (0, 0, 0) if the index contains no geometry.
+//
+// The centroid is scaled by the total measure of the shapes for two reasons:
+// (1) it is cheaper to compute this way, and (2) this makes it easier to
+// compute the centroid of a collection of shapes (since the individual
+// centroids can simply be summed).
+S2Point GetCentroid(const S2ShapeIndex& index);
+
+}  // namespace S2
+
+#endif  // S2_S2SHAPE_INDEX_MEASURES_H_