Import new google3 version.

* Fix python.
* Update docs.
* Add s2region_term_indexer.

Author: jmr

CMakeLists.txt

@@ -82,6 +82,7 @@ add_library(s2 SHARED
             src/s2/s2projections.cc
             src/s2/s2r2rect.cc
             src/s2/s2region.cc
+            src/s2/s2region_term_indexer.cc
             src/s2/s2regioncoverer.cc
             src/s2/s2regionintersection.cc
             src/s2/s2regionunion.cc
@@ -102,6 +103,8 @@ add_library(s2 SHARED
             src/s2/third_party/absl/numeric/int128.cc
             src/s2/third_party/absl/strings/ascii.cc
             src/s2/third_party/absl/strings/match.cc
+            src/s2/third_party/absl/strings/numbers.cc
+            src/s2/third_party/absl/strings/str_cat.cc
             src/s2/third_party/absl/strings/str_split.cc
             src/s2/third_party/absl/strings/string_view.cc
             src/s2/third_party/absl/strings/string_view_utils.cc
@@ -190,6 +193,7 @@ install(FILES src/s2/_fpcontractoff.h
               src/s2/s2projections.h
               src/s2/s2r2rect.h
               src/s2/s2region.h
+              src/s2/s2region_term_indexer.h
               src/s2/s2regioncoverer.h
               src/s2/s2regionintersection.h
               src/s2/s2regionunion.h
@@ -240,6 +244,7 @@ install(FILES src/s2/third_party/absl/meta/type_traits.h
         DESTINATION include/s2/third_party/absl/meta)
 install(FILES src/s2/third_party/absl/numeric/int128.h
               src/s2/third_party/absl/numeric/int128_have_intrinsic.inc
+              src/s2/third_party/absl/numeric/int128_no_intrinsic.inc
         DESTINATION include/s2/third_party/absl/numeric)
 install(FILES src/s2/third_party/absl/strings/string_view.h
         DESTINATION include/s2/third_party/absl/strings)
@@ -347,6 +352,7 @@ if (GTEST_ROOT)
       src/s2/s2projections_test.cc
       src/s2/s2r2rect_test.cc
       src/s2/s2region_test.cc
+      src/s2/s2region_term_indexer_test.cc
       src/s2/s2regioncoverer_test.cc
       src/s2/s2regionunion_test.cc
       src/s2/s2shapeindex_buffered_region_test.cc
@@ -375,17 +381,8 @@ if (GTEST_ROOT)
   endforeach()
 endif()
 
+add_subdirectory("doc/examples" examples)
+
 if (${SWIG_FOUND} AND ${PYTHONLIBS_FOUND})
-  include(${SWIG_USE_FILE})
-  include_directories(${PYTHON_INCLUDE_PATH})
-  set(CMAKE_SWIG_FLAGS "")
-  set_property(SOURCE src/s2/s2.i PROPERTY SWIG_FLAGS "-module" "pywraps2")
-  set_property(SOURCE src/s2/s2.i PROPERTY CPLUSPLUS ON)
-  swig_add_module(pywraps2 python src/s2/s2.i)
-  swig_link_libraries(pywraps2 ${PYTHON_LIBRARIES} s2)
-  enable_testing()
-  add_test(NAME pywraps2_test COMMAND
-           ${PYTHON_EXECUTABLE} "${PROJECT_SOURCE_DIR}/src/s2/pywraps2_test.py")
-  set_property(TEST pywraps2_test PROPERTY ENVIRONMENT
-               "PYTHONPATH=$ENV{PYTHONPATH}:${PROJECT_BINARY_DIR}")
+  add_subdirectory("src/python" python)
 endif()

README.md

@@ -24,16 +24,22 @@ Requirements for End Users
   (to build tests, optional)
 * A POSIX system (for getrusage).
 
-On Ubuntu, all of these can be installed via apt-get.  Otherwise, you may need
-to install some from source.
+On Ubuntu, all of these can be installed via apt-get:
+```
+sudo apt-get install cmake libgflags-dev libgoogle-glog-dev libgtest-dev openssl
+```
+Otherwise, you may need to install some from source.  On OS X, use
+[MacPorts](http://www.macports.org/) or [Homebrew](http://brew.sh/).
 
 Thorough testing has only been done on Ubuntu 14.04.3.
 
 Build and Install
 -----------------
 
 ```
-cd $S2_DIR
+mkdir s2-geometry-library
+cd s2-geometry-library
+tar zxvf $PATH_TO_DOWNLOADED_TGZ
 mkdir build
 cd build
 cmake -DGTEST_ROOT=/usr/src/gtest ..  # Omit -DGTEST_ROOT to skip tests.

doc/basic_types.md

@@ -168,7 +168,8 @@ operators.
 ## S2Region
 
 An `S2Region` represents a two-dimensional region over the unit sphere. It is an
-abstract interface with various concrete subtypes.
+abstract interface with various concrete subtypes, such as discs, rectangles,
+polylines, polygons, geometry collections, buffered shapes, etc.
 
 The main purpose of this interface is to allow complex regions to be
 approximated as simpler regions. So rather than having a wide variety of virtual
@@ -207,12 +208,17 @@ class S2Region {
   // subtypes may relax this restriction.
   virtual bool Contains(const S2Point& p) const = 0;
 
-  // Use encoder to generate a serialized representation of this region.
-  virtual void Encode(Encoder* const encoder) const = 0;
+  //////////////////////////////////////////////////////////////////////////
+  // Many S2Region subtypes also define the following non-virtual methods.
 
-  // Reconstruct a region from the serialized representation generated by
-  // Encode().
-  virtual bool Decode(Decoder* const decoder) = 0;
+  // Appends a serialized representation of the region to "encoder".
+  void Encode(Encoder* const encoder) const;
+
+  // Decodes an S2Region encoded with Encode().  Note that this method
+  // requires that an S2Region object of the appropriate concrete type has
+  // already been constructed.  It is not possible to decode regions of
+  // unknown type.
+  bool Decode(Decoder* const decoder);
 };
 ```
 
@@ -431,7 +437,7 @@ exact predicates needed for robust geometric algorithms.  `S1ChordAngle`
 supports many of the same methods as `S1Angle`, and it is also easy to
 convert back and forth as required.
 
-## S2Cap ("S2Disc")
+## S2Cap
 
 An `S2Cap` represents a spherical cap, i.e. a portion of a sphere cut off by a
 plane. This is the equivalent of a *closed disc* in planar geometry (i.e., a

doc/coverer/coverer.md

@@ -12,7 +12,7 @@ with a 5 km radius cap. When you try to cover that cap with just one
 cell, you often end up with a large amount of extra space. Notice the
 large cell compared to the circle.
 
-![](kirkland_1.gif)\
+![](kirkland_1.gif)
 
 Same configuration, except we allow the use of 2 cells.
 
@@ -58,7 +58,7 @@ cap size of about 500 km and limit of 4 cells. The ratio of "area
 covered by the cells" to "area covered by the cap" is about 10, which is
 about the worst case value when you have at least 4 cells. (The ratio
 can be quite large, on the order of 10\^15, if you limit the covering to
-fewer than 4 cells.)\
+fewer than 4 cells.)
 
 ![](edge_4.gif)
 
@@ -135,3 +135,16 @@ date line.
 Same configuration, except we allow the use of 500 cells.
 
 ![](polar_500.gif)
+
+Finally, here are some examples of geographic coverings.  This is a covering of
+Hawaii using 25 cells.
+
+![](hawaii.gif)
+
+Here is a covering of Florida using 22 cells.
+
+![](florida1.gif)
+
+And Florida using 152 cells.
+
+![](florida2.gif)

doc/coverer/edge_4.gif

@@ -0,0 +1,4 @@
+add_executable(point_index point_index.cc)
+target_link_libraries(point_index LINK_PUBLIC s2testing s2)
+add_executable(term_index term_index.cc)
+target_link_libraries(term_index LINK_PUBLIC s2testing s2)

doc/coverer/florida1.gif

@@ -0,0 +1,42 @@
+// Copyright 2017 Google Inc. All Rights Reserved.
+// Author: [email protected] (Eric Veach)
+//
+// This example shows how to build and query an in-memory index of points
+// using S2PointIndex.
+
+#include <cstdio>
+#include <gflags/gflags.h>
+#include "s2/s2earth.h"
+#include "s2/s1chordangle.h"
+#include "s2/s2closestpointquery.h"
+#include "s2/s2pointindex.h"
+#include "s2/s2testing.h"
+
+DEFINE_int32(num_index_points, 10000, "Number of points to index");
+DEFINE_int32(num_queries, 10000, "Number of queries");
+DEFINE_double(query_radius_km, 100, "Query radius in kilometers");
+
+int main(int argc, char **argv) {
+  // Build an index containing random points anywhere on the Earth.
+  S2PointIndex<int> index;
+  for (int i = 0; i < FLAGS_num_index_points; ++i) {
+    index.Add(S2Testing::RandomPoint(), i);
+  }
+
+  // Create a query to search within the given radius of a target point.
+  S2ClosestPointQuery<int> query(&index);
+  query.mutable_options()->set_max_distance(
+      S1Angle::Radians(S2Earth::KmToRadians(FLAGS_query_radius_km)));
+
+  // Repeatedly choose a random target point, and count how many index points
+  // are within the given radius of that point.
+  int64 num_found = 0;
+  for (int i = 0; i < FLAGS_num_queries; ++i) {
+    S2ClosestPointQuery<int>::PointTarget target(S2Testing::RandomPoint());
+    num_found += query.FindClosestPoints(&target).size();
+  }
+
+  std::printf("Found %lld points in %d queries\n",
+              num_found, FLAGS_num_queries);
+  return  0;
+}