pybind: Add S2Cell bindings by deustis · Pull Request #4 · deustis/s2geometry

deustis · 2026-05-07T00:42:40Z

Adds pybind11 bindings for S2Cell, covering constructors, factory methods, properties, geometric operations, containment/intersection tests, distance queries, and traversal.

The is_distance_less / is_distance_less_or_equal family is omitted — callers can use get_distance(...) < limit directly.

Naming: GetDistance is overloaded in C++ for S2Point, edge (a, b), and S2Cell arguments. Per the binding interface notes, the short name (get_distance) is used for the S2Point overload, and longer names (get_distance_to_edge, get_distance_to_cell) for the others. get_max_distance follows the same pattern.

_raw variants omitted: vertex_raw, edge_raw, and center_raw return unnormalized vectors intended for feeding into exact C++ predicates. Python callers won't do that, so these are dropped in favor of the normalized versions.

subdivide() returns a 4-tuple of S2Cell rather than an output array. get_cap_bound and get_rect_bound are deferred until S2Cap and S2LatLngRect are bound. Encode / Decode are intentionally omitted per the serialization policy in the pybind README.

Test plan

bazel test //python/... — all suites pass.

Binds S2Cell's constructors, factory methods, geometric accessors (vertex, edge, center, area), boundary helpers, containment and intersection predicates, and subdivide. Adds 43 unit tests. Distance methods and the S2Cap/S2LatLngRect-returning region methods are deferred with a TODO; they depend on S1ChordAngle/S2Cap/S2LatLngRect bindings which are not yet in place. (Stacked on deustis/s2cell_id_bindings / PR google#593.)

- Drop MaybeThrowNotValidCellId from S2Cell(S2CellId) constructor; all S2CellId objects reachable from Python are already validated - Remove instance average_area(); keep only static average_area_for_level() - Add S2CellId::kMaxPosition constant and validate pos in from_face_pos_level for both S2CellId and S2Cell bindings - Switch constants to cls.attr() pattern in both S2CellId and S2Cell bindings; update README to document this style - Fix BUILD: add absl/strings dep to s2cell_id_bindings - Remove misleading encode/decode comment from s2cell_bindings.cc - Fix magic constant 1<<30 -> 1<<S2CellId.MAX_LEVEL in s2cell_test.py

Consistent with other MaybeThrow* helpers in both binding files.

- Fix s2cell deps comment in module.cc to include s1chord_angle - Clarify orientation docstring (bitmask, values 0-3) - Drop _raw variants (vertex_raw, edge_raw, center_raw): Python callers don't feed unnormalized vectors into exact C++ predicates

deustis · 2026-05-26T16:09:55Z

+        # Orientation is in [0, 3].
+        for f in range(6):
+            orient = s2.S2Cell.from_face(f).orientation
+            self.assertIn(orient, range(4))


Assert exact (or floating point approx) values in tests

Done — test now asserts face cells have orientation 0, with a range check on a non-face cell.

deustis · 2026-05-26T16:11:06Z

+        self.assertAlmostEqual(v0.y, v4.y)
+        self.assertAlmostEqual(v0.z, v4.z)
+
+    def test_vertex_raw(self):


I thought we removed these _raw variants

deustis · 2026-05-26T16:11:52Z

+        # Face cell in (i,j) spans [0, 2^30].
+        bottom = face.ij_coord_of_edge(s2.S2Cell.BOTTOM_EDGE)
+        top = face.ij_coord_of_edge(s2.S2Cell.TOP_EDGE)
+        self.assertIn(bottom, (0, 1 << 30))


assert a value

Done — now asserts BOTTOM=0, TOP=2^30, LEFT=0, RIGHT=2^30.

deustis · 2026-05-26T16:12:40Z

+        with self.assertRaises(ValueError):
+            s2.S2Cell.average_area_for_level(-1)
+
+    def test_approx_area_positive(self):


this test is not useful, assert an approximate value within the error tolerance

Done — now checks the face cell area is within 3% of 4π/6.

deustis · 2026-05-26T16:14:29Z

+      .def("may_intersect", &S2Cell::MayIntersect, py::arg("cell"),
+           "Return true if this cell may intersect the given cell")
+
+      // Traversal


Let's get rid of traversal section and move this to geometric operations (also in tests)

Done — Traversal section removed, subdivide moved into Geometric operations.

deustis · 2026-05-26T16:15:28Z

  // Deps: s1angle, s2point, s2latlng, r2point, r2rect
  bind_s2cell_id(m);
+
+  // Deps: s2cell_id, s2point, s2latlng, s1chord_angle, r2rect


make the deps order match the declaration order above

Fixed — now r2rect, s1chord_angle, s2cell_id, s2latlng, s2point.

deustis · 2026-05-26T16:37:18Z

Superseded by google#631.

deustis mentioned this pull request May 7, 2026

pybind: Add S1ChordAngle bindings #5

Closed

1 task

deustis force-pushed the deustis/s2cell_bindings branch from c2cd642 to e212df1 Compare May 12, 2026 16:44

deustis changed the base branch from deustis/s2cell_id_bindings to master May 12, 2026 16:44

deustis commented May 12, 2026

View reviewed changes

Comment thread src/python/s2cell_bindings.cc Outdated

Comment thread src/python/s2cell_bindings.cc

Comment thread src/python/s2cell_bindings.cc

deustis commented May 12, 2026

View reviewed changes

Comment thread src/python/s2cell_id_bindings.cc Outdated

deustis force-pushed the deustis/s2cell_bindings branch from 9e7ace4 to a9a433c Compare May 12, 2026 19:34

deustis changed the base branch from master to deustis/s2cell_id_binding_fixes May 12, 2026 19:37

deustis force-pushed the deustis/s2cell_bindings branch from a9a433c to 1fc4db2 Compare May 12, 2026 22:52

deustis force-pushed the deustis/s2cell_id_binding_fixes branch from 32b3ab8 to 96ba727 Compare May 22, 2026 21:15

deustis force-pushed the deustis/s2cell_bindings branch from 1fc4db2 to 31d1af1 Compare May 22, 2026 21:15

deustis added 3 commits May 26, 2026 15:17

pybind: Extract pos validation to MaybeThrowPositionOutOfRange helper

677224f

Consistent with other MaybeThrow* helpers in both binding files.

deustis force-pushed the deustis/s2cell_bindings branch from 31d1af1 to 677224f Compare May 26, 2026 15:17

deustis changed the base branch from deustis/s2cell_id_binding_fixes to master May 26, 2026 15:30

pybind: Add S2Cell distance methods using S1ChordAngle

59d3dc0

deustis commented May 26, 2026

View reviewed changes

Comment thread src/python/module.cc Outdated

Comment thread src/python/s2cell_bindings.cc Outdated

Comment thread src/python/s2cell_bindings.cc Outdated

Comment thread src/python/s2cell_bindings.cc

pybind: Address S2Cell review comments

bb2c178

- Fix s2cell deps comment in module.cc to include s1chord_angle - Clarify orientation docstring (bitmask, values 0-3) - Drop _raw variants (vertex_raw, edge_raw, center_raw): Python callers don't feed unnormalized vectors into exact C++ predicates

deustis commented May 26, 2026

View reviewed changes

pybind: Address S2Cell review comments (tests and structure)

f9238c9

deustis closed this May 26, 2026

Conversation

deustis commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test plan

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

deustis commented May 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

deustis commented May 7, 2026 •

edited

Loading