v1.2.0 (#64)

* setup full typescript support * primary language exists on construction * first review cleanup * second review cleanup * UP gitignore * UP gitignore * UP typedoc and config * UP the prepare npm script is no longer copying demos to doc * FIX inheritance pattern of some Controls due to ML update * FIX Marker now requires an option object * WIP polyline layer helper * REM log * ADD adding a poliline layer * mock the gpx/kml parser * mock the gpx/kml parser * gpx and kml converters; better prettier support; upgrade packages; vite testing * adjust package lock * cleanup part 1 * cleanup part 2 * comment link error * FIX throwing when the string is not valid XML * FIX gpx/kml now throwing if content was xml but not of gpx/kml kind * ADD a function to convert from either gpx or kml * ADD integrate KML/GPX parser to addPolyline method * DOC added more comment * FIX DOMParser issues due to different behviors in Node (testing) and Browser * ADD demos to use map.addPolyline * ADD addPolyline examples * ENH better examples * ENH linting * Update src/Map.ts Co-authored-by: Craig O'Connor <[email protected]> * REM unnecessary @param and @return * REM some unnecessary '?' to option objects * ADD polyline blur and gap width options * ADD dash pattern interpreter into actual dash array * Update src/converters/xml.ts Co-authored-by: Craig O'Connor <[email protected]> * Update src/Map.ts Co-authored-by: Craig O'Connor <[email protected]> * ENH code readability * Update src/converters/xml.ts Co-authored-by: Craig O'Connor <[email protected]> * Update src/tools.ts Co-authored-by: Craig O'Connor <[email protected]> * ENH now supporting all the languages supported by OMT * REM geojson-validation * FIX example * Support for Customize language (#58) * ADD visitor language * WIP language logic revamp * ADD language from style metadata * ENH language definition * REM got rid of commented code * ENH adjusted the size of secondary lang with visitor language mode * Update src/Map.ts Co-authored-by: Craig O'Connor <[email protected]> * Update src/Map.ts Co-authored-by: Craig O'Connor <[email protected]> * ENH from review * ENH added things from review --------- Co-authored-by: Craig O'Connor <[email protected]> * Add polygon helper (#56) * ADD visitor language * ADD helper for addong polygon from geojson * ADD map.addPolygon * REM some data * Update src/Map.ts Co-authored-by: Craig O'Connor <[email protected]> * ENH unused import * Update src/Map.ts Co-authored-by: Craig O'Connor <[email protected]> * Update src/Map.ts Co-authored-by: Craig O'Connor <[email protected]> * ENH from review --------- Co-authored-by: Craig O'Connor <[email protected]> * Add minimap control (#54) * first attempt * reduce typescript warnings * reduce typescript warnings * add final todo * zoom ceiling; bounds bug fix; pitch off by default; unique style; simplify; etc. * fix key * simplify typescript * review part 1; cleaner types; better comments * remove zoomCeiling; its essentially minZoom * improve readability of minimap options input * bug fix; adjustments * add style downwind functions; requested changes * slight adjustment * set lang fix * improve types --------- Co-authored-by: Craig O'Connor <[email protected]> * Dev points (#59) * WIP point layer helper * WIP better clusters * WIP changed point helper options * ADD color ramps with builtins * WIP simpler set of options * ADD non linear resampling on color ramps * ADD color ramp doc * ADD outline color for points * ADD point outline settings * REM colorRamp arg and use only pointColor instead * DONE Map.addPoint * Dev points (#61) * WIP point layer helper * WIP better clusters * WIP changed point helper options * ADD color ramps with builtins * WIP simpler set of options * ADD non linear resampling on color ramps * ADD color ramp doc * ADD outline color for points * ADD point outline settings * REM colorRamp arg and use only pointColor instead * DONE Map.addPoint * ADD radius and weight being both zoom and property driven * ADD zoom comensation param to point helper * FIX minmaxzoom and added MapTiler cloud source with uuid * DOC polyline helper section in readme * WIP readme * DOC done with documenting helpers * DOC color ramp doc * DOC fix * DOC * ENH cleaning unused types * ENH updating eslint * FIX dependecy audit * ENH export types and a better style path * ENH refectoring to place the helpers in a dedicated place * FIX typo * TS moduleResolution is now "Bundler" (#62) * WIP point layer helper * WIP better clusters * WIP changed point helper options * ADD color ramps with builtins * WIP simpler set of options * ADD non linear resampling on color ramps * ADD color ramp doc * ADD outline color for points * ADD point outline settings * REM colorRamp arg and use only pointColor instead * DONE Map.addPoint * ADD radius and weight being both zoom and property driven * ADD zoom comensation param to point helper * FIX minmaxzoom and added MapTiler cloud source with uuid * DOC polyline helper section in readme * WIP readme * DOC done with documenting helpers * DOC color ramp doc * DOC fix * DOC * ENH cleaning unused types * ENH updating eslint * FIX dependecy audit * ENH export types and a better style path * ENH refectoring to place the helpers in a dedicated place * ENH changed TypeScript moduleResolution from Node to Bundler * Update to Maplibre gl v3.5.2 (#63) * WIP point layer helper * WIP better clusters * WIP changed point helper options * ADD color ramps with builtins * WIP simpler set of options * ADD non linear resampling on color ramps * ADD color ramp doc * ADD outline color for points * ADD point outline settings * REM colorRamp arg and use only pointColor instead * DONE Map.addPoint * ADD radius and weight being both zoom and property driven * ADD zoom comensation param to point helper * FIX minmaxzoom and added MapTiler cloud source with uuid * DOC polyline helper section in readme * WIP readme * DOC done with documenting helpers * DOC color ramp doc * DOC fix * DOC * ENH cleaning unused types * ENH updating eslint * FIX dependecy audit * ENH export types and a better style path * ENH refectoring to place the helpers in a dedicated place * ENH changed TypeScript moduleResolution from Node to Bundler * UP now using Maplibre v3.5.2 (strict) --------- Co-authored-by: Craig O'Connor <[email protected]> Co-authored-by: Craig O'Connor <[email protected]>
maptiler · Oct 31, 2023 · 2c7e345 · 2c7e345
1 parent 41e7436
commit 2c7e345
Show file tree

Hide file tree

Showing 276 changed files with 148,903 additions and 33,149 deletions.
diff --git a/.eslintrc.cjs b/.eslintrc.cjs
@@ -1,10 +1,21 @@
+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",
+    "@typescript-eslint/no-explicit-any": "warn"
+  },
+  ignorePatterns: tsConfig.exclude,
+};
diff --git a/.gitignore b/.gitignore
@@ -105,5 +105,9 @@ typings/
 .DS_Store
 
 .vscode
