@maptoolkit/maplibre-scene3d-control 0.5.1 → 0.6.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
@@ -10,7 +10,8 @@ Maptoolkit styles name their scene in `metadata["maptoolkit:scene3d"]`. The cont
10
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
- - 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,
13
+ - rebuilds the layers after a style change; a diffed `setStyle` that keeps the scene only puts back what the diff dropped and keeps the 3D layers,
14
+ - leaves the 3D layers in place when the terrain is switched on, off or changed: they move onto the new heights themselves, without loading again,
14
15
  - loads the 3D library (with three.js) only once the map reaches zoom 12.
15
16
 
16
17
  The 3D library comes with the control: you install and import only the control.
@@ -123,10 +124,10 @@ landmarks: {
123
124
 
124
125
  `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
 
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
+ `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 the zoom of the tile, so that none is drawn twice:
127
128
 
128
129
  ```js
129
- lod1: { maxzoom: 15, filter: ["!=", ["get", "extrude"], false], paint }, // native below z15
130
+ lod1: { filter: ["all", ["!=", ["get", "extrude"], false], ["<", ["zoom"], 15]], paint }, // native in tiles below z15
130
131
  fill3d: {
131
132
  extrusion: {
132
133
  "source-layer": "buildings2d",
@@ -136,7 +137,7 @@ fill3d: {
136
137
  },
137
138
  ```
138
139
 
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.
140
+ Both filters see the zoom of the tile, not of the map. Don't stop `lod1` with `maxzoom` instead: that is the map zoom, and a pitched view at zoom 15+ still loads z13/z14 tiles in the distance, which then get no buildings from either layer. The extruded faces carry `type: "roof" | "wall"`, so a `fill-3d-color` keyed on `type` colours them like the 3D buildings.
140
141
 
141
142
  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`.
142
143
 
@@ -47,7 +47,7 @@ export interface Scene3dManifest {
47
47
  /**
48
48
  * `Fill3DLayer` on the source layer `buildings3d`. With `extrusion` it also extrudes the 2D footprints of a source
49
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.
50
+ * occlusion; leave the same footprints out of `lod1` where it does, by a filter on the tile zoom (not `maxzoom`).
51
51
  */
52
52
  fill3d?: {
53
53
  position?: Scene3dPosition;
@@ -121,7 +121,8 @@ type ResolvedOptions = Required<Omit<Scene3dControlOptions, "apiKey" | "scene" |
121
121
  * The scene comes from the style itself (`metadata["maptoolkit:scene3d"]`, written by style-family-js),
122
122
  * so a style switch brings its own scene. The control keeps the tilt in the global state `pitch`
123
123
  * that the scene's opacity fades read, puts the layers under the style's labels, rebuilds them after
124
- * style and terrain changes and loads the 3D library only when the map gets close enough.
124
+ * a style change and loads the 3D library only when the map gets close enough. A terrain that is
125
+ * switched on, off or changed leaves the 3D layers as they are: they move onto it themselves.
125
126
  */
126
127
  export declare class Scene3dControl extends Evented<Scene3dControlEventType> implements IControl {
127
128
  readonly options: ResolvedOptions;
@@ -151,8 +152,6 @@ export declare class Scene3dControl extends Evented<Scene3dControlEventType> imp
151
152
  private sourceOk;
152
153
  /** The position each custom layer was added with (`"below-labels"` when the scene names none). */
153
154
  private customPosition;
154
- /** The terrain the 3D layers were built with (source and exaggeration), see onTerrain. */
155
- private terrainKey;
156
155
  constructor(options?: Scene3dControlOptions);
157
156
  getDefaultPosition(): ControlPosition;
158
157
  onAdd(map: MaplibreMap): HTMLElement;
@@ -178,7 +177,6 @@ export declare class Scene3dControl extends Evented<Scene3dControlEventType> imp
178
177
  private onStyleLoad;
179
178
  private onStyleData;
180
179
  private syncWithStyle;
181
- private onTerrain;
182
180
  private onZoom;
183
181
  /** `["global-state", "pitch"]` for the scene's opacity fades. Whole degrees: each change is a style update. */
184
182
  private syncPitch;