@maptoolkit/maplibre-scene3d-control 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -13,12 +13,16 @@ Maptoolkit styles name their scene in `metadata["maptoolkit:scene3d"]`. The cont
13
13
  - rebuilds the layers after a style or terrain change; a diffed `setStyle` that keeps the scene only puts back what the diff dropped and keeps the 3D layers,
14
14
  - loads the 3D library (with three.js) only once the map reaches zoom 12.
15
15
 
16
+ The 3D library comes with the control: you install and import only the control.
17
+
16
18
  ## Install
17
19
 
18
20
  ```bash
19
- npm install @maptoolkit/maplibre-scene3d-control @maptoolkit/maplibre-3d-layers three maplibre-gl
21
+ npm install @maptoolkit/maplibre-scene3d-control maplibre-gl
20
22
  ```
21
23
 
24
+ `@maptoolkit/maplibre-3d-layers` and three.js are dependencies of the control and come along. A bundler puts the 3D library into a file of its own that the control loads on demand.
25
+
22
26
  ## Usage
23
27
 
24
28
  ```js
@@ -42,7 +46,7 @@ That is all: the scene of the style appears from zoom 12, and a style switch bri
42
46
 
43
47
  ### Without a bundler
44
48
 
45
- The package is ESM-only. With an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap), point `maplibre-gl` at its module build and let the control load the standalone build of maplibre-3d-layers, which includes three.js:
49
+ The package is ESM-only. Load its standalone build, `dist/maplibre-scene3d-control.standalone.js` (also exported as `@maptoolkit/maplibre-scene3d-control/standalone`). Next to it in `dist/` lies the standalone build of maplibre-3d-layers with three.js included, `maplibre-3d-layers-<version>.standalone.mjs`, and the control loads it from there once the map reaches zoom 12. Point `maplibre-gl` at its module build with an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap), as for every MapLibre 6 plugin:
46
50
 
47
51
  ```html
48
52
  <script type="importmap">
@@ -50,18 +54,15 @@ The package is ESM-only. With an [import map](https://developer.mozilla.org/en-U
50
54
  </script>
51
55
  <script type="module">
52
56
  import * as maplibregl from "maplibre-gl";
53
- import { Scene3dControl } from "https://unpkg.com/@maptoolkit/maplibre-scene3d-control@^0.1.0/dist/maplibre-scene3d-control.js";
57
+ import { Scene3dControl } from "https://unpkg.com/@maptoolkit/maplibre-scene3d-control@^0.3.0/dist/maplibre-scene3d-control.standalone.js";
54
58
 
55
59
  const map = new maplibregl.Map({ container: "map", style, center, zoom, pitch: 70, canvasContextAttributes: { antialias: true } });
56
- map.addControl(
57
- new Scene3dControl({
58
- apiKey: "YOUR_KEY",
59
- library: () => import("https://unpkg.com/@maptoolkit/maplibre-3d-layers@^0.5.1/dist/maplibre-3d-layers.standalone.mjs"),
60
- }),
61
- );
60
+ map.addControl(new Scene3dControl({ apiKey: "YOUR_KEY" }));
62
61
  </script>
63
62
  ```
64
63
 
64
+ The file name of the bundled library carries its version, so a new release is a new URL and never meets a cached old copy. To self-host, copy both files and keep them side by side.
65
+
65
66
  ## Options
66
67
 
67
68
  | Option | Type | Default | Description |
@@ -73,7 +74,7 @@ The package is ESM-only. With an [import map](https://developer.mozilla.org/en-U
73
74
  | `minzoom` | `number` | `12` | Zoom from which the 3D library is loaded. The buildings source has no tiles below 12. |
74
75
  | `hideLayers` | `string[]` | `["building_3d", "building_3d_multicolored"]` | Style layers hidden while the scene's buildings are shown, e.g. a style's own 3D buildings. Hidden only once the buildings source has loaded: without a working API key the style keeps them. |
75
76
  | `modelBase` | `string` | document base URL | Base for relative model URLs. |
76
- | `library` | `() => Promise<Scene3dLibrary>` | `import("@maptoolkit/maplibre-3d-layers")` | Loads the 3D library, e.g. from a CDN. |
77
+ | `library` | `() => Promise<Scene3dLibrary>` | the bundled 3D library | Loads the 3D library. Default: `import("@maptoolkit/maplibre-3d-layers")`, in the standalone build the copy next to it. Pass a loader to use another build or version. |
77
78
  | `idPrefix` | `string` | `"scene3d-"` | Prefix of the source and layer ids the control adds. |
78
79
 
79
80
  ## Methods
@@ -113,7 +114,7 @@ MapLibre ignores a diffed `setStyle` that changes nothing but the metadata. A sc
113
114
 
114
115
  ## Requirements
115
116
 
116
- - MapLibre GL JS ≥ 6, `@maptoolkit/maplibre-3d-layers` ≥ 0.5.1 and three.js ≥ 0.160 (peer dependencies of the 3D library).
117
+ - MapLibre GL JS ≥ 6 (peer dependency). `@maptoolkit/maplibre-3d-layers` and three.js ≥ 0.160 come with the control.
117
118
  - A Maptoolkit API key with access to the buildings source.
118
119
  - A style with a scene, or a scene passed with `scene`. Vegetation also needs the style's `mtk` source.
119
120
 
@@ -137,6 +138,8 @@ npm run typecheck
137
138
  npm run build
138
139
  ```
139
140
 
141
+ Releases go through changesets: a merge to `main` with a changeset opens "Version Packages", and merging that publishes. A release of `@maptoolkit/maplibre-3d-layers` needs no hand: [`bump-maptoolkit-packages.yml`](.github/workflows/bump-maptoolkit-packages.yml) opens a PR that raises the bundled version and versions the control in one go (same bump level as the library), merges it once CI is green, and the merge publishes the control and notifies its consumers.
142
+
140
143
  ## License
141
144
 
142
145
  BSD-3-Clause