visgl · ibgreen-openai · May 13, 2025 · May 13, 2025 · May 14, 2025 · May 14, 2025
diff --git a/docs/README.md b/docs/README.md
@@ -11,7 +11,7 @@ math.gl is **optimized for use with WebGL and WebGPU**, however it is not a GPU
 - **Core classes** - Basic vectors and matrices: **`@math.gl/types`**, **`@math.gl/core`**
 - **Geospatial projections** - Support for a variety of geospatial projections **`@math.gl/geospatial`**, **`@math.gl/geoid`**, **`@math.gl/proj4`**, **`@math.gl/web-mercator`**
 - **Geospatial utilities** - Cutting polygons and calculating sun position and direction **`@math.gl/polygon`**, **`@math.gl/sun`**
-- **Discrete Global Grids** - Standardized interfaces to a number of the major discrete global grids. **`@math.gl/dggs-geohash`**, **`@math.gl/dggs-quadkey`**, **`@math.gl/dggs-s2`**
+- **Discrete Global Grid Systems** - Pluggable decoders for a number the major discrete global grids. **`@math.gl/dggs`**
 - **3D math** - 3D primitives and culling: **`@math.gl/culling`**
 
 ## Modules
@@ -23,20 +23,15 @@ math.gl is a toolbox that offers a suite of composable modules.
 |                                   | **`@math.gl/types`**                 | Basic math type helpers (`NumericArray` etc) |
 | ![core](./images/core.png 'core') | **`@math.gl/core`**                  | Basic math classes (vectors, matrices, etc)  |
 
-| **Geospatial math libraries**                       | Module <span style={{width: 300}} /> | Description                                        |
-| --------------------------------------------------- | ------------------------------------ | -------------------------------------------------- |
-| ![geospatial](./images/geospatial.svg 'geospatial') | **`@math.gl/geospatial`**            | Ellipsoidal math for WGS84 coordinates.            |
-| ![geoid](./images/geoid.png 'geoid')                | **`@math.gl/geoid`**                 | Earth Gravity Model support .                      |
-|                                                     | **`@math.gl/polygon`**               | Polygon math, including geospatial cutting etc.    |
-|                                                     | **`@math.gl/proj4`**                 | Conversion between coordinate reference systems.   |
-|                                                     | **`@math.gl/sun`**                   | Solar position / direction from position and time. |
-|                                                     | **`@math.gl/web-mercator`**          | Supports 3D Web Mercator (spherical) projections.  |
-
-| **DGGS (Discrete global grid support) libraries** | Module <span style={{width: 300}} /> | Description                     |
-| ------------------------------------------------- | ------------------------------------ | ------------------------------- |
-| ![geohash](./images/dggs/geohash.png 'geohash')   | **`@math.gl/dggs-geohash`**          | Get geometry of GeoHash tokens. |
-| ![quadkey](./images/dggs/quadkey.png 'quadkey')   | **`@math.gl/dggs-quadkey`**          | Get geometry of QuadKey tokens  |
-| ![s2](./images/dggs/s2.png 's2')                  | **`@math.gl/dggs-s2`**               | Get geometry of S2 tokens.      |
+| **Geospatial math libraries**                       | Module <span style={{width: 300}} /> | Description                                         |
+| --------------------------------------------------- | ------------------------------------ | --------------------------------------------------- |
+| ![geospatial](./images/geospatial.svg 'geospatial') | **`@math.gl/geospatial`**            | Ellipsoidal math for WGS84 coordinates.             |
+| ![geoid](./images/geoid.png 'geoid')                | **`@math.gl/geoid`**                 | Earth Gravity Model support .                       |
+|                                                     | **`@math.gl/polygon`**               | Polygon math, including geospatial cutting etc.     |
+|                                                     | **`@math.gl/proj4`**                 | Conversion between coordinate reference systems.    |
+|                                                     | **`@math.gl/sun`**                   | Solar position / direction from position and time.  |
+|                                                     | **`@math.gl/web-mercator`**          | Supports 3D Web Mercator (spherical) projections.   |
+| ![DDGS](./images/dggs/s2.png 'dggs')                | **`@math.gl/dggs`**                  | Get geometry of Discrete Global Grid System tokens. |
 
 | **3D math libraries**                      | Module <span style={{width: 300}} /> | Description                                |
 | ------------------------------------------ | ------------------------------------ | ------------------------------------------ |

diff --git a/docs/developer-guide/geospatial/dggs.md b/docs/developer-guide/geospatial/dggs.md
@@ -2,27 +2,29 @@
 
 Discrete global grid systems are powerful tools that enables us to convert geospatial data into a common, easy-to-analyze form.
 
-## Why DGGS in math.gl
+## Why DGGS support in math.gl?
 
