@maptoolkit/maplibre-scene3d-control 0.1.2 → 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 +15 -12
- package/dist/Scene3dControl.d.ts +14 -5
- package/dist/maplibre-3d-layers-0.5.4.standalone.mjs +18996 -0
- package/dist/maplibre-scene3d-control.js +11 -11
- package/dist/maplibre-scene3d-control.js.map +1 -1
- package/dist/maplibre-scene3d-control.standalone.js +280 -0
- package/dist/maplibre-scene3d-control.standalone.js.map +1 -0
- package/dist/standalone.d.ts +12 -0
- package/package.json +10 -5
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
|
|
@@ -107,13 +108,13 @@ All values are plain MapLibre or maplibre-3d-layers options. Maptoolkit styles g
|
|
|
107
108
|
}
|
|
108
109
|
```
|
|
109
110
|
|
|
110
|
-
Every part is optional except `version` and `source`.
|
|
111
|
+
Every part is optional except `version` and `source`. `position` (on `lod1`, `fill3d` and every `gltf` layer) decides where a layer goes: under the style's labels by default (`"below-labels"`, right below the style's first symbol layer), on top of everything with `"top"`, or right below the style layer whose id it names, e.g. `position: "water_waterway_label_rank_4"`. A layer id the style lacks falls back to under the labels, with a console warning. The position only matters against symbol layers (labels, icons): fills and lines always end up under the 3D layers. Vegetation needs the source it names in the style (`mtk` in Maptoolkit styles); a layer whose source the style lacks is left out with a warning.
|
|
111
112
|
|
|
112
113
|
MapLibre ignores a diffed `setStyle` that changes nothing but the metadata. A scene that changes on its own, with the rest of the style unchanged, therefore never reaches the control that way: pass it with `setScene()` or use `setStyle` with `diff: false`.
|
|
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
|
package/dist/Scene3dControl.d.ts
CHANGED
|
@@ -1,8 +1,13 @@
|
|
|
1
1
|
import { Evented, ControlPosition, CustomLayerInterface, FilterSpecification, IControl, Map as MaplibreMap, MapLibreEvent } from 'maplibre-gl';
|
|
2
2
|
/** Root metadata key under which a Maptoolkit style carries its 3D scene. */
|
|
3
3
|
export declare const SCENE3D_METADATA_KEY = "maptoolkit:scene3d";
|
|
4
|
-
/**
|
|
5
|
-
|
|
4
|
+
/**
|
|
5
|
+
* Where a layer of the scene goes: under the style's labels (`"below-labels"`, the default: right below its first
|
|
6
|
+
* symbol layer), on top of everything (`"top"`), or right below the style layer with that id. The position only
|
|
7
|
+
* decides what draws over the 3D among symbol layers (labels, icons); fills and lines always end up under it. A
|
|
8
|
+
* layer id the style lacks falls back to `"below-labels"`.
|
|
9
|
+
*/
|
|
10
|
+
export type Scene3dPosition = "below-labels" | "top" | (string & {});
|
|
6
11
|
type Expression = unknown;
|
|
7
12
|
/** One glTF vegetation layer: maplibre-3d-layers `GltfLayer` options, `models` as ids of the scene's model library. */
|
|
8
13
|
export interface Scene3dGltfLayer {
|
|
@@ -123,8 +128,8 @@ export declare class Scene3dControl extends Evented<Scene3dControlEventType> imp
|
|
|
123
128
|
private sceneKey;
|
|
124
129
|
/** Whether the buildings source of the current scene has loaded (its TileJSON answered). */
|
|
125
130
|
private sourceOk;
|
|
126
|
-
/**
|
|
127
|
-
private
|
|
131
|
+
/** The position each custom layer was added with (`"below-labels"` when the scene names none). */
|
|
132
|
+
private customPosition;
|
|
128
133
|
/** The terrain the 3D layers were built with (source and exaggeration), see onTerrain. */
|
|
129
134
|
private terrainKey;
|
|
130
135
|
constructor(options?: Scene3dControlOptions);
|
|
@@ -162,8 +167,12 @@ export declare class Scene3dControl extends Evented<Scene3dControlEventType> imp
|
|
|
162
167
|
private sourceId;
|
|
163
168
|
/** The id of the style's first symbol layer: the scene goes right below it. */
|
|
164
169
|
private labelsAnchor;
|
|
170
|
+
/** The layer a scene layer goes below for `position`: none for "top", the style layer it names, else `anchor`. */
|
|
165
171
|
private beforeFor;
|
|
166
|
-
/**
|
|
172
|
+
/**
|
|
173
|
+
* The buildings source and the native layers, each below the layer its position names. `place` can pick another
|
|
174
|
+
* layer for a position (restoreNative: the 3D layers with the same position).
|
|
175
|
+
*/
|
|
167
176
|
private addNative;
|
|
168
177
|
/** After a diffed setStyle with the same scene: put back the source and native layers, keep the 3D layers. */
|
|
169
178
|
private restoreNative;
|