+demos/tmp_*
+dist
+docs
+docsmd
+
 
-demos/tmp_*
diff --git a/.npmignore b/.npmignore
@@ -2,3 +2,5 @@ docs
 docsmd
 images
 scripts
+test
+demos
diff --git a/colorramp.md b/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.
diff --git a/demos/colorramps.html b/demos/colorramps.html
@@ -0,0 +1,96 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8"/>
+    <meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no"/>
+    <style>
+        body {
+            margin: 10px;
+            padding: 0;
+            font-family: sans-serif;
+        }
+
+        #colorramp-contain > * {
+            margin-bottom: 6px;
+            display:flex;
+        }
+
+        #colorramp-contain > div > span {
+            width: 185px;
+            height: 20px;
+            line-height: 20px;
+            background: #eeeeee;
+            text-align: center;
+            margin-right: 5px;
+            border-radius: 3px;
+            color: #04040496;
+            font-size: 12px;
+        }
+
+        #colorramp-contain > div > canvas {
+            width: calc(100% - 190px);
+            border-radius: 3px;
+        }
+
+
+        #colorramp-contain > div:nth-of-type(1) > canvas
+        {
+            border: 1px dashed #00000059;
+        } 
+
+
+    </style>
+</head>
+
+<body>
+
+    <div id="colorramp-contain"></div>
+
+    <script src="../dist/maptiler-sdk.umd.js"></script>
+<script>
+   const colorrampContainer = document.getElementById("colorramp-contain");
+
+   function displayColorRamp(name, colorramp, extraInfo = "") {
+        const canvas = colorramp.getCanvasStrip();
+        canvas.style.height = "20px";
+        // canvas.style.width = "100%";
+        // canvas.style.border = "1px dashed #00000059";
+
+        const bounds = colorramp.getBounds()
+
+        const div = document.createElement("div");
+        const descSpan = document.createElement("span");
+        // descSpan.innerHTML = `${name}${extraInfo} [${bounds.min}, ${bounds.max}]`;
+        descSpan.innerHTML = `${name}${extraInfo}`;
+
+
+        div.appendChild(descSpan);
+        div.appendChild(canvas);
+        colorrampContainer.appendChild( div );
+   }
+
+    Object.keys(maptilersdk.ColorRampCollection).forEach((k, i) => {
+        const colorramp = maptilersdk.ColorRampCollection[k];
+        displayColorRamp(k, colorramp);
+
+        // if (i === 0) return;
+
+        // displayColorRamp(k, colorramp.resample("ease-in-square"), ', resampling method: "ease-in-square"')
+        // displayColorRamp(k, colorramp.resample("ease-in-sqrt"), ', resampling method: "ease-in-sqrt"')
+        // displayColorRamp(k, colorramp.resample("ease-in-exp"), ', resampling method: "ease-in-exp"')
+
+        // displayColorRamp(k, colorramp.resample("ease-out-square"), ', resampling method: "ease-out-square"')
+        // displayColorRamp(k, colorramp.resample("ease-out-sqrt"), ', resampling method: "ease-out-sqrt"')
+        // displayColorRamp(k, colorramp.resample("ease-out-exp"), ', resampling method: "ease-out-exp"')
+
+
+
+        // colorrampContainer.appendChild( document.createElement("p") );
+    })
+
+
+
+
+</script>
+</body>
+</html>
diff --git a/demos/maptiler-sdk.css b/demos/maptiler-sdk.css
diff --git a/demos/maptiler-sdk.umd.js b/demos/maptiler-sdk.umd.js
diff --git a/demos/mountain.html b/demos/mountain.html
@@ -21,7 +21,7 @@
 
     </style>
 
