@maptiler/sdk 1.1.2 → 1.2.0

package/.eslintrc.cjs

@@ -1,10 +1,20 @@
+const tsConfig = require('./tsconfig.json');
+
 module.exports = {
-  extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'prettier'
+  ],
   parser: '@typescript-eslint/parser',
-  plugins: ['@typescript-eslint'],
+  plugins: [
+    '@typescript-eslint',
+    'prettier'
+  ],
   root: true,
-  //"@typescript-eslint/ban-ts-comment": "warn"
   rules: {
     "@typescript-eslint/ban-ts-comment": "warn",
-  }
-};
+    "prettier/prettier": "error",
+  },
+  ignorePatterns: tsConfig.exclude,
+};

package/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## Objective
+What is the goal?
+
+## Description
+What changed, how and why?
+
+## Acceptance
+How were changes tested?
+
+## Checklist
+- [ ] I have added relevant info to the CHANGELOG.md

package/.github/workflows/format-lint.yml

@@ -0,0 +1,24 @@
+name: Format and Lint
+
+on: [pull_request]
+
+jobs:
+  format-and-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out Git repository
+        uses: actions/checkout@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+
+      - name: Install Node.js dependencies
+        run: npm ci
+
+      - name: Formatting with Prettier
+        run: npm run format
+
+      - name: Linting with ESLint
+        run: npm run lint

package/CHANGELOG.md

