@maptoolkit/maplibre-scene3d-control 0.3.3 → 0.5.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 +32 -4
- package/dist/Scene3dControl.d.ts +23 -2
- package/dist/{maplibre-3d-layers-0.5.6.standalone.mjs → maplibre-3d-layers-0.6.0.standalone.mjs} +1751 -1378
- package/dist/maplibre-scene3d-control.js +33 -13
- package/dist/maplibre-scene3d-control.js.map +1 -1
- package/dist/maplibre-scene3d-control.standalone.js +37 -17
- package/dist/maplibre-scene3d-control.standalone.js.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -3,11 +3,11 @@
|
|
|
3
3
|
[](LICENSE)
|
|
4
4
|
[](https://www.npmjs.com/package/@maptoolkit/maplibre-scene3d-control)
|
|
5
5
|
|
|
6
|
-
A [MapLibre GL JS](https://maplibre.org/maplibre-gl-js/docs/) control plugin that adds the 3D scene of a Maptoolkit style: 3D buildings and glTF vegetation.
|
|
6
|
+
A [MapLibre GL JS](https://maplibre.org/maplibre-gl-js/docs/) control plugin that adds the 3D scene of a Maptoolkit style: 3D buildings, landmarks and glTF vegetation.
|
|
7
7
|
|
|
8
8
|
Maptoolkit styles name their scene in `metadata["maptoolkit:scene3d"]`. The control reads it whenever the style changes, so switching styles switches the scene. It draws the buildings with a `fill-extrusion` plus [`@maptoolkit/maplibre-3d-layers`](https://www.npmjs.com/package/@maptoolkit/maplibre-3d-layers) (`Fill3DLayer`, `GltfLayer`) and takes care of the rest:
|
|
9
9
|
|
|
10
|
-
- adds the buildings source with your API key (only for a scene with buildings),
|
|
10
|
+
- adds the buildings source with your API key (only for a scene with buildings or landmarks),
|
|
11
11
|
- puts the layers under the style's labels,
|
|
12
12
|
- keeps the tilt in the global state `pitch`, which the scene's opacity fades read,
|
|
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,
|
|
@@ -102,13 +102,41 @@ All values are plain MapLibre or maplibre-3d-layers options. Maptoolkit styles g
|
|
|
102
102
|
version: 1,
|
|
103
103
|
source: "https://…/buildings.json", // TileJSON of the buildings, without api_key
|
|
104
104
|
lod1: { filter, paint, layout }, // fill-extrusion on the source layer buildings2d
|
|
105
|
-
fill3d: { paint },
|
|
105
|
+
fill3d: { paint, extrusion }, // Fill3DLayer on the source layer buildings3d
|
|
106
|
+
landmarks: { position, filter, paint }, // the landmarks in buildings3d, a Fill3DLayer of their own
|
|
106
107
|
models: { tree_1: "https://static.maptoolkit.net/3d/models/…/Tree.gltf" },
|
|
107
108
|
gltf: [{ id, models: ["tree_1"], source: "mtk", "source-layer": "natural", filter, minzoom, layout, paint, lighting }],
|
|
108
109
|
}
|
|
109
110
|
```
|
|
110
111
|
|
|
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.
|
|
112
|
+
Every part is optional except `version` and `source`. `position` (on `lod1`, `fill3d`, `landmarks` 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.
|
|
113
|
+
|
|
114
|
+
`landmarks` draws the landmarks that the buildings tiles carry in the source layer `buildings3d` (features with `source: "landmark"`, each face with its `colour`) as a `Fill3DLayer` of their own, so they can have their own paint and their own place among the style's layers:
|
|
115
|
+
|
|
116
|
+
```js
|
|
117
|
+
landmarks: {
|
|
118
|
+
position: "water_waterway_label_rank_2",
|
|
119
|
+
filter: ["==", ["get", "source"], "landmark"], // the default
|
|
120
|
+
paint: { "fill-3d-color": ["to-color", ["get", "colour"], "#ffffff"], "fill-3d-opacity": 1 },
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
`fill3d` then leaves those features out: its filter becomes `["all", <its own filter, if any>, ["!", <the landmarks' filter>]]` (expression filters). A scene without `landmarks` keeps them in `fill3d`, drawn as plain buildings. `landmarks` works without `fill3d` and `lod1` too; the style's own 3D buildings (`hideLayers`) then stay. `paint` goes to the `Fill3DLayer` as it is, on `fill3d` as well, including the `fill-3d-ambient-occlusion-*` keys of maplibre-3d-layers ≥ 0.6 (older versions ignore them, and place a landmark like a building instead of rigidly at its anchor).
|
|
125
|
+
|
|
126
|
+
`fill3d.extrusion` lets the `Fill3DLayer` extrude the 2D footprints as well (maplibre-3d-layers ≥ 0.6.0, experimental), so that they get the shading and the fake ambient occlusion of the 3D buildings. The control passes it on as it is; hand the same footprints over by zoom, so that none is drawn twice:
|
|
127
|
+
|
|
128
|
+
```js
|
|
129
|
+
lod1: { maxzoom: 15, filter: ["!=", ["get", "extrude"], false], paint }, // native below z15
|
|
130
|
+
fill3d: {
|
|
131
|
+
extrusion: {
|
|
132
|
+
"source-layer": "buildings2d",
|
|
133
|
+
filter: ["all", ["!=", ["get", "extrude"], false], [">=", ["zoom"], 15]], // three.js from z15
|
|
134
|
+
},
|
|
135
|
+
paint,
|
|
136
|
+
},
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
The extrusion filter sees the zoom of the tile, not of the map. The extruded faces carry `type: "roof" | "wall"`, so a `fill-3d-color` keyed on `type` colours them like the 3D buildings.
|
|
112
140
|
|
|
113
141
|
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`.
|
|
114
142
|
|
package/dist/Scene3dControl.d.ts
CHANGED
|
@@ -44,11 +44,31 @@ export interface Scene3dManifest {
|
|
|
44
44
|
paint?: Record<string, Expression>;
|
|
45
45
|
layout?: Record<string, Expression>;
|
|
46
46
|
};
|
|
47
|
-
/**
|
|
47
|
+
/**
|
|
48
|
+
* `Fill3DLayer` on the source layer `buildings3d`. With `extrusion` it also extrudes the 2D footprints of a source
|
|
49
|
+
* layer of the same tiles (maplibre-3d-layers ≥ 0.6.0, experimental), so that they get its shading and fake ambient
|
|
50
|
+
* occlusion; hide the same footprints in `lod1` where it does, e.g. by zoom.
|
|
51
|
+
*/
|
|
48
52
|
fill3d?: {
|
|
49
53
|
position?: Scene3dPosition;
|
|
50
54
|
filter?: FilterSpecification;
|
|
51
55
|
paint?: Record<string, Expression>;
|
|
56
|
+
extrusion?: {
|
|
57
|
+
"source-layer": string;
|
|
58
|
+
filter?: FilterSpecification;
|
|
59
|
+
height?: Expression;
|
|
60
|
+
base?: Expression;
|
|
61
|
+
};
|
|
62
|
+
};
|
|
63
|
+
/**
|
|
64
|
+
* The landmarks in the source layer `buildings3d`, as a `Fill3DLayer` of their own: with their own paint and their
|
|
65
|
+
* own place among the style's layers. `filter` picks them (default `["==", ["get", "source"], "landmark"]`), and
|
|
66
|
+
* `fill3d` then leaves those features out.
|
|
67
|
+
*/
|
|
68
|
+
landmarks?: {
|
|
69
|
+
position?: Scene3dPosition;
|
|
70
|
+
filter?: FilterSpecification;
|
|
71
|
+
paint?: Record<string, Expression>;
|
|
52
72
|
};
|
|
53
73
|
/** Model library of the vegetation: id → glTF/glb URL. */
|
|
54
74
|
models?: Record<string, string>;
|
|
@@ -95,7 +115,8 @@ export type Scene3dControlEventType = {
|
|
|
95
115
|
type ResolvedOptions = Required<Omit<Scene3dControlOptions, "apiKey" | "scene" | "modelBase">> & Pick<Scene3dControlOptions, "apiKey" | "modelBase">;
|
|
96
116
|
/**
|
|
97
117
|
* A MapLibre GL JS control plugin that adds the 3D scene of a Maptoolkit style: 3D buildings
|
|
98
|
-
* (a `fill-extrusion` plus maplibre-3d-layers' `Fill3DLayer`)
|
|
118
|
+
* (a `fill-extrusion` plus maplibre-3d-layers' `Fill3DLayer`), the landmarks among them (a `Fill3DLayer`
|
|
119
|
+
* of their own) and glTF vegetation (`GltfLayer`).
|
|
99
120
|
*
|
|
100
121
|
* The scene comes from the style itself (`metadata["maptoolkit:scene3d"]`, written by style-family-js),
|
|
101
122
|
* so a style switch brings its own scene. The control keeps the tilt in the global state `pitch`
|