@maptiler/sdk 1.2.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maptiler/sdk",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "The Javascript & TypeScript map SDK tailored for MapTiler Cloud",
   "module": "dist/maptiler-sdk.mjs",
   "types": "dist/maptiler-sdk.d.ts",
@@ -74,10 +74,10 @@
     "xmldom": "^0.6.0"
   },
   "dependencies": {
-    "@maptiler/client": "^1.7.0",
+    "@maptiler/client": "^1.8.1",
     "events": "^3.3.0",
     "js-base64": "^3.7.4",
-    "maplibre-gl": "3.5.2",
+    "maplibre-gl": "4.1.2",
     "uuid": "^9.0.0"
   }
 }

package/readme.md

@@ -22,6 +22,8 @@ The **MapTiler SDK JS** extends MapLibre GL JS, exposes all its features, and ad
 In addition, the MapTiler SDK JS provides well-documented and easy-to-use wrapper functions to the [MapTiler Cloud API services](https://docs.maptiler.com/cloud/api) such as: geocoding, static maps, geolocation, as well as a search engine for coordinate reference systems and transforming coordinates from one CRS to another.
 > 📣 *__Note:__* If you need <ins>only the API Client library</ins> to use in a headless fashion and without any map display, check out [MapTiler Client JS](https://github.com/maptiler/maptiler-client-js) library for browser and NodeJS.
 
+![Lake Louise, Canada, with MapTiler Outdoor style](images/screenshots/lake-louise.jpg)
+
 # Install
 ```shell
 npm install --save @maptiler/sdk
@@ -51,7 +53,7 @@ const map = new maptilersdk.Map({
 });
 ```
 
-Alternativelly, the `apiKey` can be set as Map option intead of in the `config` object. Yet, this will still internally propagate to the `config` obejct:
+Alternativelly, the `apiKey` can be set as Map option intead of in the `config` object. Yet, this will still internally propagate to the `config` object:
 ```ts
 import * as maptilersdk from '@maptiler/sdk';
 
@@ -172,6 +174,9 @@ Here is the full list:
 - `MapStyle.DATAVIZ`, the perfect style for data visualization, with very little noise
   - `MapStyle.DATAVIZ.DARK` (variant)
   - `MapStyle.DATAVIZ.LIGHT` (variant)
+- `MapStyle.BACKDROP`, great style for data visualization when hillshading matters!
+  - `MapStyle.BACKDROP.DARK` (variant)
+  - `MapStyle.BACKDROP.LIGHT` (variant)
 - `MapStyle.BASIC` reference style for minimalist design and general purpose
   - `MapStyle.BASIC.DARK` (variant)
   - `MapStyle.BASIC.LIGHT` (variant)
@@ -392,16 +397,32 @@ Languages that are written right-to-left such as arabic and hebrew are fully sup
 
 # Custom Events and Map Lifecycle
 ## Events
-Since the SDK is fully compatible with MapLibre, [all these events](https://maplibre.org/maplibre-gl-js-docs/api/map/#map-events) are available, yet we have added one more: `loadWithTerrain`.  
+### The `ready` event
+The `ready` event happens just after the `load` event but waits that all the controls managed by the `Map` constructor are dealt with, some having an asynchronous logic to set up.  
+Since the `ready` event waits that all the basic controls are nicely positioned, it is **safer** to use `ready` than `load` if you plan to add other custom comtrols with the `.addControl()` method.
 
-The `loadWithTerrain` event is triggered only *once* in a `Map` instance lifecycle, when both the `load` event and the `terrain` event **with non-null terrain** are fired. 
+This event works exactely the same way as `load` and you can safely replace those by `"ready"`. Here is a usage example:
+
+```js
+const map = new maptilersdk.Map({
+  container: "map-container",
+});
+
+map.on("ready", (evt) => {
+  const terrainControl = new maptilersdk.MaptilerTerrainControl();
+  map.addControl(terrainControl);
+})
+```
+
+### The `loadWithTerrain` event
+The `loadWithTerrain` event is triggered only *once* in a `Map` instance lifecycle, when both the `ready` event and the `terrain` event **with non-null terrain** are fired. 
 
 **Why a new event?**
 When a map is instanciated with the option `terrain: true`, then MapTiler terrain is directly added to it and some animation functions such as `.flyTo()` or `.easeTo()` if started straight after the map initialization will actually need to wait a few milliseconds that the terrain is properly initialized before running.  
-Relying on the `load` event to run an animation with a map with terrain may fail in some cases for this reason, and this is why waiting for `loadWithTerrain` is safer in this particular situation.
+Relying on the `ready` or `load` event to run an animation with a map with terrain may fail in some cases for this reason, and this is why waiting for `loadWithTerrain` is safer in this particular situation.
 
 ## Lifecycle Methods
-The events `load` and `loadWithTerrain` are both called *at most once* and require a callback function to add more elements such as markers, layers, popups and data sources. Even though MapTiler SDK fully supports this logic, we have also included a *promise* logic to provide a more linear and less nested way to wait for a Map instance to be ready. Let's compare the two ways:
+The events `load`, `ready` and `loadWithTerrain` are both called *at most once* and require a callback function to add more elements such as markers, layers, popups and data sources. Even though MapTiler SDK fully supports this logic, we have also included a *promise* logic to provide a more linear and less nested way to wait for a Map instance to be usable. Let's compare the two ways:
 
 - Classic: with a callback on the `load` event:
 ```ts
@@ -494,9 +515,54 @@ async function init() {
 }
 ```
 
+And finally, the lifecycle method corresponding to the `ready` event:
+- Classic: with a callback on the `ready` event:
+```ts
+function init() {
+
+  const map = new Map({
+    container,
+    center: [2.34804, 48.85439], // Paris, France
+    zoom: 14,
+  });
+
+  // We wait for the event.
+  // Once triggered, the callback is ranin it's own scope.
+  map.on("ready", (evt) => {
+    // Adding a data source
+    map.addSource('my-gps-track-source', {
+      type: "geojson",
+      data: "https://example.com/some-gps-track.geojson",
+    });
+  })
+}
+```
+
+- Modern: with a promise returned by the method `.onReadyAsync()`, used in an `async` function:
+```ts
+async function init() {
+
+  const map = new Map({
+    container,
+    center: [2.34804, 48.85439], // Paris, France
+    zoom: 14,
+  });
+
+  // We wait for the promise to resolve.
+  // Once triggered, the rest of the init function runs
+  await map.onReadyAsync();
+
+  // Adding a data source
+  map.addSource('my-gps-track-source', {
+    type: "geojson",
+    data: "https://example.com/some-gps-track.geojson",
+  });
+}
+```
+
 We believe that the *promise* approach is better because it does not nest scopes and will allow for a linear non-nested stream of execution. It also corresponds to more modern development standards.
 
-> 📣 *__Note:__* Generally speaking, *promises* are not a go to replacement for all event+callback and are suitable only for events that are called only once in the lifecycle of a Map instance. This is the reason why we have decided to provide a *promise* equivalent only for the `load` and `loadWithTerrain` events.
+> 📣 *__Note:__* Generally speaking, *promises* are not a go to replacement for all event+callback and are suitable only for events that are called only once in the lifecycle of a Map instance. This is the reason why we have decided to provide a *promise* equivalent only for the `load`, `ready` and `loadWithTerrain` events but not for events that may be called multiple time such as interaction events.
 
 # Color Ramps
 A color ramp is a color gradient defined in a specific interval, for instance in [0, 1], and for any value within this interval will retrieve a color. They are defined by at least a color at each bound and usualy additional colors within the range.  
@@ -795,6 +861,16 @@ Turning off *zoom compensation* allows for more accurate adjustments to the visu
 
 All the other options are documented on a [our reference page](https://docs.maptiler.com/sdk-js/api/map/) and more examples are available [here](https://docs.maptiler.com/sdk-js/examples/).
 
+# Caching
+Starting from v2, MapTiler SDK introduced the **caching** of tiles and fonts served by MapTiler Cloud, which can represent a large chunk of the data being fetched when browsing a map. This caching leverages modern browsers caching API so it's well-managed and there is no risk of bloating! When we update **MapTiler Planet** or our **official styles**, the caching logic will detect it and automatically invalidate older versions of the tiles that were previously cached.
+
+Caching greatly improves the performance at load time and positively impact the user experience, for this reason, it is **enabled by default**. If for debugging purposes or a for a very specific use-case caching needs to be disabled, then it possible:
+
+```ts
+import { config } from "@maptiler/sdk";
+
+config.caching = false;
+```
 
 # Easy access to MapTiler Cloud API
 Our map SDK is not only about maps! We also provide plenty of wrapper to our API calls!
@@ -1061,3 +1137,132 @@ And voila!
 > 📣 *__Note:__* The GeoJSON for this track contains 9380 couples of coordinates, which is a lot! In order to send the track to MapTiler Cloud static maps API, the client simplifies the long paths while keeping a high degree of precision using a very fast [Ramer-Douglas-Peucker algorithm](https://en.wikipedia.org/wiki/Ramer%E2%80%93Douglas%E2%80%93Peucker_algorithm).
 
 Read more about bounded static maps on our official [API documentation](https://docs.maptiler.com/cloud/api/static-maps/#auto-fitted-image).
+
+## 🏔️ Elevation
+With the elevation API, it's possible to get the elevation in metter from any location. It's possible to lookup and compute elevation for a single location, to provide a batch of points, from a GeoJSON LineString or from a GeoJSON MultiLineString!
+
+> ℹ️ Under the hood, the elevation API is fueled by MapTiler Cloud's **RGB Terrain** raster tileset, which is a composite of many high-resolution DEMs from all over the world, currated and processed by our geodata team! The same dataset is also fueling our SDK's elevation (3D terrain) and the hillshading we use in many of our styles.
+
+> 📣 Note for **TypeScript** users: internaly, the elevation feature relies on some *GeoJSON* types definitions that can be found in this NPM package: `@types/geojson`. Namely `LineString`, `MultiLineString` and `Position`. It may improve your developer experience to also use these types. 
+
+Let's see how to use it:
+
+### At a single location
+```ts
+// Not mandatory, but it's to explain where the type comes from:
+import { Position } from "geojson";
+
+const montBlancPeak: Position = [6.864884, 45.832743];
+const elevatedPosition = await maptilersdk.elevation.at(montBlancPeak);
+```
+The returned value is also a *GeoJSON* `Position` array, but with three elements: `[lng, lat, elevation]`.
+
+Read more about elevation lookup for a single location in our [official documentation](https://docs.maptiler.com/client-js/elevation/#at).
+
+### Batch mode
+```ts
+// Not mandatory, but it's to explain where the type comes from:
+import { Position } from "geojson";
+
+const peaks: Position[] = [
+  [6.864884, 45.832743],   // Mont Blanc, Alps
+  [86.9250, 27.9881],      // Mount Everest, Himalayas
+  [-70.0109, -32.6532],    // Aconcagua, Andes
+  [-151.0064, 63.0695],    // Denali, Alaska
+  [37.3556, -3.0674],      // Mount Kilimanjaro
+  [42.4453, 43.3499],      // Mount Elbrus, Caucasus
+  [137.1595, -4.0784],     // Puncak Jaya, Sudirman Range
+  [-140.4055, 60.5672],    // Mount Logan, Saint Elias Mountains
+  [138.73111, 35.358055],  // Mount Fuji
+];
+
+const elevatedPeaks = await maptilersdk.elevation.batch(peaks);
+```
+
+Read more about elevation lookup for a batch of locations in our [official documentation](https://docs.maptiler.com/client-js/elevation/#batch).
+
+### From a GeoJSON LineString
+In the *GeoJSON* LineString case, it clones the entire structure and the positions arrays of the clone will contain three element: `[lng, lat, elevation]`. The original LineString is not mutated nor pointed at.
+
+```ts
+// Not mandatory, but it's to explain where the type comes from:
+import { LineString } from "geojson";
+
+
+const someLineString: LineString = {
+  type: "LineString",
+  coordinates: [[6.864884, 45.832743], [86.9250, 27.9881], [-70.0109, -32.6532]]
+};
+
+const someElevatedLineString = await maptilersdk.elevation.fromLineString(someLineString);
+// someElevatedLineString is also of type LineString
+```
+
+Read more about elevation lookup for a `LineString` in our [official documentation](https://docs.maptiler.com/client-js/elevation/#linestring).
+
+### From a GeoJSON MultiLineString
+In the *GeoJSON* MultiLineString case, it clones the entire structure and the positions arrays of the clone will contain three element: `[lng, lat, elevation]`. The original MultiLineString is not mutated nor pointed at.
+
+```ts
+// Not mandatory, but it's to explain where the type comes from:
+import { MultiLineString } from "geojson";
+
+
+const someMultiLineString: MultiLineString = {
+  type: "LineString",
+  coordinates: [
+    [[6.864884, 45.832743], [86.9250, 27.9881], [-70.0109, -32.6532]],
+    [[-151.0064, 63.0695], [37.3556, -3.0674], [42.4453, 43.3499]],
+    [[137.1595, -4.0784], [-140.4055, 60.5672], [138.73111, 35.358055]],
+  ]
+};
+
+const someElevatedMultiLineString = await maptilersdk.elevation.fromMultiLineString(someMultiLineString);
+// someElevatedMultiLineString is also of type MultiLineString
+```
+
+Read more about elevation lookup for a `MultiLineString` in our [official documentation](https://docs.maptiler.com/client-js/elevation/#multilinestring).
+
+### Caching
+In order to increase performance while reducing unnecessary elevation data fetching, the elevation tiles are cached. This is particularly important for the LineString and MultiLineString lookups because GeoJSON data are likely to come from a recorded or planned route, where position points are very close to one another.
+
+## 🧮 Math
+Some operations can be fairly repetitive: WGS84 to Mercator, WGS84 to *zxy* tile index, distance between two points with Haversine formula, etc. As a result, we have decided to expose a `math` package providing the most recurent feature, so that, just like us at MapTiler, you no longer need to copy-paste the same function from your previous project!
+
+The `math` package differs from the others in the sense that it does not call the MapTiler Cloud API, instead it operates fully on the machine it's running on.
+
+Here are some examples:
+
+```ts
+// Not mandatory, but it's to explain where the type comes from:
+import { Position } from "geojson";
+
+// Some constants
+const earthRadius = maptilersdk.math.EARTH_RADIUS;
+const earthCircumference = maptilersdk.math.EARTH_CIRCUMFERENCE;
+
+const montBlancPeakWgs84: Position = [6.864884, 45.832743];
+
+// From WGS84 to Mercator
+const montBlancPeakMerc = maptilersdk.math.wgs84ToMercator(montBlancPeakWgs84); // also of type Position
+
+// From Mercator to WGS84
+const montBlancPeakWgs84Again = maptilersdk.math.mercatorToWgs84(montBlancPeakMerc);
+
+// A great-circle distance in meter:
+const from: Position = /* ... */;
+const to: Position = /* ... */;
+const distance = maptilersdk.math.haversineDistanceWgs84(from, to);
+
+// Full distance of a route made of many positions
+const route: Position[] = /* ... */;
+const totalDistance = maptilersdk.math.haversineCumulatedDistanceWgs84(route);
+
+// Lon lat to tile index, given a zoom level. An [x, y] array is returned
+const tileXY = maptilersdk.math.wgs84ToTileIndex(montBlancPeakWgs84, 14);
+// Possible to have floating point tile indices with a third argument to `false`
+
+// and many more!
+```
+
+Please find out more about the math package in our [official documentation](https://docs.maptiler.com/client-js/math):

package/CHANGELOG.md

@@ -1,157 +0,0 @@
-# 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`
-  - `LogoControl`
-  - `ScaleControl`
-  - `FullscreenControl`
-  - `TerrainControl`
-  - `Popup`
-  - `Marker`
-  - `Style`
-  - `LngLat`
-  - `LngLatBounds`
-  - `MercatorCoordinate`
-  - `Evented`
-  - `AJAXError`
-  - `CanvasSource`
-  - `GeoJSONSource`
-  - `ImageSource`
-  - `RasterDEMTileSource`
-  - `RasterTileSource`
-  - `VectorTileSource`
-  - `VideoSource`
-  - `MapMLGL`
-- The following class have been extended to provide greater compatibility with SDK,s MapL
-  - `Popup`
-  - `Marker`
-  - `Style`
-  - `CanvasSource`
-  - `GeoJSONSource`
-  - `ImageSource`
-  - `RasterDEMTileSource`
-  - `RasterTileSource`
-  - `VectorTileSource`
-  - `VideoSource`
-  - `NavigationControl`
-  - `GeolocateControl`
-  - `AttributionControl`
-  - `LogoControl`
-  - `ScaleControl`
-  - `FullscreenControl`
-  - `TerrainControl`
-
-
-## 1.0.8
-### Bug Fixes
-- Since v1.0.7, the `Map` primary language (when custom) was no longer persistant on style update.
-
-## 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.
-
-## 1.0.6
-### New Features
-- Now exposing `MaptilerGeolocateControl` for external initialization if needed
-- Now exposing `MaptilerTerrain` for external initialization if needed
-
-## 1.0.5
-### New Features
-- Terrain elevation is now using MapTiler's `terrain-rgb-v2`
-
-## 1.0.4
-### Others
-- Improved the geolocate control behavior by not zooming out
-
-## 1.0.3
-### Bug Fixes
-- Fixed the usage of relative path style JSON (in `Map` constructor and `.setStyle()`)
-
-## 1.0.2
-### Bug Fixes
-- Fixed the dependency scheme of MapLibre import.
-
-## 1.0.1
-### Others
-- Reducing the NPM size by ignoring documentation images
-
-## 1.0.0
-### Others
-- First public version!

package/colorramp.md

@@ -1,93 +0,0 @@
-# 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.