geodetic 0.8.0 → 0.8.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 542167ec9e7b27122d31d5287f967481dc9d0d4b293eaaaa349ca4203e2eb302
-  data.tar.gz: f544332a931f775df18ce4e0d2ed78e4d2619bbb946df6d287c8bc3a798d6c9f
+  metadata.gz: e747e334297726a887a07b078e0419bc232dd00d90823007bc8fcc96bb8b6fce
+  data.tar.gz: 87f53111a3ca2f2d5e5e126f780c1e756f98c415d1a10c66bad8595fc9049940
 SHA512:
-  metadata.gz: cca8fc5c8b38722ab95fecfeea576104c180352a9af854171858702d23a240368bef870b831c463601f06f6f04d76671aa8a5254edfc37880b3acef1aced476a
-  data.tar.gz: 29f289c88b14fcbe64091256d61afaa1752a4f405a5a3f88e55b966c7fbc50076c6db6a5e88bbe4f1e4840f3a424c88e37daf167acdca64b1872d81f8a2dcc01
+  metadata.gz: c384201adbfeb713cd67d81f3dda4642d0e9efab8b3026cf6fe88f6de869728890ca60e5f9591c12c9d6b034d9c5d9f74aae77a796a327674c129f806466b1d2
+  data.tar.gz: 1e8b73525875288901086e755ce87cfe3f2d257ddfe234f55d6eca0b680b0841c8205e05d77f91550ca978618d79c8bf3ad9ce41740b87c92585ea306726ea36

data/README.md

@@ -13,7 +13,7 @@
 <td width="50%" valign="top">
 <strong>Key Features</strong><br>
 
-- <strong>18 Coordinate Systems</strong> - LLA, ECEF, UTM, ENU, NED, MGRS, USNG, Web Mercator, UPS, State Plane, BNG, GH36, GH, HAM, OLC, GEOREF, GARS, H3<br>
+- <strong>19 Coordinate Systems</strong> - LLA, ECEF, UTM, ENU, NED, MGRS, USNG, Web Mercator, UPS, State Plane, BNG, GH36, GH, HAM, OLC, GEOREF, GARS, H3, S2<br>
 - <strong>Full Bidirectional Conversions</strong> - Every system converts to and from every other system<br>
 - <strong>Distance Calculations</strong> - Vincenty great-circle and straight-line with unit tracking<br>
 - <strong>Bearing Calculations</strong> - Forward azimuth, back azimuth, compass directions, elevation angles<br>
@@ -36,7 +36,7 @@
 </tr>
 </table>
 
-<p>Geodetic enables precise conversion between geodetic coordinate systems in Ruby. All 18 coordinate systems support complete bidirectional conversions with high precision. Review the <a href="https://madbomber.github.io/geodetic/">full documentation website</a> and explore the <a href="examples/">runnable examples</a>.</p>
+<p>Geodetic enables precise conversion between geodetic coordinate systems in Ruby. All 19 coordinate systems support complete bidirectional conversions with high precision. Review the <a href="https://madbomber.github.io/geodetic/">full documentation website</a> and explore the <a href="examples/">runnable examples</a>.</p>
 
 ## Installation
 
@@ -86,6 +86,24 @@ Set `GEODETIC_GEOS_DISABLE=1` to force pure Ruby for all operations, even when G
 Geodetic::Geos.available?  # => true when libgeos_c is found and not disabled
 ```
 
+### Optional: S2 Spherical Geometry Index
+
+The S2 coordinate system requires Google's [S2 Geometry library](https://github.com/google/s2geometry) installed on your system. S2 projects a cube onto the sphere and subdivides it into quadrilateral cells via a Hilbert space-filling curve, providing very low distortion (~0.56%) across the entire Earth surface. Cell IDs are 64-bit integers that enable efficient spatial database queries on standard B-tree indexes.
+
+```bash
+# macOS
+brew install s2geometry
+
+# Linux (build from source)
+# See https://github.com/google/s2geometry
+```
+
+You can set the `LIBS2_PATH` environment variable to point to a custom `libs2` location. See [S2 documentation](docs/coordinate-systems/s2.md) for detailed API reference and [example 15](examples/15_s2_geometry.rb) for a comprehensive demo.
+
+```ruby
+Geodetic::Coordinate::S2.available?  # => true when libs2 is found
+```
+
 ## Usage
 
 ### Basic Coordinate Creation
@@ -132,7 +150,7 @@ Geodetic::Coordinate.systems
 # Get short names
 Geodetic::Coordinate.systems.map { |c| c.name.split('::').last }
 # => ["LLA", "ECEF", "UTM", "ENU", "NED", "MGRS", "USNG", "WebMercator",
-#     "UPS", "StatePlane", "BNG", "GH36", "GH", "HAM", "OLC", "GEOREF", "GARS", "H3"]
+#     "UPS", "StatePlane", "BNG", "GH36", "GH", "HAM", "OLC", "GEOREF", "GARS", "H3", "S2"]
 ```
 
 ### Coordinate Conversions
