MapLibre GL 3D Tiles

A MapLibre GL JS control for rendering 3D Tiles with three.js and 3d-tiles-renderer. It provides a standalone IControl, a React wrapper, Vite examples, a Docker example server, and a GeoLibre plugin bundle.

Features

• MapLibre custom 3D layer backed by three.js
• 3D Tiles rendering through 3d-tiles-renderer
• GLTF, Draco, and KTX2 loader support
• Collapsible MapLibre control with URL, altitude offset, visibility, load, remove, and fly-to actions
• Multiple tilesets on the same map with per-tileset visibility, fly-to, and remove actions
• TypeScript API and React wrapper
• GeoLibre plugin zip build

Installation

npm install maplibre-gl-3d-tiles

Vanilla Usage

import maplibregl from 'maplibre-gl';
import { ThreeDTilesControl } from 'maplibre-gl-3d-tiles';
import 'maplibre-gl-3d-tiles/style.css';
import 'maplibre-gl/dist/maplibre-gl.css';

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://tiles.openfreemap.org/styles/bright',
  center: [0, 0],
  zoom: 1,
  pitch: 60,
  maxPitch: 80,
  canvasContextAttributes: { antialias: true },
});

map.on('load', () => {
  const control = new ThreeDTilesControl({
    collapsed: false,
    layerName: 'AGI Headquarters',
    tilesetUrl: 'https://pelican-public.s3.amazonaws.com/3dtiles/agi-hq/tileset.json',
    altitudeOffset: -300,
  });

  map.addControl(control, 'top-right');
  void control.loadTileset();
  void control.loadTileset('https://example.com/another/tileset.json', {
    layerName: 'Second tileset',
    beforeId: 'place-labels',
    altitudeOffset: 0,
  });
});

React Usage

import { useEffect, useRef, useState } from 'react';
import maplibregl, { Map } from 'maplibre-gl';
import {
  ThreeDTilesControlReact,
  useThreeDTilesState,
} from 'maplibre-gl-3d-tiles/react';
import 'maplibre-gl-3d-tiles/style.css';

function App() {
  const mapContainer = useRef<HTMLDivElement>(null);
  const [map, setMap] = useState<Map | null>(null);
  const { state, setState } = useThreeDTilesState({ collapsed: false });

  useEffect(() => {
    if (!mapContainer.current) return;

    const mapInstance = new maplibregl.Map({
      container: mapContainer.current,
      style: 'https://tiles.openfreemap.org/styles/bright',
      center: [0, 0],
      zoom: 1,
      pitch: 60,
      maxPitch: 80,
      canvasContextAttributes: { antialias: true },
    });

    mapInstance.on('load', () => setMap(mapInstance));
    return () => mapInstance.remove();
  }, []);

  return (
    <>
      <div ref={mapContainer} style={{ width: '100%', height: '100vh' }} />
      {map && (
        <ThreeDTilesControlReact
          map={map}
          collapsed={state.collapsed}
          onStateChange={(nextState) => setState(nextState)}
        />
      )}
    </>
  );
}

API

ThreeDTilesControl

Constructor options include:

| Option | Type | Default | | --- | --- | --- | | tilesetUrl | string | MapLibre example tileset | | sampleData | ThreeDTilesSampleDataset[] | [] (hides the "Load sample data" dropdown) | | sampleDataLabel | string | 'Load sample data...' | | layerName | string | 3D Tiles | | beforeId | string | undefined | | altitudeOffset | number | -300 | | flyToOnLoad | boolean | true | | visible | boolean | true | | requestHeaders | Record<string, string> | undefined | | layerId | string | maplibre-gl-3d-tiles | | collapsed | boolean | true | | panelWidth | number | 360 | | position | MapLibre control position | top-right |

For authenticated tilesets, pass requestHeaders (e.g. { Authorization: 'ApiKey <key>' }). The headers are applied to the tileset's fetch options, so the tileset JSON and every tile request carry them. In the control panel, headers can also be entered in the "Request headers" field, one Name: Value pair per line.

Main methods:

• loadTileset(url?, options?)
• removeTileset(id?), removes all tilesets when no id is passed
• setVisible(visible, id?)
• flyToTileset(id?)
• getState()
• setState(state)
• toggle(), expand(), collapse()
• on(event, handler), off(event, handler)

Events:

collapse, expand, statechange, loadstart, load, error, remove, visibilitychange

Development

npm install
npm run dev
npm test
npm run build
npm run build:examples

GeoLibre Plugin Bundle

npm run package:geolibre

This creates:

geolibre-plugin/maplibre-gl-3d-tiles-0.1.0.zip

Docker

docker build -t maplibre-gl-3d-tiles .
docker run -p 8080:80 maplibre-gl-3d-tiles

Open http://localhost:8080/maplibre-gl-3d-tiles/ to view the examples.