docs: Update docs for 4.0 (#7)

README.md

@@ -23,8 +23,8 @@ In spite of its name, math.gl has no actual WebGL dependencies (e.g. it does not
 
 ## Attribution
 
-math.gl heavily inspired by, and includes code, documentation and ideas from some of the most proven open source JavaScript math libraries, the awesome [`gl-matrix`](http://glmatrix.net/) and the THREE.js math library. Those libraries encouraged reuse which enabled math.gl to be built, and naturally math.gl does the same!
+math.gl was inspired by, and includes code, documentation and ideas from some of the most proven open source JavaScript math libraries, including the awesome [`gl-matrix`](http://glmatrix.net/) and the THREE.js math library. The generous open source licenses of those libraries encouraged reuse which enabled math.gl to be built, and naturally math.gl does the same.
 
 ## License
 
-MIT license. The libraries that math.gl are built on are also all open source under permissive licenses.
+MIT license. Any code that math.gl has forked is also open source under permissive licenses.

dev-docs/design-notes.md

@@ -51,8 +51,6 @@ Some background:
 
 math.gl is a JavaScript math library primarily intended to support WebGL applications. It is a generic library but was developed as a companion for [luma.gl](http://uber.github.io/luma.gl/) and [deck.gl](http://uber.github.io/deck.gl/).
 
-math.gl contains a set of classes (Matrix4 etc) to complement the procedural interface of gl-matrix. It also imports a limited subset of the standard `gl-matrix` functions (to keep bundle size down), these can be used in parallel with the classes.
-
 ## Who is this for?
 
 JavaScript WebGL programmers who:

docs/README.md

@@ -1,25 +1,27 @@
 # Introduction
 
-Welcome to math.gl! math.gl is JavaScript (TypeScript) math library focused on **geospatial** and **3D** use cases. Designed as a composable, **modular toolbox**. math.gl provides a core module with classic vector and matrix classes, and a suite of optional modules implementing various aspects of geospatial and 3D math.
+Welcome to math.gl! 
 
-While math.gl is highly **optimized for use with the WebGL and WebGPU APIs**, it has no WebGL dependencies and is designed to be usable in any application.
+math.gl is TypeScript math library focused on **geospatial** and **3D** use cases. Designed as a composable, **modular toolbox**. math.gl provides a core module with the standard complement of vector and matrix classes, and a suite of optional modules implementing various aspects of geospatial and 3D math.
+
+math.gl is  **optimized for use with WebGL and WebGPU**, however it is not a GPU math library, meaning that it has no GPU dependencies and is designed to be usable in any application.
 
 ## Features
 
-- **3D math** - Basic vectors and matrices, as well as 3D primitives and culling: **`@math.gl/types`**, **`@math.gl/core`**, **`@math.gl/culling`**
+- **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`**
+- **3D math** - 3D primitives and culling: **`@math.gl/culling`**
 
 ## Modules
 
 math.gl is a toolbox that offers a suite of composable modules.
 
-| **Core math libraries**                    | Module <span style={{width: 300}} /> | Description                                  |
-| ------------------------------------------ | ------------------------------------ | -------------------------------------------- |
-|                                            | **`@math.gl/types`**                 | Basic math type helpers (`NumericArray` etc) |
-| ![core](./images/core.png 'core')          | **`@math.gl/core`**                  | 3D math classes (vectors, matrices, etc)     |
-| ![culling](./images/culling.png 'culling') | **`@math.gl/culling`**               | Bounding volumes and intersection testing.   |
+| **Core math libraries**           | Module <span style={{width: 300}} /> | Description                                  |
+| --------------------------------- | ------------------------------------ | -------------------------------------------- |
+|                                   | **`@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                                        |
 | --------------------------------------------------- | ------------------------------------ | -------------------------------------------------- |
@@ -32,10 +34,13 @@ math.gl is a toolbox that offers a suite of composable modules.
 
 | **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.      |
+| ![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.      |
+
+| **3D math libraries**                      | Module <span style={{width: 300}} /> | Description                                |
+| ------------------------------------------ | ------------------------------------ | ------------------------------------------ |
+| ![culling](./images/culling.png 'culling') | **`@math.gl/culling`**               | Bounding volumes and intersection testing. |
 
 <br/>
 In addition, math.gl provides a few deprecated legacy modules, to avoid breaking older applications.
@@ -53,16 +58,18 @@ math.gl is fully supported on:
 
 - Evergreen browsers: Recent versions of Chrome, Safari, Firefox, Edge etc.
 - Node.js: Active and Maintenance [LTS releases](https://nodejs.org/en/about/releases/)
-- IE11: Supported (with certain performance caveats) using math.gl's fully transpiled `es5` distribution and `@babel/polyfills`.
-
-Note that Internet Explorer < 10 will not work. If your application needs to support older browsers, an option could be to use [`gl-matrix`](http://glmatrix.net/) directly.
 
 ## History
 
-- The core classes were originally developed as part of luma.gl v4 to provide a basic 3D math library for the luma.gl and deck.gl frameworks.
-- math.gl was then broken out into its own repository to ensure it remained an independently usable set of 3D and Geospatial math modules.
-- parts of the Cesium math library were ported and published as independently usable math.gl modules (the geospatial and culling modules). This was a collaboration with the Cesium team around 3D Tiles support in loaders.gl,
-- Additional geospatial modules have gradually been added to support more advanced use cases for deck.gl.
+| Year  | Version | Description                                                                                                                                                            |
+| ----- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 2015  | N/A     | `@math.gl/core` classes were created as part of luma.gl v4, as a set of class wrappers for `gl-matrix` for luma.gl and deck.gl frameworks.                             |
+| 2017  | v1.0    | `math.gl` was broken out into its own repository to manage luma.gl growth. The goal was to  independently usable set of 3D and Geospatial math modules.                |
+| 2018  | v2.0    | The math.gl API started to mature.                                                                                                                                     |
+| 2019  | v3.0    | A collaboration with the Cesium team around 3D Tiles led to parts of the Cesium math library were ported into the `math.gl/geospatial` and `@math.gl/culling` modules. |
+| 2020+ | v3.x    | Additional geospatial modules have gradually been added to support more advanced use cases for deck.gl.                                                                |
+| 2022  | v3.6    | Code base fully rewritten in TypeScript.                                                                                                                               |
+| 2023  | v4.0    | ES module support. gl-matrix was removed as a dependency and math.gl became fully stand-alone.                                                                         |
 
 ## Attributions
 

docs/developer-guide/external-frameworks.md

@@ -1,28 +1,20 @@
 # Using with Other Frameworks
 
-> This article is a work in progress.
-
-math.gl is designed to be (reasonably) interoperable with other major math frameworks.
+math.gl has made some efforts to be "interoperable" with other major JavaScript math frameworks.
 
 ## Using with gl-matrix
 
 ### API comparison
 
-The math.gl API is intentionally designed to remain intuitively similar to the wrapped `gl-matrix` procedures, usually just removing the first one or two parameters from each function (the out argument and the first input arguments, both are implictly set to `this`), and exposes the remaining arguments in the same order as the gl-matrix api.
-
-Only in a few cases where `gl-matrix` methods take a long list arguments (e.g. `Matrix4.perspective`, `Matrix4.ortho` etc) or return multiple values (e.g. `quat.getAxisRotation`) do methods provide a modified API that is more natural for modern ES6 applications to use, e.g. using named parameters, or collecting all results in one returned object.
-
-Also, for transforming vectors with matrices, the `transform*` methods are offered in the matrix classes, instead of on the vector classes. They also (optionally) auto allocate the result vectors.
+The math.gl Matrix and Vector class APIs are inspired by the popular `gl-matrix` library, and it is possible to use `gl-matrix` together with math.gl.
 
-In code that is very frequently executed, working with directly with gl-matrix can sometimes provide better performance math.gl.
+Sometimes, in code that is very frequently executed, working with directly with gl-matrix can sometimes provide better performance than math.gl, mainly by avoiding object creation. However in such cases you may also be able to use pre-created "scratch objects" in math.gl to achieve similar performance.
 
-## References
-
-- Top learn more about gl-matrix. The [gl-matrix docs](http://glmatrix.net/docs/) are a good start. Additionally, the gl-matrix source code is partially updated with JSDoc.
+To learn more about gl-matrix, the [gl-matrix docs](http://glmatrix.net/docs/) are a good start.
 
 ## Using with THREE.js
 
-math.gl makes efforts to be compatible with the THREE.js math API.
+math.gl is partially compatible with the THREE.js math API. In fact, math.gl includes a fork of the math test suite from THREE.js, parts of which pass cleanly when run using the math.gl core classes (admittedly with a few disabled cases).
 
 ### Method Interoperability
 
@@ -36,10 +28,6 @@ In particular, the basic math.gl math classes have implementations of most of th
 | `Matrix3` | `THREE.Matrix3` | Math.gl stores in column-major order by default |
 | `Matrix4` | `THREE.Matrix4` | ditto                                           |
 
-- Can a THREE.Math class be created/initialized from a math.gl class? Probably yes, as we expose x, y, z accessors
-- Can a math.gl class be created/initialized from a THREE.Math class? Probably not yet, as we don't look for x, y, z.
-
-### Notable Incompatibilities
 
 ### Colum-Major vs. Row-Major Matrices
 
@@ -51,10 +39,5 @@ Since math.gl's classes are subclasses of JavaScripts built-in `Array` class, th
 
 ### Cross-Library Convenience Methods
 
-A complication with THREE.js is that the framework is not strict about separating the library into independent layers. Thus the THREE math classes have convenience methods that accept other THREE.js objects such `Geometries` and `BufferAttributes`. These methods are not implemented in math.gl.
-
-### Remarks
+A complication with THREE.js is that the framework is not strict about separating the library into independent layers. Thus the THREE math classes have convenience methods that accept other THREE.js objects such `Geometries` and `BufferAttributes`. These methods can not be implemented in math.gl.
 
-- An indicator of the level of THREE.js compatibility is the fact that math.gl includes a copy of the math test suites from THREE.js, parts of which pass cleanly when run the math.gl classes listed above (admittedly with a few disabled cases).
-- While it would of course be nice to be able to state "100% compatiblity" with the THREE.js math API, there are hard technical constraints. For instance, since math.gl's classes are subclasses of JavaScripts built-in `Array` class, the `length` property has the special meaning defined by `Array`, so it is not possible to implement the `Vector.length()` method defined by THREE.js.
-- Note that THREE.js compatibility methods will not always be implemented in the most performant way. Every compatibility methods adds size to the library and if they can be implemented in a compact way by calling existing methods that is often preferred over raw speed.

docs/developer-guide/geospatial/dggs.md

@@ -1,16 +1,19 @@
 # Discrete Global Grids
 
-Working with discrete global grids is a powerful way of unifying the treatment of geospatial data.
+Discrete global grid systems are powerful tools that enables us to convert geospatial data into a common, easy-to-analyze form.
 
-When working with multiple grid systems, working with a group of independent libraries with different API conventions and limitations can be non-optimal. There is sometimes a value in having a common set of libraries that work in a somewhat unified way.
+## Why DGGS in math.gl
 
-## Goals
+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.
 
-The DGGS support in math.gl is currently mainly focused on decoding cell indexes or tokens into center points (lng/lat) or boundaries (polygon on lng/lats). 
+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.
 
-Encoding and advanced operations (child/neighbor calculation, polygon fills etc are not currently included). Some basic encoding may be included in the future, however a secondary goal is to keep these libraries fairly small.
+## Goals
 
-In terms of API design and nomenclature, the golden standard for DGGS systems at this time is arguably [H3](https://h3geo.org), in terms of functionality, number of languages and platforms supported, community activity etc.  
+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.
 
 ## Supported Grid Systems
 
@@ -24,22 +27,32 @@ In terms of API design and nomenclature, the golden standard for DGGS systems at
 Note that `h3-js` is not a `math.gl` library. For H3 it is recommended to work directly with the H3 JavaScript bindings.
 
 
-## API
+## H3 API Conventions
+
+In terms of API design and nomenclature, the golden standard for DGGS systems at this time is arguably [H3](https://h3geo.org), in terms of functionality, number of languages and platforms supported, community activity etc.  
 
 Rather than expose the original function names as in the existing JavaScript libraries for each DGGS, math.gl applies API naming convention based on the H3 API.
 
-| Function               | S2                  | QuadKey                  | GeoHash                  | H3                  |
-| ---------------------- | ------------------- | ------------------------ | ------------------------ | ------------------- |
-| Get cell center        | `getS2LngLat`       | `getQuadKeyLngLat`       | `getGeoHashLngLat`       | `getH3LngLat`       |
-| Get cell boundary      | `getS2Boundary`     | `getQuadKeyBoundary`     | `getGeoHashBoundary`     | `getH3Boundary`     |
-| Get cell boundary flat | `getS2BoundaryFlat` | `getQuadKeyBoundaryFlat` | `getGeoHashBoundaryFlat` | `getH3BoundaryFlat` |
+| Function               | **H3**                  | S2                  | QuadKey                  | GeoHash                  |
+| ---------------------- | ----------------------- | ------------------- | ------------------------ | ------------------------ |
+| Get cell center        | **`getH3LngLat`**       | `getS2LngLat`       | `getQuadKeyLngLat`       | `getGeoHashLngLat`       |
+| Get cell boundary      | **`getH3Boundary`**     | `getS2Boundary`     | `getQuadKeyBoundary`     | `getGeoHashBoundary`     |
+| Get cell boundary flat | **`getH3BoundaryFlat`** | `getS2BoundaryFlat` | `getQuadKeyBoundaryFlat` | `getGeoHashBoundaryFlat` |
 
 ## Comparison of DGGS Systems
 
+| Characteristic    | **H3**     | S2          | QuadKey     | GeoHash     |
+| ----------------- | ---------- | ----------- | ----------- | ----------- |
+| Cell shape        | Hexagon    | "square"    | square      | square      |
+| Cell area         | "constant" | varies      | varies      | varies      |
+| Neighbor distance | "constant" | 1 or 1.4... | 1 or 1.4... | 1 or 1.4... |
+| Child cells       | 7          | 4           | 4           | 4           |
+| Exact hierarchy   | No         | Yes         | Yes         | Yes         |
+
 ### H3
 
-H3, initally developed at Uber, is now widely used across the geospatial indusry. 
-While not directly supported by math.gl, is in fact the DGGS we would recommend for most applications.
+H3 is now widely used across the geospatial industry (it was initially developed at Uber).
+While not directly supported by math.gl, H3 is in fact the DGGS we would recommend for most applications.
 
 - Extensive, optimized, evolving API.
 - Superb cross-language support.
@@ -50,9 +63,13 @@ While not directly supported by math.gl, is in fact the DGGS we would recommend
 Downsides:
 - More complex projection math.
 
+### S2
+
+S2 works well when exact aggregation and subdivision are needed but has some disadvantages when e.g. neighbor cell calculations are important
+
 ### GeoHash
 
-Geohash is common choice  open source word http://en.wikipedia.org/wiki/Geohash
+[Geohash](http://en.wikipedia.org/wiki/Geohash) is common choice in the open source word.
 
 Good cross-language support.
 
@@ -62,5 +79,5 @@ Bing Maps uses a [quadkey](http://msdn.microsoft.com/en-us/library/bb259689.aspx
 
 - Quadtrees are more predictable in that each level spans a square (at least in terms of coordinates), whereas in geohash representation sometimes squares sometimes rectangles are spanned.
 
-### Other systems
+