pybind: Add S2Interval bindings (#524)

Add pybind11 bindings for S1Interval.

Also add interface notes to the python README

Author: deustis

src/python/BUILD.bazel

@@ -25,14 +25,26 @@ py_library(
 pybind_extension(
     name = "s2geometry_bindings",
     srcs = ["module.cc"],
+    copts = ["-DNDEBUG"],
     deps = [
+        ":s1interval_bindings",
         ":s2point_bindings",
     ],
 )
 
+pybind_library(
+    name = "s1interval_bindings",
+    srcs = ["s1interval_bindings.cc"],
+    copts = ["-DNDEBUG"],
+    deps = [
+        "//:s2",
+    ],
+)
+
 pybind_library(
     name = "s2point_bindings",
     srcs = ["s2point_bindings.cc"],
+    copts = ["-DNDEBUG"],
     deps = [
         "//:s2",
     ],
@@ -42,6 +54,12 @@ pybind_library(
 # Python Tests
 # ========================================
 
+py_test(
+    name = "s1interval_test",
+    srcs = ["s1interval_test.py"],
+    deps = [":s2geometry_pybind"],
+)
+
 py_test(
     name = "s2point_test",
     srcs = ["s2point_test.py"],

src/python/README.md

@@ -13,19 +13,9 @@ The S2 Geometry library is transitioning from SWIG-based bindings to pybind11-ba
 
 Once the pybind11 bindings are feature-complete and stable, the SWIG bindings will be deprecated and the pybind11 package will be renamed to `s2geometry` to become the primary Python API.
 
-## Directory Structure
+## User Guide
 
-```
-python/
-├── module.cc                     # Binding module entry point
-├── s2point_bindings.cc           # Bindings for S2Point (add more *_bindings.cc as needed)
-├── s2geometry_pybind/            # Dir for Python package
-│   └── __init__.py               # Package initialization
-├── s2point_test.py               # Tests for S2Point (add more *_test.py as needed)
-└── BUILD.bazel                   # Build rules for bindings, library, and tests
-```
-
-## Usage Example
+### Usage Example
 
 ```python
 import s2geometry_pybind as s2
@@ -36,8 +26,64 @@ sum_point = p1 + p2
 print(sum_point)
 ```
 
+### Interface Notes
+
+The Python bindings follow the C++ API closely but with Pythonic conventions:
+
+**Naming Conventions:**
+- **Modules** core classes exist within the top-level module; we intend to define submodules for utility classes.
+- **Class names** remain unchanged (e.g., `S2Point`, `S1Angle`, `R1Interval`)
+- **Method names** are converted to snake_case (converted from UpperCamelCase C++ function names)
+
+**Properties vs. Methods:**
+- **Simple coordinate accessors** are properties: `point.x`, `point.y`, `interval.lo`, `interval.hi`
+- **Some properties are mutable**: if the C++ class has a trivial set_foo method for the propertiy, then the Python property is mutable (otherwise it is a read-only property).
+- **Conversions and computations** are defined as method, not properties: `angle.radians()`, `angle.degrees()`, `interval.get_length()`
+
+**Invalid/Unnormalized Values:**
+- Some constructors and accept invalid values or unormalized values.
+- Examples: 
+  - `S1Interval(0.0, 4.0)` with `4.0 > π` creates interval where `is_valid()` is `False`
+  - `S2Point(3.0, 4.0, 0.0)` creates an unnormalized point outside of the unit sphere; use `normalize()` to normalize.
+- In **C++** invalid values will typically trigger (`ABSL_DCHECK`) in when compiled with debug options.
+- In **Python bindings** debug assertions (`ABSL_DCHECK`) are disabled, matching the production optimized C++ behavior.
+
+**Type Conversions:**
+- Python floats map to C++ `double`
+- Functions that accept angles as `double` expect values in **radians** (same as C++ interface)
+
+**Operators:**
+- Standard Python operators work as expected: `+`, `-`, `*`, `==`, `!=`, `<`, `>` (for C++ classes that implement those operators)
+
+**String Representations:**
+- `repr()` outputs developer-centric representations: `S1Angle.from_degrees(45.0)`
+- `str()` outputs simpler human-readable representations (e.g. `45.0 degrees`)
+
+**Vector Inheritance:**
+- In C++, various geometry classes inherit from or expose vector types (e.g., `S2Point` inherits from `Vector3_d`, `R2Point` is a type alias for `Vector2_d`, `R1Interval` returns bounds as `Vector2_d`)
+- The Python bindings **do not expose** this inheritance hierarchy; it is treated as an implementation detail
+- Instead, classes that inherit from a vector expose key functions from the `BasicVector` interface (e.g., `norm()`, `dot_prod()`, `cross_prod()`)
+- C++ functions that accept or return a vector object use a Python tuple (of length matching the vector dimension)
+- Array indexing operators (e.g., `point[0]`) are **not supported**.
+
+**Serialization:**
+- The C++ Encoder/Decoder serialization functions are **not currently bound**
+- These may be added in the future if there is a need for binary serialization
+
 ## Development
 
+### Directory Structure
+
+```
+python/
+├── module.cc                     # Binding module entry point
+├── s2point_bindings.cc           # Bindings for S2Point (add more *_bindings.cc as needed)
+├── s2geometry_pybind/            # Dir for Python package
+│   └── __init__.py               # Package initialization
+├── s2point_test.py               # Tests for S2Point (add more *_test.py as needed)
+└── BUILD.bazel                   # Build rules for bindings, library, and tests
+```
+
 ### Building with Bazel (pybind11 bindings)
 
 Bazel can be used for development and testing of the new pybind11-based bindings.
@@ -82,4 +128,18 @@ To add bindings for a new class:
 1. Create `<classname>_bindings.cc` with pybind11 bindings
 2. Update `BUILD.bazel` to add a new `pybind_library` target
 3. Update `module.cc` to call your binding function
-4. Create tests in `<classname>_test.py`
+4. Create tests in `<classname>_test.py`
+
+### Binding File Organization
+
+Use the following sections to organize the binding files and tests:
+
+1. **Constructors** - Default constructors and constructors with parameters
+2. **Factory methods** - Static factory methods (e.g., `from_degrees`, `from_radians`, `zero`, `invalid`)
+3. **Properties** - Mutable and read-only properties (e.g., coordinate accessors like `x`, `y`, `lo`, `hi`)
+4. **Predicates** - Simple boolean state checks (e.g., `is_empty`, `is_valid`, `is_full`)
+5. **Geometric operations** - All other methods including conversions, computations, containment checks, set operations, normalization, and distance calculations
+6. **Vector operations** - Methods from the Vector base class (e.g., `norm`, `norm2`, `normalize`, `dot_prod`, `cross_prod`, `angle`). Only applicable to classes that inherit from `util/math/vector.h`
+7. **Operators** - Operator overloads (e.g., `==`, `+`, `*`, comparison operators)
+8. **String representation** - `__repr__`, `__str__`, and string conversion methods like `to_string_in_degrees`
+9. **Module-level functions** - Standalone functions (e.g., trigonometric functions for S1Angle)

src/python/module.cc

@@ -3,9 +3,13 @@
 namespace py = pybind11;
 
 // Forward declarations for binding functions
+void bind_s1interval(py::module& m);
 void bind_s2point(py::module& m);
 
 PYBIND11_MODULE(s2geometry_bindings, m) {
   m.doc() = "S2 Geometry Python bindings using pybind11";
+  
+  // Bind core geometry classes in dependency order
+  bind_s1interval(m);
   bind_s2point(m);
 }

src/python/s1interval_bindings.cc

@@ -0,0 +1,96 @@
+#include <pybind11/pybind11.h>
+#include <pybind11/operators.h>
+
+#include "s2/s1interval.h"
+
+namespace py = pybind11;
+
+void bind_s1interval(py::module& m) {
+  py::class_<S1Interval>(m, "S1Interval")
+      // Constructors
+      .def(py::init<>(), "Default constructor (empty interval)")
+      .def(py::init<double, double>(),
+           py::arg("lo"), py::arg("hi"),
+           "Construct interval from lo and hi bounds (in radians)")
+
+      // Static factory methods
+      .def_static("empty", &S1Interval::Empty, "Return an empty interval")
+      .def_static("full", &S1Interval::Full, "Return a full interval")
+      .def_static("from_point", &S1Interval::FromPoint, py::arg("p"),
+                  "Construct interval containing a single point")
+      .def_static("from_point_pair", &S1Interval::FromPointPair,
+                  py::arg("p1"), py::arg("p2"),
+                  "Construct minimal interval containing two points")
+
+      // Properties
+      .def_property("lo", &S1Interval::lo, &S1Interval::set_lo, "Lower bound")
+      .def_property("hi", &S1Interval::hi, &S1Interval::set_hi, "Upper bound")
+      .def("bounds", [](const S1Interval& self) {
+        return py::make_tuple(self.lo(), self.hi());
+      }, "Return bounds as a tuple (lo, hi)")
+
+      // Predicates
+      .def("is_valid", &S1Interval::is_valid, "Check if interval is valid")
+      .def("is_full", &S1Interval::is_full, "Check if interval is full")
+      .def("is_empty", &S1Interval::is_empty, "Check if interval is empty")
+      .def("is_inverted", &S1Interval::is_inverted,
+           "Check if interval is inverted (lo > hi)")
+
+      // Geometric operations
+      .def("get_center", &S1Interval::GetCenter, "Return center of interval")
+      .def("get_length", &S1Interval::GetLength, "Return length of interval")
+      .def("get_complement_center", &S1Interval::GetComplementCenter,
+           "Return center of complement")
+      .def("contains", py::overload_cast<double>(&S1Interval::Contains, py::const_),
+           py::arg("p"), "Check if interval contains a point")
+      .def("interior_contains", py::overload_cast<double>(
+               &S1Interval::InteriorContains, py::const_),
+           py::arg("p"), "Check if interval's interior contains a point")
+      .def("contains", py::overload_cast<const S1Interval&>(
+               &S1Interval::Contains, py::const_),
+           py::arg("other"), "Check if interval contains another interval")
+      .def("interior_contains", py::overload_cast<const S1Interval&>(
+               &S1Interval::InteriorContains, py::const_),
+           py::arg("other"),
+           "Check if interval's interior contains another interval")
+      .def("intersects", &S1Interval::Intersects, py::arg("other"),
+           "Check if interval intersects another")
+      .def("interior_intersects", &S1Interval::InteriorIntersects,
+           py::arg("other"),
+           "Check if interval's interior intersects another")
+      .def("add_point", &S1Interval::AddPoint, py::arg("p"),
+           "Expand interval to include a point")
+      .def("project", &S1Interval::Project, py::arg("p"),
+           "Return closest point in interval")
+      .def("expanded", &S1Interval::Expanded, py::arg("margin"),
+           "Return expanded interval")
+      .def("union", &S1Interval::Union, py::arg("other"),
+           "Return union with another interval")
+      .def("intersection", &S1Interval::Intersection, py::arg("other"),
+           "Return intersection with another interval")
+      .def("complement", &S1Interval::Complement,
+           "Return complement of this interval")
+      .def("get_directed_hausdorff_distance", 
+           &S1Interval::GetDirectedHausdorffDistance,
+           py::arg("other"),
+           "Return directed Hausdorff distance to another interval")
+      .def("approx_equals", &S1Interval::ApproxEquals,
+           py::arg("other"), py::arg("max_error") = 1e-15,
+           "Check if approximately equal")
+
+      // Operators
+      .def(py::self == py::self, "Check equality")
+      .def(py::self != py::self, "Check inequality")
+
+      // String representation
+      .def("__repr__", [](const S1Interval& i) {
+        return "S1Interval(" + std::to_string(i.lo()) + ", " +
+               std::to_string(i.hi()) + ")";
+      })
+      .def("__str__", [](const S1Interval& i) {
+        if (i.is_empty()) return std::string("[∅]");
+        if (i.is_full()) return std::string("[0, 2π)");
+        return "[" + std::to_string(i.lo()) + ", " +
+               std::to_string(i.hi()) + "]";
+      });
+}