@maptoolkit/maplibre-scene3d-control 0.2.0 → 0.3.1
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
|
|
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.
|
|
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.
|
|
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")
|
|
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
|
|
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
|