-    <link rel="stylesheet" href="maptiler-sdk.css">
+    <link rel="stylesheet" href="../dist/maptiler-sdk.css">
   </head>
 
   <body>
@@ -33,7 +33,7 @@
 
     </div>
 
-    <script src ="maptiler-sdk.umd.js"></script>
+    <script src ="../dist/maptiler-sdk.umd.js"></script>
 
     <script>
       maptilersdk.config.apiKey = "YOUR_API_KEY";

diff --git a/demos/simple.html b/demos/simple.html
@@ -21,7 +21,7 @@
 
     </style>
 
-    <link rel="stylesheet" href="maptiler-sdk.css">
+    <link rel="stylesheet" href="../dist/maptiler-sdk.css">
   </head>
 
   <body>
@@ -33,7 +33,7 @@
 
     </div>
 
-    <script src ="maptiler-sdk.umd.js"></script>
+    <script src ="../dist/maptiler-sdk.umd.js"></script>
 
     <script>
       maptilersdk.config.apiKey = "YOUR_API_KEY";

diff --git a/demos/transform-request.html b/demos/transform-request.html
@@ -21,7 +21,7 @@
 
     </style>
 
-    <link rel="stylesheet" href="maptiler-sdk.css">
+    <link rel="stylesheet" href="../dist/maptiler-sdk.css">
   </head>
 
   <body>
@@ -33,7 +33,7 @@
 
     </div>
 
-    <script src ="maptiler-sdk.umd.js"></script>
+    <script src ="../dist/maptiler-sdk.umd.js"></script>
 
     <script>
       maptilersdk.config.apiKey = "YOUR_API_KEY";

diff --git a/dist/maptiler-sdk.css b/dist/maptiler-sdk.css