-Today there are multiple DGGS grid systems, and it is not unusual for an application to have to work with
-more than one DGGS. This can require working with a set of independent DGGS libraries with large API surfaces and subtly different API conventions, which can be taxing for implementors and maintainers.
+There is value in having access to a common set of minimal, pluggable and interchangeable DGGS libraries.
 
-We found that there is a value in having a common set of small, easy-to-use DGGS libraries that work with common API conventions.
+Today there are multiple advanced DGGS grid systems that offer different tradeoffs, and it is not unusual for an application to have to consume data encoded in one or more systems.
 
-## Goals
+This requires integrating a set of independent DGGS libraries following different API conventions and nomenclature. Such independent DGGS libraries tend to offer a large set of functions and can accordingly be large dependencies, and bundling complications (WASM etc) can add additional effort from implementors and maintainers.
+
+## Scope
 
 The DGGS support in math.gl is currently focused on decoding cell indexes or tokens into center points (lng/lat) or cell boundary polygons.
 
-Encoding (lng/lat to cell index) and advanced operations (child/neighbor calculation, polygon fills etc) are not currently included. Some basic encoding may be included in the future, however it is a goal to keep these libraries fairly small, and the intention is not to eventually fully duplicate large existing DGGS libraries.
+- Encoding (lng/lat to cell index) may be supported in a future version.
+- Advanced operations (child/neighbor calculation, polygon fills etc) are not currently included. Some features may be included in the future, however it is a goal to keep these libraries fairly small, and the intention is not to eventually fully duplicate large existing DGGS libraries.
 
 ## Supported Grid Systems
 
-| DGGS                                                | Module                  | Functionality                   |
-| --------------------------------------------------- | ----------------------- | ------------------------------- |
-| ![GeoHash](../../images/dggs/geohash.png 'GeoHash') | `@math.gl/dggs-geohash` | Get geometry of GeoHash tokens. |
-| ![QuadKey](../../images/dggs/quadkey.png 'QuadKey') | `@math.gl/dggs-quadkey` | Get geometry of QuadKey tokens  |
-| ![S2](../../images/dggs/s2.png 'S2')                | `@math.gl/dggs-s2`      | Get geometry of S2 tokens.      |
-| ![H3](../../images/dggs/h3.png 'H3')                | `h3-js` \*              | Get geometry of H3 tokens.      |
+| DGGS                                                | Module          | Functionality                   |
+| --------------------------------------------------- | --------------- | ------------------------------- |
+| ![GeoHash](../../images/dggs/geohash.png 'GeoHash') | `@math.gl/dggs` | Get geometry of GeoHash tokens. |
+| ![QuadKey](../../images/dggs/quadkey.png 'QuadKey') | `@math.gl/dggs` | Get geometry of QuadKey tokens  |
+| ![S2](../../images/dggs/s2.png 'S2')                | `@math.gl/dggs` | Get geometry of S2 tokens.      |
+| ![H3](../../images/dggs/h3.png 'H3')                | `h3-js` \*      | Get geometry of H3 tokens.      |
 
 Note that `h3-js` is not a `math.gl` library. For H3 it is recommended to work directly with the H3 JavaScript bindings.
 