@@ -546,6 +564,51 @@ olc.precision              # => 10
 olc.precision_in_meters    # => { lat: 13.9, lng: 13.9 }
 ```
 
+### S2 Spherical Geometry Index
+
+Google's hierarchical spatial index using a cube-on-sphere projection with Hilbert curve ordering. Cell IDs are 64-bit integers displayed as hex tokens. See [S2 documentation](docs/coordinate-systems/s2.md) for the full API.
+
+```ruby
+# From a token string or integer
+s2 = Coordinate::S2.new("54906ab14")
+s2 = Coordinate::S2.new(6093487605347778560)
+
+# From any coordinate
+s2 = Coordinate::S2.new(lla)
+s2 = lla.to_s2(precision: 20)     # level 20
+
+# Decode back to LLA
+lla = s2.to_lla
+
+# Properties
+s2.level               # => 15
+s2.face                # => 2 (cube face 0-5)
+s2.cell_id             # => 6093487605347778560 (for database storage)
+s2.to_s                # => "54906ab14" (token for display)
+
+# Hierarchy
+s2.parent(10)          # => S2 at level 10
+s2.children            # => [S2, S2, S2, S2] at level 16
+
+# Neighbors (4 edge-adjacent cells)
+s2.neighbors           # => [S2, S2, S2, S2]
+
+# Containment
+parent.contains?(child)   # => true
+parent.intersects?(child) # => true
+
+# Cell area (exact spherical surface area)
+s2.cell_area           # => 77544.2 (square meters)
+
+# Cell boundary as polygon
+polygon = s2.to_area   # => Areas::Polygon with 4 vertices
+polygon.includes?(s2.to_lla)  # => true
+
+# Database range scans (spatial queries on B-tree indexes)
+s2.range_min           # => start of cell ID range
+s2.range_max           # => end of cell ID range
+```
+
 ### Geographic Areas
 
 ```ruby
@@ -896,6 +959,8 @@ The [`examples/`](examples/) directory contains runnable demo scripts showing pr
 | [`11_wkb_serialization.rb`](examples/11_wkb_serialization.rb) | WKB serialization: `to_wkb`/`to_wkb_hex` on all geometry types, EWKB/SRID, Z-dimension, parsing, roundtrip, and binary/hex file I/O |
 | [`12_geos_benchmark.rb`](examples/12_geos_benchmark.rb) | GEOS performance benchmark: polygon validation, point-in-polygon, path intersection, PreparedGeometry batch containment, and GEOS-only boolean operations |
 | [`13_geos_operations.rb`](examples/13_geos_operations.rb) | GEOS-only operations: boolean overlay (intersection, difference, symmetric difference, union), buffering, convex hull, simplification, validity checking, geometry repair, planar measurements, nearest points, PreparedGeometry, and operation chaining |
+| [`14_geos_map_rendering.rb`](examples/14_geos_map_rendering.rb) | GEOS map rendering: visualizes 8 GEOS operation categories on a single raster map with distinct colors and an embedded legend |
+| [`15_s2_geometry.rb`](examples/15_s2_geometry.rb) | S2 Geometry: construction, round-trip conversion, cell hierarchy (parent/children), edge neighbors, containment/intersection, cell area calculations, cell polygons, database range scans, cross-hash conversions, distance/bearing, arithmetic, serialization (WKT/WKB/GeoJSON), six cube faces, and performance benchmarks |
 
 Run any example with:
 

