@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 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 @maptoolkit/maplibre-3d-layers three maplibre-gl
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. With an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap), point `maplibre-gl` at its module build and let the control load the standalone build of maplibre-3d-layers, which includes three.js:
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.1.0/dist/maplibre-scene3d-control.js";
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")` | Loads the 3D library, e.g. from a CDN. |
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`. A layer goes under the style's labels unless it says `position: "top"`. 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
+ 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, `@maptoolkit/maplibre-3d-layers` ≥ 0.5.1 and three.js ≥ 0.160 (peer dependencies of the 3D library).
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
@@ -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
- /** Where a layer of the scene goes: under the style's labels (default) or on top of everything. */
5
- export type Scene3dPosition = "below-labels" | "top";
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
- /** Custom layers added with `position: "top"`. */
127
- private topIds;
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
- /** The buildings source and the native layers, before `anchor` (default: under the labels). */
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;