diff --git a/docs/modules/dggs-geohash/README.md b/docs/modules/dggs-geohash/README.md
diff --git a/docs/modules/dggs-geohash/api-reference/geohash.md b/docs/modules/dggs-geohash/api-reference/geohash.md
diff --git a/docs/modules/dggs-quadkey/README.md b/docs/modules/dggs-quadkey/README.md
diff --git a/docs/modules/dggs-s2/README.md b/docs/modules/dggs-s2/README.md
diff --git a/docs/modules/dggs-s2/api-reference/s2.md b/docs/modules/dggs-s2/api-reference/s2.md
diff --git a/docs/modules/dggs/README.md b/docs/modules/dggs/README.md
@@ -0,0 +1,39 @@
+# Overview
+
+<p class="badges">
+  <img src="https://img.shields.io/badge/From-v4.0-blue.svg?style=flat-square" alt="From-v4.0" />
+</p>
+
+:::caution
+This module is still experimental. It may have issues and functionality may change in minor releases.
+:::
+
+`@math.gl/dggs` is a JavaScript library which provides lightweight support for working with Discrete Global Grid System (DGGS) indices.
+
+## Installation
+
+```bash
+npm install @math.gl/dggs
+```
+
+## Usage
+
+```js
+import {GeohashDecoder} from '@math.gl/dggs';
+const polygon = GeohashDecoder.getCellBoundaryPolygon(geohashId);
+```
+
+### S2 Cell Format
+
+S2 cells are identified by a 64&nbsp;bit index. The three most significant bits
+encode the cube face, followed by 60&nbsp;bits that encode the cell's position on
+the Hilbert curve. The least significant bit is always set and trailing zero
+bits indicate the level of the cell. When written in hexadecimal the trailing
+zeros are stripped; this representation is commonly referred to as the **S2
+token**.
+
+## Attribution
+
+The `S2Encoder` object is based on a subset of the s2-geometry module under ISC License (ISC)
+Copyright (c) 2012-2016, Jon Atkins github@jonatkins.com
+Copyright (c) 2016, AJ ONeal aj@daplie.com
diff --git a/docs/modules/dggs/api-reference/dggs-decoder.md b/docs/modules/dggs/api-reference/dggs-decoder.md
@@ -0,0 +1,27 @@
+# DGGSDecoder
+
+A common type is provided as a template for DGGS decoder objects.
+
+#### `name: string`
+
+The name of the DGGS that this decoder object implements.
+
+#### `getCellIndexFromToken(token: string): bigint`
+
+Decodes a token string into the 64 bit index.
+
+#### `getTokenFromCellIndex(index: bigint): string`
+
+Encodes the 64 bit index into a token string.
+
+#### `getCellLngLat(token: string): number[]`
+
+Returns the center `[lng, lat]` of the specified cell
+
+#### `getS2CellBoundaryPolygon(token: string): Float64Array`
+
+Returns the boundary as a nested array `[[lng0, lat0], ...]` for the specified cell
+
+#### `getS2CellBoundaryPolygonFlat(token: string): Float64Array`
+
+Returns the boundary as a flat array `[lng0, lat0, ...]` for the specified cell
diff --git a/docs/modules/dggs/api-reference/geohash-decoder.md b/docs/modules/dggs/api-reference/geohash-decoder.md
@@ -0,0 +1,20 @@
+### `GeohashDecoder`
+
+<p class="badges">
+  <img src="https://img.shields.io/badge/From-v4.0-blue.svg?style=flat-square" alt="From-v4.0" />
+</p>
+
+:::caution
+This module is still experimental. It may have issues and functionality may change in minor releases.
+:::
+
+> The GeoHash functions in math.gl are currently focused on **decoding** Geohash encoded data, not encoding it.
+
+## Functions
+
+Implements the functions in the [DGGSDecoder](/docs/modules/types/api-reference/dggs) type, e.g:
+
+- `getCellIndexFromToken(token: string): bigint` - Decodes a token string into the 64 bit index.
+- `getTokenFromCellIndex(index: bigint): string` - Encodes the 64 bit index into a token string.
+- `getCellLngLat(token: string): number[]` - Returns the center `[lng, lat]` of the cell
+- `getCellBoundaryPolygonFlat(token: string): Float64Array` - Returns the boundary as a flat array `[lng0, lat0, ...]` for the S2 cell
diff --git a/...les/dggs-quadkey/api-reference/quadkey.md → ...les/dggs/api-reference/quadkey-decoder.md b/...les/dggs-quadkey/api-reference/quadkey.md → ...les/dggs/api-reference/quadkey-decoder.md
diff --git a/docs/modules/dggs/api-reference/s2-decoder.md b/docs/modules/dggs/api-reference/s2-decoder.md
@@ -0,0 +1,40 @@
+# S2 API
+
+<p class="badges">
+  <img src="https://img.shields.io/badge/From-v4.0-blue.svg?style=flat-square" alt="From-v4.0" />
+</p>
+
+:::caution
+This module is still experimental. It may have issues and functionality may change in minor releases.
+:::
+
+## Overview
+
+S2 is a discrete global grid system built on the Hilbert curve.
+See [s2geometry.io](https://s2geometry.io/) for more information.
+
+> The S2 functions in math.gl are currently focused on **decoding** S2 encoded data, not encoding it.
+
+## API Notes
+
+The API provided by this module works with S2 token strings, as those are typically found in data files.
+
+S2 cells have multiple representations, and can be represented as:
+
+- S2 token strings (stringified versions of the indexes)
+- S2 indexes which are 64 bit numbers represented by JavaScript `bigint`
+
+The 64 bit index layout allocates 3 bits for the face id and 60 bits for
+the Hilbert curve position. The least significant bit is always set and
+trailing zero bits encode the level. When expressed as hexadecimal
+strings these trailing zeros are omitted; such a string is known as the
+S2 token. An empty cell is represented by the token `X`.
+
+### `S2Decoder`
+
+Implements the functions in the [DGGSDecoder](/docs/modules/types/api-reference/dggs) type, e.g:
+
+- `getCellIndexFromToken(token: string): bigint` - Decodes a token string into the 64 bit index.
+- `getTokenFromCellIndex(index: bigint): string` - Encodes the 64 bit index into a token string.
+- `getCellLngLat(token: string): number[]` - Returns the center `[lng, lat]` of the cell
+- `getCellBoundaryPolygonFlat(token: string): Float64Array` - Returns the boundary as a flat array `[lng0, lat0, ...]` for the S2 cell