data/docs/coordinate-systems/index.md

@@ -1,6 +1,6 @@
 # Coordinate Systems Overview
 
-The Geodetic gem supports 18 coordinate systems organized into six categories. All coordinate classes live under `Geodetic::Coordinate`.
+The Geodetic gem supports 19 coordinate systems organized into six categories. All coordinate classes live under `Geodetic::Coordinate`.
 
 ## Global Systems
 
@@ -47,6 +47,7 @@ The Geodetic gem supports 18 coordinate systems organized into six categories. A
 | [**GEOREF**](georef.md) | `Geodetic::Coordinate::GEOREF` | World Geographic Reference System. A geocode system used in aviation and military applications that encodes positions using letter tiles (15° grid), letter degree subdivisions, and numeric minute pairs. Uses a 24-letter alphabet (A-Z excluding I and O). Supports variable precision from 15° tiles (2 chars) down to 0.01-minute resolution (12 chars). Default precision is 8 characters (1-minute resolution). |
 | [**GARS**](gars.md) | `Geodetic::Coordinate::GARS` | Global Area Reference System. An NGA standard that divides the world into 30-minute cells identified by a 3-digit longitude band (001-720) and 2-letter latitude band. Cells are subdivided into 15-minute quadrants (1-4) and 5-minute keypads (1-9, telephone layout). Variable precision: 5 chars (30'), 6 chars (15'), 7 chars (5'). Default precision is 7 characters. |
 | [**H3**](h3.md) | `Geodetic::Coordinate::H3` | H3 Hexagonal Hierarchical Index. Uber's spatial indexing system that divides the globe into hexagonal cells (and 12 pentagons) at 16 resolution levels (0-15). Each cell is a 64-bit integer displayed as a hex string. Unlike the rectangular spatial hashes, `to_area` returns an `Areas::Polygon` with 6 vertices (5 for pentagons) and `neighbors` returns an Array of 6 cells. **Requires `libh3` installed** (`brew install h3` on macOS). |
+| [**S2**](s2.md) | `Geodetic::Coordinate::S2` | S2 Spherical Geometry Index. Google's hierarchical spatial indexing system that projects a cube onto the unit sphere, subdividing into quadrilateral cells via a Hilbert space-filling curve. 31 levels (0-30) with 64-bit cell IDs displayed as hex tokens. Cells are geodesic quadrilaterals with very low distortion (~0.56%). `to_area` returns an `Areas::Polygon` with 4 vertices. `neighbors` returns an Array of 4 edge cells. Cell IDs enable efficient database range scans on standard B-tree indexes. **Requires `libs2` installed** (`brew install s2geometry` on macOS). |
 
 ## Regional Systems
 
@@ -61,26 +62,27 @@ The Geodetic gem supports 18 coordinate systems organized into six categories. A
 
 Every coordinate system can convert to every other coordinate system. The table below confirms full interoperability:
 
-| From \ To | LLA | ECEF | UTM | ENU | NED | MGRS | USNG | WebMercator | UPS | StatePlane | BNG | GH36 | GH | HAM | OLC | GEOREF | GARS | H3 |
-|-----------|-----|------|-----|-----|-----|------|------|-------------|-----|------------|-----|------|----|----|-----|--------|------|-----|
-| **LLA**        | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
-| **ECEF**       | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
-| **UTM**        | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
-| **ENU**        | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
-| **NED**        | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
-| **MGRS**       | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
-| **USNG**       | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
-| **WebMercator**| Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
-| **UPS**        | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y |
-| **StatePlane** | Y | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y |
-| **BNG**        | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y |
-| **GH36**       | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y |
-| **GH**         | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y | Y | Y | Y | Y |
-| **HAM**        | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y | Y | Y | Y |
-| **OLC**        | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y | Y | Y |
-| **GEOREF**     | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y | Y |
-| **GARS**       | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y |
-| **H3**         | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- |
+| From \ To | LLA | ECEF | UTM | ENU | NED | MGRS | USNG | WebMercator | UPS | StatePlane | BNG | GH36 | GH | HAM | OLC | GEOREF | GARS | H3 | S2 |
+|-----------|-----|------|-----|-----|-----|------|------|-------------|-----|------------|-----|------|----|----|-----|--------|------|-----|-----|
+| **LLA**        | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **ECEF**       | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **UTM**        | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **ENU**        | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **NED**        | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **MGRS**       | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **USNG**       | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **WebMercator**| Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **UPS**        | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **StatePlane** | Y | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y | Y |
+| **BNG**        | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y | Y |
+| **GH36**       | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | --  | Y | Y | Y | Y | Y | Y | Y |
+| **GH**         | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y | Y | Y | Y | Y | Y |
+| **HAM**        | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y | Y | Y | Y | Y |
+| **OLC**        | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y | Y | Y | Y |
+| **GEOREF**     | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y | Y | Y |
+| **GARS**       | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y | Y |
+| **H3**         | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- | Y |
+| **S2**         | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -- |
 
 ## Universal Distance and Bearing Calculations
 
@@ -100,6 +102,6 @@ Conversions typically route through **LLA** or **ECEF** as intermediate steps:
 - **ECEF** is the intermediate for local tangent plane systems (ENU, NED), since the rotation from global Cartesian to local frames is straightforward in ECEF.
 - **ENU and NED** convert between each other directly by reordering axes and inverting the vertical component.
 - **MGRS and USNG** route through UTM, which in turn routes through LLA.
-- **WebMercator, UPS, BNG, StatePlane, GH36, GH, HAM, OLC, GEOREF, GARS, and H3** all convert through LLA.
+- **WebMercator, UPS, BNG, StatePlane, GH36, GH, HAM, OLC, GEOREF, GARS, H3, and S2** all convert through LLA.
 
 For example, converting from BNG to NED follows the chain: `BNG -> LLA -> ECEF -> ENU -> NED`. The gem handles this automatically when you call a conversion method.

data/docs/coordinate-systems/s2.md

@@ -0,0 +1,451 @@
+# Geodetic::Coordinate::S2
+
+## S2 Spherical Geometry Index
+
+S2 is Google's hierarchical geospatial indexing system. It projects a cube onto the unit sphere, then recursively subdivides each of the six cube faces into quadrilateral cells using a Hilbert space-filling curve. Each cell is identified by a 64-bit integer called a **cell ID**, typically displayed as a **token** — a hex string with trailing zeros stripped.
+
+The name comes from the mathematical notation S² for the unit sphere.
+
+**S2 requires the `libs2` C++ library** installed on your system. Without it, all other coordinate systems work normally; S2 operations raise a clear error message with installation instructions.
+
+### Prerequisites
+
+```bash
+# macOS (Homebrew)
+brew install s2geometry
+
+# Linux (build from source)
+git clone https://github.com/google/s2geometry.git
+cd s2geometry
+cmake -B build -DCMAKE_INSTALL_PREFIX=/usr/local
+cmake --build build
+sudo cmake --install build
+```
+
+You can also set the `LIBS2_PATH` environment variable to specify a custom library path:
+
+```bash
+export LIBS2_PATH=/path/to/libs2.dylib
+```
+
+### Key Differences from Other Spatial Hashes
+
+| Feature | GH/OLC/GARS/GEOREF/HAM | H3 | S2 |
+|---------|------------------------|-----|-----|
+| Cell shape | Rectangle | Hexagon (6 vertices) | Quadrilateral (4 vertices) |
+| `to_area` returns | `Areas::BoundingBox` | `Areas::Polygon` (6 verts) | `Areas::Polygon` (4 verts) |
+| `neighbors` returns | Hash with 8 cardinal keys | Array of 6 cells | Array of 4 edge cells |
+| Code format | String | 64-bit integer (hex) | 64-bit integer (hex token) |
+| Hierarchy | String prefix | Parent/child by resolution | Parent/child by level (quadtree) |
+| Levels | String length | 0-15 | 0-30 |
+| Projection | Rectangular lat/lng | Icosahedron | Cube-on-sphere |
+| Distortion | High at poles | Low (~1.2x) | Very low (~0.56%) |
+| Spatial ordering | Z-order (GH) / none | None guaranteed | Hilbert curve (locality) |
+| Dependency | None (pure Ruby) | `libh3` (C) | `libs2` (C++) |
+
+S2 is a **2D coordinate system** (no altitude). Conversions to/from other systems go through LLA as the intermediary. Each token represents a quadrilateral cell; the coordinate's point value is the cell's centroid.
+
+### Cell ID vs Token
+
+A cell ID and a token represent the same cell in two formats:
+
+- **cell_id** — the raw 64-bit unsigned integer. Use this for database storage and range queries. Standard B-tree indexes on a `BIGINT` column give you spatial queries for free.
+
+- **token** — the cell_id printed as hex with trailing zeros stripped. Use this for display, logging, and human-readable interchange. Shorter tokens represent coarser (larger) cells.
+
+```ruby
+cell = S2.new(seattle, precision: 15)
+cell.cell_id  # => 6093487605347778560
+cell.to_s     # => "54906ab14"
+
+# Equivalence: token is just compact hex of cell_id
+"54906ab14".ljust(16, '0').to_i(16)  # => 6093487605347778560
+```
+
+Tokens naturally reveal the hierarchy — a parent's token is always a prefix of its descendants:
+
+```
+Level  0: "5"                 (face 2)
+Level  5: "5494"
+Level 10: "54906b"
+Level 15: "54906ab14"
+Level 20: "54906ab12f1"
+Level 30: "54906ab12f10f899"
+```
+
+For **database applications**, store the cell_id as a `BIGINT`. Spatial containment queries become range scans:
+
+```sql
+-- Find all points inside a level-12 cell
+SELECT * FROM locations
+WHERE s2_cell_id BETWEEN :range_min AND :range_max
+```
+
+The Hilbert curve ordering guarantees that spatially nearby cells have numerically nearby cell_ids, so these range scans are efficient on standard B-tree indexes — no spatial index extension required.
+
+## Constructor
+
+```ruby
+# From a token string
+coord = Geodetic::Coordinate::S2.new("54906ab14")
+
+# From a token with 0x prefix
+coord = Geodetic::Coordinate::S2.new("0x54906ab14")
+
+# From a 64-bit cell ID integer
+coord = Geodetic::Coordinate::S2.new(6093487605347778560)
+
+# From any coordinate (converts via LLA)
+coord = Geodetic::Coordinate::S2.new(lla_coord)
+coord = Geodetic::Coordinate::S2.new(utm_coord, precision: 20)
+```
+
+| Parameter   | Type                    | Default | Description                              |
+|-------------|-------------------------|---------|------------------------------------------|
+| `source`    | String, Integer, or Coord | --    | An S2 token, cell ID integer, or coordinate |
+| `precision` | Integer                 | 15      | S2 cell level (0-30)                     |
+
+Raises `ArgumentError` if the source string is empty, contains invalid hex characters, or does not produce a valid S2 cell ID. String input is case-insensitive (normalized to lowercase). The `0x` prefix is stripped automatically.
+
+## Attributes
+
+| Attribute | Type    | Access    | Description                       |
+|-----------|---------|-----------|-----------------------------------|
+| `code`    | String  | read-only | The token string representation   |
+| `cell_id` | Integer | read-only | The 64-bit S2 cell ID             |
+
+S2 is **immutable** — there are no setter methods.
+
+## Levels
+
+S2 uses "level" (0-30) for its hierarchy. Higher level means smaller cells. Each level subdivides cells by 4 (quadtree), so area decreases by roughly 4x per level.
+
+| Level | Approximate Cell Area | Approximate Edge Length |
+|-------|----------------------|------------------------|
+| 0     | 85,201,316 km²       | ~9,200 km (face cell)  |
+| 1     | 21,300,329 km²       | ~4,600 km              |
+| 5     | 79,002 km²           | ~281 km                |
+| 10    | 79.4 km²             | ~8.9 km                |
+| 12    | 5.0 km²              | ~2.2 km                |
+| 15    | 77,544 m² (default)  | ~278 m                 |
+| 18    | 1,212 m²             | ~35 m                  |
+| 20    | 75.7 m²              | ~8.7 m                 |
+| 24    | 0.30 m² (2,958 cm²)  | ~54 cm                 |
+| 28    | 11.55 cm²            | ~3.4 cm                |
+| 30    | 0.72 cm²             | ~0.85 cm               |
+
+```ruby
+coord.level                  # => 15 (alias: coord.precision)
+coord.cell_area              # => 77544.2 (square meters)
+coord.precision_in_meters    # => { lat: ~278, lng: ~278, area_m2: ~77544 }
+S2.average_cell_area(15)     # => 79349.9 (average across all level-15 cells)
+```
+
+## The Six Cube Faces
+
+S2 projects a cube onto the sphere, giving 6 face cells at level 0:
+
+| Face | Direction   | Center         | Token |
+|------|-------------|----------------|-------|
+| 0    | +X (front)  | (0°, 0°)       | `1`   |
+| 1    | +Y (right)  | (0°, 90°E)     | `3`   |
+| 2    | +Z (top)    | (90°N, 0°)     | `5`   |
+| 3    | -X (back)   | (0°, 180°)     | `7`   |
+| 4    | -Y (left)   | (0°, 90°W)     | `9`   |
+| 5    | -Z (bottom) | (90°S, 0°)     | `b`   |
+
+The cube-on-sphere projection limits distortion to approximately 0.56% across the entire Earth surface — far less than rectangular projections which distort heavily near the poles.
+
+```ruby
+coord.face        # => 2 (Seattle is on face 2, the +Z/north pole face)
+coord.face_cell?  # => false (only level-0 cells are face cells)
+```
+
+## Checking Availability
+
+```ruby
+Geodetic::Coordinate::S2.available?   # => true if libs2 is found
+```
+
+## Conversions
+
+All conversions chain through LLA. The datum parameter defaults to `Geodetic::WGS84`.
+
+### Instance Methods
+
+```ruby
+coord.to_lla                    # => LLA (centroid of the cell)
+coord.to_ecef
+coord.to_utm
+coord.to_enu(reference_lla)
+coord.to_ned(reference_lla)
+coord.to_mgrs
+coord.to_usng
+coord.to_web_mercator
+coord.to_ups
+coord.to_state_plane(zone_code)
+coord.to_bng
+coord.to_gh36
+coord.to_gh
+coord.to_ham
+coord.to_olc
+coord.to_georef
+coord.to_gars
+coord.to_h3                    # (requires libh3)
+```
+
+### Class Methods
+
+```ruby
+S2.from_lla(lla_coord)
+S2.from_ecef(ecef_coord)
+S2.from_utm(utm_coord)
+S2.from_web_mercator(wm_coord)
+S2.from_gh(gh_coord)
+S2.from_h3(h3_coord)
+# ... and all other coordinate systems
+```
+
+### LLA Convenience Methods
+
+```ruby
+lla = Geodetic::Coordinate::LLA.new(lat: 47.6062, lng: -122.3321)
+s2 = lla.to_s2                    # default level 15
+s2 = lla.to_s2(precision: 20)     # level 20
+
+lla = Geodetic::Coordinate::LLA.from_s2(s2)
+```
+
+## Serialization
+
+### `to_s(format = nil)`
+
+Returns the token string. Pass `:integer` to get the 64-bit cell ID.
+
+```ruby
+coord = S2.new("54906ab14")
+coord.to_s             # => "54906ab14"
+coord.to_s(:integer)   # => 6093487605347778560
+coord.cell_id          # => 6093487605347778560
+```
+
+### `to_a`
+
+Returns `[lat, lng]` of the cell centroid.
+
+```ruby
+coord.to_a    # => [47.605..., -122.334...]
+```
+
+### `from_string` / `from_array`
+
+```ruby
+S2.from_string("54906ab14")                  # from token
+S2.from_array([47.6062, -122.3321])          # from [lat, lng]
+```
+
+### WKT, WKB, GeoJSON
+
+S2 coordinates support all standard serialization formats:
+
+```ruby
+coord.to_wkt                        # => "POINT(-122.334371 47.605024)"
+coord.to_wkt(srid: 4326)           # => "SRID=4326;POINT(-122.334371 47.605024)"
+coord.to_wkb_hex                    # => "010100000014dbfb5466955ec0..."
+coord.to_geojson                    # => {"type" => "Point", "coordinates" => [...]}
+
+# Cell polygon serialization
+coord.to_area.to_wkt               # => "POLYGON((-122.33392 47.606536, ...))"
+coord.to_area.to_geojson           # => {"type" => "Polygon", ...}
+```
+
+## Cell Hierarchy
+
+S2 cells form a strict quadtree: each cell has exactly 4 children and 1 parent (except level-0 face cells which have no parent).
+
+### Parent
+
+```ruby
+coord = S2.new("54906ab14")        # level 15
+parent = coord.parent              # level 14 (one level up)
+parent = coord.parent(10)          # level 10 (5 levels up)
+parent = coord.parent(0)           # level 0 (face cell)
+```
+
+Raises `ArgumentError` if the target level is not coarser (lower number) than the current level.
+
+### Children
+
+```ruby
+coord = S2.new("54906ab14")        # level 15
+children = coord.children          # => [S2, S2, S2, S2] at level 16
+children.length                    # => 4
+```
+
+Raises `ArgumentError` on leaf cells (level 30).
+
+### Ancestry Traversal
+
+```ruby
+leaf = S2.new(seattle, precision: 30)
+[30, 20, 10, 0].each do |lvl|
+  ancestor = lvl == 30 ? leaf : leaf.parent(lvl)
+  puts "Level #{lvl}: #{ancestor.to_s}"
+end
+```
+
+## Neighbors
+
+Returns the 4 edge-adjacent cells as an Array. Unlike rectangular hashes (which return 8 directional neighbors), S2 cells are quadrilaterals with exactly 4 edges.
+
+```ruby
+coord = S2.new("54906ab14")
+neighbors = coord.neighbors
+# => [S2, S2, S2, S2]
+
+neighbors.length               # => 4
+neighbors.first.level          # => 15 (same level as source)
+```
+
+## Containment and Intersection
+
+S2 cells have strict hierarchical containment — a cell contains exactly its descendants and intersects exactly its ancestors and descendants.
+
+```ruby
+coarse = S2.new(seattle, precision: 10)
+fine   = S2.new(seattle, precision: 20)
+
+coarse.contains?(fine)       # => true
+fine.contains?(coarse)       # => false
+coarse.intersects?(fine)     # => true
+fine.intersects?(coarse)     # => true
+```
+
+## Database Range Scans
+
+Every S2 cell defines a contiguous range of cell IDs that covers all its descendants. This enables spatial queries as simple integer range scans.
+
+```ruby
+cell = S2.new(seattle, precision: 12)
+cell.range_min   # => 6093487531259592705
+cell.range_max   # => 6093487668698546175
+cell.cell_id     # => 6093487599767896064 (between min and max)
+```
+
+Any descendant cell's ID falls within `[range_min, range_max]`:
+
+```ruby
+child = S2.new(seattle, precision: 20)
+child.cell_id >= cell.range_min  # => true
+child.cell_id <= cell.range_max  # => true
+```
+
+## Cell Area
+
+S2 provides exact cell area calculations using the C++ library's spherical geometry.
+
+```ruby
+coord.cell_area              # => 77544.2 (square meters for level 15)
+S2.average_cell_area(15)     # => 79349.9 (global average for level 15)
+coord.precision_in_meters    # => { lat: 278.5, lng: 278.5, area_m2: 77544.2 }
+```
+
+Cell areas are computed as exact spherical surface area (steradians) multiplied by R², giving results in square meters.
+
+## Cell Polygon (to_area)
+
+The `to_area` method returns the quadrilateral cell boundary as an `Areas::Polygon` with 4 vertices.
+
+```ruby
+area = coord.to_area
+# => Geodetic::Areas::Polygon
+
+area.includes?(coord.to_lla)    # => true (centroid is inside the cell)
+area.boundary.length             # => 5 (4 vertices + closing point)
+```
+
+S2 cell boundaries are geodesics (great circle arcs), not straight lines in lat/lng space. The polygon approximation uses the 4 corner vertices connected by straight edges.
+
+## Leaf and Face Cells
+
+```ruby
+coord.leaf?        # => true if level == 30 (smallest possible cell, ~0.7 cm²)
+coord.face_cell?   # => true if level == 0 (one of 6 cube faces, ~85M km²)
+```
+
+## Equality
+
+Two S2 instances are equal if their token strings match exactly.
+
+```ruby
+S2.new("54906ab14") == S2.new("54906ab14")                       # => true
+S2.new("54906ab14") == S2.new(6093487605347778560)                # => true
+S2.new("54906ab14") == S2.new("54906ab1c")                       # => false
+```
+
+## `valid?`
+
+Returns `true` if the cell ID has valid structure (correct face bits, properly positioned sentinel bit).
+
+```ruby
+coord.valid?    # => true
+```
+
+## Universal Distance and Bearing Methods
+
+S2 supports all universal distance and bearing methods via the `DistanceMethods` and `BearingMethods` mixins:
+
+```ruby
+seattle = S2.new(Coordinate::LLA.new(lat: 47.6062, lng: -122.3321), precision: 15)
+nyc     = S2.new(Coordinate::LLA.new(lat: 40.7128, lng: -74.0060), precision: 15)
+
+seattle.distance_to(nyc)                # => Distance (~3,876 km)
+seattle.straight_line_distance_to(nyc)  # => Distance
+seattle.bearing_to(nyc)                 # => Bearing (~83°, roughly east)
+seattle.elevation_to(nyc)               # => Float (degrees)
+```
+
+## Geodetic Arithmetic
+
+S2 cells support the standard arithmetic operators:
+
+```ruby
+s2 = S2.new(seattle, precision: 15)
+v = Geodetic::Vector.new(distance: 10_000, bearing: 90)
+
+s2 * v          # => LLA (translated cell center)
+s2 + v          # => Segment (from center to destination)
+s2 + distance   # => Circle (centered on cell center)
+s2 + other_s2   # => Segment (between cell centers)
+```
+
+## Well-Known S2 Tokens
+
+| Location | Token (level 30) | Token (level 15) | Face |
+|----------|-----------------|-------------------|------|
+| Seattle  | `54906ab12f10f899` | `54906ab14` | 2 |
+| New York | `89c25a220cf80969` | `89c25a224` | 4 |
+| Tokyo    | `6018f25555544b7f` | `6018f254c` | 3 |
+| London   | `487604ce36748fa9` | `487604d04` | 2 |
+| Sydney   | `6b12ae3ff6290055` | `6b12ae3fc` | 3 |
+| Null Island (0°, 0°) | `1000000000000001` | `1000000000000004` | 0 |
+
+## Implementation Notes
+
+Geodetic uses Ruby's `fiddle` (part of the standard library) to call the S2 C++ library directly. Despite S2 being C++ (not C), the key functions are callable through their mangled symbol names. No gem dependency beyond `fiddle` is required. The S2 C++ library must be installed separately.
+
+**Functions called via Fiddle:**
+- `S2CellId::S2CellId(S2LatLng const&)` — encode lat/lng to cell ID
+- `S2CellId::ToFaceIJOrientation()` — decode cell ID to face/IJ coordinates
+- `S2CellId::GetEdgeNeighbors()` — 4 adjacent cells
+- `S2Cell::ExactArea()` — spherical surface area in steradians
+- `S2Cell::AverageArea(level)` — average area for a level
+
+**Pure Ruby operations** (no FFI overhead):
+- Cell level, face, parent, child — bit manipulation on the 64-bit cell ID
+- Token encode/decode — hex formatting with trailing zero stripping
+- Coordinate transforms — face/IJ → ST → UV → XYZ → lat/lng pipeline
+- Cell vertex computation — 4 corners via the coordinate pipeline
+- Containment/intersection — integer range comparisons
+- Range min/max — bit arithmetic for database scan ranges
+- Validity checks — sentinel bit position verification