@@ -1,37 +1,77 @@
-# Changelog
-
-## [v1.1.1](https://github.com/maptiler/maptiler-sdk-js/releases/tag/v1.1.1)
-- VER update to `maplibre-gl@3.1.0`
-
-## [v1.1.0](https://github.com/maptiler/maptiler-sdk-js/releases/tag/v1.1.0)
-- VER updated from `maplibre-gl@3.0.0-pre.4` to `maplibre-gl@3.0.1` (this includes the switch to WebGL2)
-- UP made the few necessary changes acording to updating the ML v3. No braking change for SDK API
-- FIX the MapTiler logo rel name and its nofollow feature
-- ADD bringing back Map's `options.transformRequest` and `.setTransformRequest()`
-
-
-## [v1.0.12](https://github.com/maptiler/maptiler-sdk-js/releases/tag/v1.0.12)
-- ADD a new language flag `Language.STYLE_LOCK` to force keep the language form the style and prevent any further update. Can be at a sigle map instance level (via constuctor option `language`) or via global config (`config.primaryLanguage`)
-- FIX the fallback language was `{name:latin}`, it is now replaced by `{name}`, which is for the local name (present by default for many places while `latin` is less frequent).
-
-## [v1.0.11](https://github.com/maptiler/maptiler-sdk-js/releases/tag/v1.0.11)
-- DOC update for `Map`'s `option.maptilerLogo` that was a bit unclear
-- FIX now exporting `MaptilerNavigationControl`
-
-## [v1.0.10](https://github.com/maptiler/maptiler-sdk-js/releases/tag/v1.0.10)
-- ADD terrain growing animation on enabling/disabling
-- ADD `Map` custom event `loadWithTerrain`
-- ADD `Map` lifecycle methods `.onLoadAsync()` and `.onLoadWithTerrainAsync()`
-- DOC readme section was added about the event an methods above
-- VER updated from `maplibre-gl@3.0.0-pre.3` to `maplibre-gl@3.0.0-pre.4`
-- VER updated from `typedoc@0.23.21` to `typedoc@0.24.4`, which changes slightly the look of the reference documentation.
-- VER updated from `typescript@4.8.4` to `typescript@5.0.4`
-- VER updated from `rollup@2.79.0` to `rollup@3.20.6` as well as all the Rollup plugins
-
-## [v1.0.9](https://github.com/maptiler/maptiler-sdk-js/releases/tag/v1.0.9)
-- FIX: if the geolocate option is missing from `Map` constructor, then it's considered `false`
-
-- FIX: The instance types for the following MapLibre classes are now fully exported:
+# MapTiler SDK Changelog
+
+## DEVEL
+### New Features
+### Bug Fixes
+### Others
+
+## 1.2.0
+### New Features
+- Added the Minimap control https://github.com/maptiler/maptiler-sdk-js/pull/54
+- Added vector layer helpers to create easier:
+  - point layer (https://github.com/maptiler/maptiler-sdk-js/pull/61)
+  - heatmap layer (https://github.com/maptiler/maptiler-sdk-js/pull/61)
+  - polyline layer, including parsing from GPX/KML (https://github.com/maptiler/maptiler-sdk-js/pull/51)
+  - polygon layer (https://github.com/maptiler/maptiler-sdk-js/pull/56)
+- Add the `ColorRamp` class to create and customize color ramps, as well as `ColorRampCollection` with many predefined ones (as part of https://github.com/maptiler/maptiler-sdk-js/pull/61)
+- Improved the language management for increased compatibility with [MapTiler Customize](https://cloud.maptiler.com/maps/editor/) (https://github.com/maptiler/maptiler-sdk-js/pull/58)
+### Bug Fixes
+- Fixed type export (https://github.com/maptiler/maptiler-sdk-js/pull/47)
+### Others
+- Upgrade to MapLibre v3.5.2 (https://github.com/maptiler/maptiler-sdk-js/pull/63)
+- Update of TypeScript configuration `moduleResolution` to `Bundler` (https://github.com/maptiler/maptiler-sdk-js/pull/62)
+
+## 1.1.2
+### Bug Fixes
+- Now using a fixed version of MapLibre GL. No longer use `^` because this caused issues as MapLibre made minor/patch update that were not backward compatible
+
+## 1.1.1
+### Others
+- Update to `maplibre-gl@3.1.0`
+
+## 1.1.0
+### New Features
+- Bringing back Map's `options.transformRequest` and `.setTransformRequest()`
+### Bug Fixes
+- Fixed the MapTiler logo rel name and its nofollow feature
+- Made the few necessary changes acording to updating the ML v3. No braking change for SDK API
+### Others
+- Updated from `maplibre-gl@3.0.0-pre.4` to `maplibre-gl@3.0.1` (this includes the switch to WebGL2)
+
+
+## 1.0.12
+### New Features
+- Added a new language flag `Language.STYLE_LOCK` to force keep the language form the style and prevent any further update. Can be at a sigle map instance level (via constuctor option `language`) or via global config (`config.primaryLanguage`)
+### Bug Fixes
+- The fallback language was `{name:latin}`, it is now replaced by `{name}`, which is for the local name (present by default for many places while `latin` is less frequent).
+
+## 1.0.11
+### Bug Fixes
+- Now exporting `MaptilerNavigationControl`
+### Others
+- Documentation update for `Map`'s `option.maptilerLogo` that was a bit unclear
+
+## 1.0.10
+### New Features
+- Terrain growing animation on enabling/disabling
+- Added `Map` custom event `loadWithTerrain`
+- Added `Map` lifecycle methods `.onLoadAsync()` and `.onLoadWithTerrainAsync()`
+### Others
+- Readme section was added about the event an methods above
+- Updated from `maplibre-gl@3.0.0-pre.3` to `maplibre-gl@3.0.0-pre.4`
+- Updated from `typedoc@0.23.21` to `typedoc@0.24.4`, which changes slightly the look of the reference documentation.
+- Updated from `typescript@4.8.4` to `typescript@5.0.4`
+- Updated from `rollup@2.79.0` to `rollup@3.20.6` as well as all the Rollup plugins
+
+## 1.0.9
+### New Features
+- Added new styles:
+  - `MapStyle.STREETS.NIGHT`
+  - `MapStyle.WINTER.DARK`
+  - `MapStyle.OUTDOOR.DARK`
+### Bug Fixes
+- If the geolocate option is missing from `Map` constructor, then it's considered `false`
+- The instance types for the following MapLibre classes are now fully exported:
   - `NavigationControl`
   - `GeolocateControl`
   - `AttributionControl`
@@ -55,8 +95,7 @@
   - `VectorTileSource`
   - `VideoSource`
   - `MapMLGL`
-
-- FIX: The following class have been extended to provide greater compatibility with SDK,s MapL
+- The following class have been extended to provide greater compatibility with SDK,s MapL
   - `Popup`
   - `Marker`
   - `Style`
@@ -75,40 +114,44 @@
   - `FullscreenControl`
   - `TerrainControl`
 
-- ADD: new styles:
-  - `MapStyle.STREETS.NIGHT`
-  - `MapStyle.WINTER.DARK`
-  - `MapStyle.OUTDOOR.DARK`
 
-## [v1.0.8](https://github.com/maptiler/maptiler-sdk-js/releases/tag/v1.0.8)
-- FIX: Since v1.0.7, the `Map` primary language (when custom) was no longer persistant on style update.
+## 1.0.8
+### Bug Fixes
+- Since v1.0.7, the `Map` primary language (when custom) was no longer persistant on style update.
 
-## [v1.0.7](https://github.com/maptiler/maptiler-sdk-js/releases/tag/v1.0.7)
+## 1.0.7
+### New Features
 - The `apiKey` can now be specified in the `Map` constructor (will propagate to `config`)
 - The `language` can now be speficifed in the `Map` constructo (will **not** propagete to `config` and will apply only to this specific instance)
 - `Map` now has the method `.getSdkConfig()` to retrieve the config object. 
 - `Map` now has the method `.getMaptilerSessionId()` to retrieve the MapTiler session ID
-
 Both `.getSdkConfig()` and `.getMaptilerSessionId()` are handy for layers or control built outside of the SDK that still need some of the configuration to interact with the server. Those components do not always have access to the internal of the SDK (especially that the config is scoped) but can access to the `Map` instance to which they are added with the implementation of the `.onAdd()` method.
 
-## [v1.0.6](https://github.com/maptiler/maptiler-sdk-js/releases/tag/v1.0.6)
+## 1.0.6
+### New Features
 - Now exposing `MaptilerGeolocateControl` for external initialization if needed
 - Now exposing `MaptilerTerrain` for external initialization if needed
 
-## [v1.0.5](https://github.com/maptiler/maptiler-sdk-js/releases/tag/v1.0.5)
+## 1.0.5
+### New Features
 - Terrain elevation is now using MapTiler's `terrain-rgb-v2`
 
-## [v1.0.4](https://github.com/maptiler/maptiler-sdk-js/releases/tag/v1.0.4)
+## 1.0.4
+### Others
 - Improved the geolocate control behavior by not zooming out
 
-## [v1.0.3](https://github.com/maptiler/maptiler-sdk-js/releases/tag/v1.0.3)
+## 1.0.3
+### Bug Fixes
 - Fixed the usage of relative path style JSON (in `Map` constructor and `.setStyle()`)
 
-## [v1.0.2](https://github.com/maptiler/maptiler-sdk-js/releases/tag/v1.0.2)
+## 1.0.2
+### Bug Fixes
 - Fixed the dependency scheme of MapLibre import.
 
-## [v1.0.1](https://github.com/maptiler/maptiler-sdk-js/releases/tag/v1.0.1)
+## 1.0.1
+### Others
 - Reducing the NPM size by ignoring documentation images
 
-## [v1.0.0](https://github.com/maptiler/maptiler-sdk-js/releases/tag/v1.0.0)
+## 1.0.0
+### Others
 - First public version!

package/colorramp.md

@@ -0,0 +1,93 @@
+# ColorRamps resampling
+`ColorRamps` in the SDK, whether they are built-in (`ColorRampCollection`) or custom made (`new ColorRamp()`) can be resampled in a non linear fashion. Such resampling can serve different purposes, for instance:
+- the data to visualize follows a non-linear function
+- the goal of the visualization is to specificaly emphasize difference towards the lower or upper bound of the range
+
+Creating a non linear color ramp can be a bit difficult, so resampling an existing one that has been originaly created as linear is easier. At the moment, the SDK provides four methods to resample a color ramp with the `.resample()` function:
+- folowing a square function: `"ease-in-square"`
+- folowing a square function: `"ease-out-square"`
+- following a square root: `"ease-in-sqrt"`
+- following a square root: `"ease-out-sqrt"`
+- folowing an exponential function: `"ease-in-exp"`
+- folowing an exponential function: `"ease-in-exp"`
+
+Note: the *ease-out* equivalent of *ease-in-square* is technically *ease-out-square* and the *ease-in* equivalent of *ease-out-sqrt* is technically *ease-in-sqrt* but after some tests, it appeared that `"ease-in-square"` and `"ease-out-sqrt"` where a better pairing so this is why we decided to focus mainly on those two.
+
+Terminology:
+- an function is said **ease in** when its acceleration is fairly low at the begining and much higher towards the end
+- an function is said **ease out** when its acceleration is quite high at begining and much lower towards the end
+
+
+## Linear logic
+All the built-in color ramps are defined in a range of `(0, 1)`. Even though they can be scaled (`.scale(min, max)`) or custom ones can be created on a diferent interval, the range of (0, 1) is the most convenient to visualize how things work. Also, to keep it simple we are using a linear gray color ramp going from `(R:0, G:0, B:0)` to `(R:255, G:255, B:255)`. You can find this specific one as `ColorRampCollection.GRAY`.
+
+![](images/plot_linear_gradient.jpg)
+
+- along the `x` axis (horizontal), the input number. This can be the intensity or any real-worl metric
+- along the `y` axis (vertical), the output color
+
+As we can see:
+- an input of `0` will yied the color `(R:0, G:0, B:0)`
+- an input of `0.5` will yied the color `(R:127, G:127, B:127)`
+- an input of `1` will yied the color `(R:255, G:255, B:255)`
+
+The original linear GRAY color ramp looks like this:
+
+![](images/gray_linear.png)
+
+## *ease-out-sqrt* method
+To resample a color ramp with the *square root* method, simply do:
+```ts
+const graySqrt = ColorRampCollection.GRAY.resample("ease-out-sqrt");
+```
+
+Note: this will **not** modify the origin `ColorRampCollection.GRAY`.
+
+There are multiple ways to visualize the effect of such resampling. The simplest is probably to do as above (*linear logic*), but using a *square root* function:
+
+![](images/plot_sqrt_gradient.jpg)
+
+This will yield the following color ramp:
+
+![](images/gray_sqrt.png)
+
+If we compare with the linear GRAY from above, we can see that the lower part (the darkest) is sort of compressed, while the upper part (the lightest) looks stretched.
+
+As a result:
+- an input of `0` will yied the color `(R:0, G:0, B:0)`
+- an input of `0.5` will yied the color `(R:180, G:180, B:180)`
+- an input of `1` will yied the color `(R:255, G:255, B:255)`
+
+Another way to look at the *ease-out-sqrt-resampled* GRAY color ramp is by using it along the `y` axis and addressing it with data that are following a linear rule:
+![](images/linear_on_sqrt.jpg)
+
+This can be convenient to do if the purpose is to emphasize the change of values on the lower-end, say in the range `(0, 0.4)` as the color response will be faster-changing than with a linear scale.
+
+## *ease-in-square* method
+To resample a color ramp with the *square* method, simply do:
+```ts
+const graySquare = ColorRampCollection.GRAY.resample("ease-in-square");
+```
+
+Note: this will **not** modify the origin `ColorRampCollection.GRAY`.
+
+Let's visualize it, using the original linear gradient along the `y` axis:
+
+![](images/plot_square_gradient.jpg)
+
+This will yield the following color ramp:
+
+![](images/gray_square.png)
+
+As we can see, compared to the linear ramping, the change is color is slower towards the lower end and faster towards the end of the range.
+
+As a result:
+- an input of `0` will yied the color `(R:0, G:0, B:0)`
+- an input of `0.5` will yied the color `(R:64, G:64, B:64)`
+- an input of `1` will yied the color `(R:255, G:255, B:255)`
+
+Again, we can visualize a *ease-in-square-resampled* color ramp by using it alongside the `y` axis, with linear data:
+
+![](images/linear_on_square.jpg)
+
+Contrary to the *ease-out-sqrt* method, the *ease-in-square* will yield faster changing colors on the upper bound of the input range.