Skip to content

Scene3D Control

@maptoolkit/maplibre-scene3d-control adds the 3D scene of a style to a MapLibre GL JS map: buildings with roof shapes from zoom 15, official 3D city models where they exist, for example in Vienna, and 3D trees. The Street and Summer community styles carry a scene. The other five styles have none, so the control adds nothing on them.

Install

npm install @maptoolkit/maplibre-scene3d-control maplibre-gl

npm installs @maptoolkit/maplibre-3d-layers and three.js with the control. You do not import them yourself.

Usage

import * as maplibregl from "maplibre-gl";
import { Scene3dControl } from "@maptoolkit/maplibre-scene3d-control";
import "@maptoolkit/maplibre-scene3d-control/style.css";

const map = new maplibregl.Map({
  container: "map",
  style: "https://styles.maptoolkit.org/street.json",
  center: [16.3731, 48.2085],
  zoom: 16,
  pitch: 70,
  maxPitch: 85,
  canvasContextAttributes: { antialias: true }, // smooth edges on distant trees
});

map.addControl(new Scene3dControl());

The community buildings source needs no API key, so leave out the control’s apiKey option. The control has no button by default; pass button: true to add one that switches the scene on and off. The buildings get more opaque as you tilt the map; looking straight down at zoom 15 and below, they are hidden.

Without a bundler

Load the control’s standalone build from a CDN and map maplibre-gl in an import map. The standalone build loads the 3D library, three.js included, from next to itself, so there is nothing else to load:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/maplibre-gl@6.16.0/dist/maplibre-gl.css" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@maptoolkit/maplibre-scene3d-control@0.5.2/dist/maplibre-scene3d-control.css" />

<script type="importmap">
  {
    "imports": {
      "maplibre-gl": "https://cdn.jsdelivr.net/npm/maplibre-gl@6.16.0/dist/maplibre-gl.mjs"
    }
  }
</script>
<script type="module">
  import * as maplibregl from "maplibre-gl";
  import { Scene3dControl } from "https://cdn.jsdelivr.net/npm/@maptoolkit/maplibre-scene3d-control@0.5.2/dist/maplibre-scene3d-control.standalone.js";

  const map = new maplibregl.Map({
    container: "map",
    style: "https://styles.maptoolkit.org/street.json",
    center: [16.3731, 48.2085],
    zoom: 16,
    pitch: 70,
    canvasContextAttributes: { antialias: true },
  });
  map.addControl(new Scene3dControl());
</script>

Do not load three.js a second time on the same page. The standalone build brings its own copy.

More

  • 3D Buildings explains the scene in the style, the buildings tileset and what the other libraries can show.
  • The Scene3D Control reference on docs.maptoolkit.com describes the options, methods, events and styling.

License

The Scene3D Control is open source under the BSD 3-Clause License.