@maptoolkit/maplibre-scene3d-control 0.3.3 → 0.5.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
@@ -3,11 +3,11 @@
3
3
  [![License](https://img.shields.io/npm/l/@maptoolkit/maplibre-scene3d-control?style=plastic)](LICENSE)
4
4
  [![Version](https://img.shields.io/npm/v/@maptoolkit/maplibre-scene3d-control?style=plastic)](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,
@@ -103,12 +103,25 @@ All values are plain MapLibre or maplibre-3d-layers options. Maptoolkit styles g
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
105
  fill3d: { paint }, // 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).
112
125
 
113
126
  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
127
 
@@ -50,6 +50,16 @@ export interface Scene3dManifest {
50
50
  filter?: FilterSpecification;
51
51
  paint?: Record<string, Expression>;
52
52
  };
53
+ /**
54
+ * The landmarks in the source layer `buildings3d`, as a `Fill3DLayer` of their own: with their own paint and their
55
+ * own place among the style's layers. `filter` picks them (default `["==", ["get", "source"], "landmark"]`), and
56
+ * `fill3d` then leaves those features out.
57
+ */
58
+ landmarks?: {
59
+ position?: Scene3dPosition;
60
+ filter?: FilterSpecification;
61
+ paint?: Record<string, Expression>;
62
+ };
53
63
  /** Model library of the vegetation: id → glTF/glb URL. */
54
64
  models?: Record<string, string>;
55
65
  gltf?: Scene3dGltfLayer[];
@@ -95,7 +105,8 @@ export type Scene3dControlEventType = {
95
105
  type ResolvedOptions = Required<Omit<Scene3dControlOptions, "apiKey" | "scene" | "modelBase">> & Pick<Scene3dControlOptions, "apiKey" | "modelBase">;
96
106
  /**
97
107
  * 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`) and glTF vegetation (`GltfLayer`).
108
+ * (a `fill-extrusion` plus maplibre-3d-layers' `Fill3DLayer`), the landmarks among them (a `Fill3DLayer`
109
+ * of their own) and glTF vegetation (`GltfLayer`).
99
110
  *
100
111
  * The scene comes from the style itself (`metadata["maptoolkit:scene3d"]`, written by style-family-js),
101
112
  * so a style switch brings its own scene. The control keeps the tilt in the global state `pitch`