From eecad0d9766f93dc1e0bb2b9501cfad0e8c0d965 Mon Sep 17 00:00:00 2001 From: Xiaoji Chen Date: Mon, 26 Aug 2024 14:50:40 -0700 Subject: [PATCH] Lint docs --- docs/README.md | 8 +++--- docs/developer-guide/external-frameworks.md | 2 -- docs/developer-guide/geospatial/dggs.md | 9 +++---- docs/developer-guide/math/rotations.md | 25 +++++++++++-------- docs/modules/dggs-geohash/README.md | 1 - .../dggs-geohash/api-reference/geohash.md | 1 - docs/modules/dggs-quadkey/README.md | 5 ++-- .../dggs-quadkey/api-reference/quadkey.md | 1 - docs/modules/dggs-s2/api-reference/s2.md | 5 ++-- docs/modules/types/README.md | 2 +- .../types/api-reference/array-types.md | 9 ++++--- docs/roadmap.md | 1 - docs/upgrade-guide.md | 4 +-- docs/whats-new.md | 7 +++--- 14 files changed, 38 insertions(+), 42 deletions(-) diff --git a/docs/README.md b/docs/README.md index 545a2cd1..e581861f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,16 +1,16 @@ # Introduction -Welcome to math.gl! +Welcome to math.gl! 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. +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 - **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`** +- **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`** @@ -64,7 +64,7 @@ math.gl is fully supported on: | 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. | +| 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. | diff --git a/docs/developer-guide/external-frameworks.md b/docs/developer-guide/external-frameworks.md index ce9eb3c5..63c505fa 100644 --- a/docs/developer-guide/external-frameworks.md +++ b/docs/developer-guide/external-frameworks.md @@ -28,7 +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 | - ### Colum-Major vs. Row-Major Matrices By default, math.gl stores matrices in column-major order internally (while exposing a row-major friendly interface), whereas THREE.js stores matrices in row-major order. @@ -40,4 +39,3 @@ 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 can not be implemented in math.gl. - diff --git a/docs/developer-guide/geospatial/dggs.md b/docs/developer-guide/geospatial/dggs.md index c1953422..d0169ea8 100644 --- a/docs/developer-guide/geospatial/dggs.md +++ b/docs/developer-guide/geospatial/dggs.md @@ -26,10 +26,9 @@ Encoding (lng/lat to cell index) and advanced operations (child/neighbor calcula Note that `h3-js` is not a `math.gl` library. For H3 it is recommended to work directly with the H3 JavaScript bindings. - ## 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. +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. @@ -61,6 +60,7 @@ While not directly supported by math.gl, H3 is in fact the DGGS we would recomme - K-ring formation for filtering and convolutions Downsides: + - More complex projection math. ### S2 @@ -75,9 +75,6 @@ Good cross-language support. ### QuadKey -Bing Maps uses a [quadkey](http://msdn.microsoft.com/en-us/library/bb259689.aspx.) structure as their tiling scheme. Here is an overview of the concept +Bing Maps uses a [quadkey](http://msdn.microsoft.com/en-us/library/bb259689.aspx.) structure as their tiling scheme. Here is an overview of the concept - 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. - - - diff --git a/docs/developer-guide/math/rotations.md b/docs/developer-guide/math/rotations.md index 3ca81496..0e84bf2c 100644 --- a/docs/developer-guide/math/rotations.md +++ b/docs/developer-guide/math/rotations.md @@ -43,7 +43,7 @@ Interpolation of quaternions is done using Spherical Linear intERPolation (aka S ## Rotation Matrices -Rotations around arbitrary points can be treated as rotations around the origin simply by applying a translation before the rotation, and the inverse translation after the rotation. +Rotations around arbitrary points can be treated as rotations around the origin simply by applying a translation before the rotation, and the inverse translation after the rotation. Thus, when combining rotations with other transformations (translations, scalings, projections etc), 4x4 matrices are the representation of choice. @@ -102,20 +102,23 @@ Calculate the quaternion that represents the rotation you want to apply (e.g. mo If you are new to working with 3D rotations it can be good to have an awareness of how they differ mathematically from 2D rotations In two dimensions, rotations represent a highly structured and intuitive set of operations: - - A series of 2D rotations can be applied in any order (they commute). - - The combination of two 2D rotations can always be expressed as another single rotation (simply by taking the sum of the angles of the two rotations). - - Any 2D rotation can be fully parametrized by a single value (the "angle"). + +- A series of 2D rotations can be applied in any order (they commute). +- The combination of two 2D rotations can always be expressed as another single rotation (simply by taking the sum of the angles of the two rotations). +- Any 2D rotation can be fully parametrized by a single value (the "angle"). However, in three dimensions, rotations start to loose some "structure": - - In 3D, rotations are no longer order-independent (they are not commutative), meaning that applying the same two rotations in different order will often yield different results. - - However, by [Euler's Rotation Theorem](https://en.wikipedia.org/wiki/Euler%27s_rotation_theorem), two 3D rotations around the origin can still always be expressed as (combined into) another single 3D rotation around the origin. - - Also, a 3D rotation requires not two, but three values to be fully specified. + +- In 3D, rotations are no longer order-independent (they are not commutative), meaning that applying the same two rotations in different order will often yield different results. +- However, by [Euler's Rotation Theorem](https://en.wikipedia.org/wiki/Euler%27s_rotation_theorem), two 3D rotations around the origin can still always be expressed as (combined into) another single 3D rotation around the origin. +- Also, a 3D rotation requires not two, but three values to be fully specified. While math.gl does not support rotations in four and higher dimensions, it should be no surprised that rotations continue to "loose structure" as the number of dimensions increase: - - Higher dimension rotations are also not commutative. - - Euler's Rotation Theorem no longer holds. There are now two different "types" of basic rotations, and the combination of two rotations will in general not even result in another "rotation", but another, more complex transformation. - - In addition, the number of parameters (degrees of freedom) required to fully specify a rotation grows with mind-boggling rapidity, as `2^(n-1) - 1`, (meaning that e.g. a "21 dimensional rotation" would require over one million values to be fully specified). - + +- Higher dimension rotations are also not commutative. +- Euler's Rotation Theorem no longer holds. There are now two different "types" of basic rotations, and the combination of two rotations will in general not even result in another "rotation", but another, more complex transformation. +- In addition, the number of parameters (degrees of freedom) required to fully specify a rotation grows with mind-boggling rapidity, as `2^(n-1) - 1`, (meaning that e.g. a "21 dimensional rotation" would require over one million values to be fully specified). + ## Background: More on Euler Angles [Euler angle values](https://en.wikipedia.org/wiki/Euler_angles) diff --git a/docs/modules/dggs-geohash/README.md b/docs/modules/dggs-geohash/README.md index b41a03b1..f4f4716c 100644 --- a/docs/modules/dggs-geohash/README.md +++ b/docs/modules/dggs-geohash/README.md @@ -24,4 +24,3 @@ const polygon = getGeohashPolygon(geohash); ``` ## Attribution - diff --git a/docs/modules/dggs-geohash/api-reference/geohash.md b/docs/modules/dggs-geohash/api-reference/geohash.md index 124c3df6..1d933105 100644 --- a/docs/modules/dggs-geohash/api-reference/geohash.md +++ b/docs/modules/dggs-geohash/api-reference/geohash.md @@ -22,5 +22,4 @@ Returns the boundary of a GeoHash cell as a polygon of [lng, lat], [lng, lat], . #### `getGeohashBoundaryFlat(geohash: string): number[]` - Returns the boundary of a GeoHash cell as a flat polygon of lng, lat, lng, lat, ... . diff --git a/docs/modules/dggs-quadkey/README.md b/docs/modules/dggs-quadkey/README.md index 05585564..fdd42909 100644 --- a/docs/modules/dggs-quadkey/README.md +++ b/docs/modules/dggs-quadkey/README.md @@ -18,12 +18,11 @@ npm install @math.gl/dggs-quadkey ## Usage -Get a polygon representing the outline of a specific +Get a polygon representing the outline of a specific + ```js import {getQuadkeyLngLat} from '@math.gl/dggs-quadkey'; const center = getQuadkeyLngLat(quadkey); ``` ## Attribution - - diff --git a/docs/modules/dggs-quadkey/api-reference/quadkey.md b/docs/modules/dggs-quadkey/api-reference/quadkey.md index e450ff5b..c60ab615 100644 --- a/docs/modules/dggs-quadkey/api-reference/quadkey.md +++ b/docs/modules/dggs-quadkey/api-reference/quadkey.md @@ -8,7 +8,6 @@ This module is still experimental. It may have issues and functionality may change in minor releases. ::: - The quadkey library is currently focused on decoding quadkeys. > The quadkey functions in math.gl are currently focused on **decoding** S2 encoded data, not encoding it. diff --git a/docs/modules/dggs-s2/api-reference/s2.md b/docs/modules/dggs-s2/api-reference/s2.md index 98a7431f..ea88ad58 100644 --- a/docs/modules/dggs-s2/api-reference/s2.md +++ b/docs/modules/dggs-s2/api-reference/s2.md @@ -17,10 +17,11 @@ See [s2geometry.io](https://s2geometry.io/) for more information. ## API Notes -The API provided by this module mainly works with S2 token strings, +The API provided by this module mainly works with S2 token strings, as those are typically found in data files. But note that S2 cells have multiple representations. They can be represented as: + - S2 token strings (stringified versions of the indexes) - S2 indexes which are 64 bit numbers represented by the `Long` type. - Hilbert QuadKey strings. @@ -32,7 +33,7 @@ Information on the the Long data type can be found here: TBA #### `getIndexFromS2Token(s2Token: string): Long` -Decodes a string into the 64 bit token. +Decodes a string into the 64 bit token. #### `getS2TokenFromIndex(s2Index: Long): string` diff --git a/docs/modules/types/README.md b/docs/modules/types/README.md index 1dc1f7b8..bfb4656a 100644 --- a/docs/modules/types/README.md +++ b/docs/modules/types/README.md @@ -7,4 +7,4 @@ across other frameworks. ```bash npm install @math.gl/types -``` \ No newline at end of file +``` diff --git a/docs/modules/types/api-reference/array-types.md b/docs/modules/types/api-reference/array-types.md index 7f07c2df..13e77732 100644 --- a/docs/modules/types/api-reference/array-types.md +++ b/docs/modules/types/api-reference/array-types.md @@ -4,8 +4,6 @@ math.gl provides a number of numeric array types. TypeScript types to simplify working with a mix of typed arrays and standard JavaScript arrays containing numbers. - - ## Types ### `TypedArray` @@ -46,14 +44,16 @@ Types matching number arrays of specific lengths or typed arrays. Checks if a value is a typed array. -Remarks: +Remarks: + - Avoids type narrowing problems with `ArrayBuffer.isView()` (which accepts `DataViews` that do not support array methods). ### `isNumberArray(value: unknown): value as NumberArray` Checks if a value is a classic JavaScript array of numbers. -Remarks: +Remarks: + - Only the type of the first element in a standard array is checked to be a `number`. ### `isNumericArray(value: unknown): value as NumericArray` @@ -61,5 +61,6 @@ Remarks: Checks if a value is either a classic JavaScript array of numbers or a typed array. Remarks: + - Avoids type narrowing problems with `ArrayBuffer.isView()` (which accepts `DataViews` that do not support array methods). - Only the type of the first element in a standard array is checked to be a `number`. diff --git a/docs/roadmap.md b/docs/roadmap.md index 5dd6a683..f93989e2 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -15,4 +15,3 @@ Some of the high-level goals for future and past versions # v3.6 - Full typescript support - diff --git a/docs/upgrade-guide.md b/docs/upgrade-guide.md index 754ba7b4..2a179191 100644 --- a/docs/upgrade-guide.md +++ b/docs/upgrade-guide.md @@ -8,7 +8,7 @@ ## Upgrading to v4.0 - math.gl v4.0 is now packaged as ESM modules, but with additional CommonJS exports. In most cases you should not have problems importing 4.0. -- The `gl-matrix` dependency has been removed. You can still install / import gl-matrix in your application, it should remain highly compatible with math.gl. +- The `gl-matrix` dependency has been removed. You can still install / import gl-matrix in your application, it should remain highly compatible with math.gl. ## Upgrading to v3.6 @@ -17,13 +17,13 @@ While the API itself has not changed, in some cases, the introduction of types made it harder to keep supporting some type signatures and overloads. Known changes + - `Matrix4.lookAt()` - Now only accepts named parameters. - `SphericalCoordinates()` - Constructor is now more restrictive in terms of what parameters it accepts. Note that some omissions may be unintentional, feel free to report upgrade issues in the math.gl github repo. - ## Upgrading to v3.0 ### Matrix API changes diff --git a/docs/whats-new.md b/docs/whats-new.md index 7ae134ac..53756468 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -63,9 +63,9 @@ Release Date: Q3, 2024. **`@math.gl/types`** -- `Bounds`, `Bounds2D` and `Bounds3D` - New types for expressing [bounds](./modules/types/api-reference/bounds) (extents): . -- `NumberArray2` - `NumberArray16` - New types to specify numeric arrays of a specific length: . -- `NumericArray2` - `NumericArray16` - New types to specify numeric arrays of a specific length: . +- `Bounds`, `Bounds2D` and `Bounds3D` - New types for expressing [bounds](./modules/types/api-reference/bounds) (extents). +- `NumberArray2` - `NumberArray16` - New types to specify numeric arrays of a specific length. +- `NumericArray2` - `NumericArray16` - New types to specify numeric arrays of a specific length. - `isTypedArray()`, `isNumericArray()` - These utilities now perform typescript type narrowing. ## v4.0 @@ -112,6 +112,7 @@ are no longer supported. For details, consult the [upgrade guide](./upgrade-guid - New module that exports a few typescript types that e.g. generalize handling of numeric arrays. **`@math.gl/polygon` (NEW)** + - Includes earcut 2.2 (various bug fixes for edge cases) - The `earcut` utility supports a new argument `plane` to calculate tesselation on alternative projection planes.