@maptiler/sdk 1.2.1 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maptiler/sdk",
-  "version": "1.2.1",
+  "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.8.0",
+    "@maptiler/client": "^1.8.1",
     "events": "^3.3.0",
     "js-base64": "^3.7.4",
-    "maplibre-gl": "3.6.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)
@@ -856,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!

package/CHANGELOG.md

@@ -1,168 +0,0 @@
-# MapTiler SDK Changelog
-
-## DEVEL
-### New Features
-### Bug Fixes
-### Others
-
-## 1.2.1
-### New Features
-- Elevation lookup at `maptilersdk.elevation` with the function `.at()`, `.batch()` and for geojson payloads. From the update of the MapTiler Client library
-- the new `ready` event. Called only once after `load` and wait for all the controls managed by the Map constructor to be dealt with (as one relies on async logic)
-- the new Map lifecycle method `.onReadyAsync()` corresponding to a promise-based equivalent of the the `ready` event.
-### Bug Fixes
-- The index now exposes the geocoding option types from the Client library
-### Others
-- Update of the Maptiler Client library to v1.8.0 that brings the elevation and math module
-- Update with the last version of MapLibre GL JS (v3.6.2)
-
-## 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.