maplibre-three-plugin

maplibre-three-plugin is a bridge plugin that cleverly connects MapLibre GL JS with Three.js, enabling developers to implement 3D rendering and animation on maps.

Install

npm install @dvt3d/maplibre-three-plugin
----------------------------------------
yarn add @dvt3d/maplibre-three-plugin

Quickly Start

maplibre-three-plugin depends on three, please make sure three is installed before using it.

<div id="map-container"></div>

import maplibregl from 'maplibre-gl'
import * as THREE from 'three'
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js'
import * as MTP from '@dvt3d/maplibre-three-plugin'

const map = new maplibregl.Map({
  container: 'map-container', // container id
  style: 'https://api.maptiler.com/maps/basic-v2/style.json?key=get_access_key',
  zoom: 18,
  center: [148.9819, -35.3981],
  pitch: 60,
  canvasContextAttributes: { antialias: true },
  maxPitch: 85,
})

//init three scene
const mapScene = new MTP.MapScene(map)

//add light
mapScene.addLight(new THREE.AmbientLight())

// add model
const glTFLoader = new GLTFLoader()

glTFLoader.load('./assets/34M_17/34M_17.gltf', (gltf) => {
  let rtcGroup = MTP.Creator.createRTCGroup([148.9819, -35.39847])
  rtcGroup.add(gltf.scene)
  mapScene.addObject(rtcGroup)
})

Examples

| | | | |
|:------------------------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------------:|:--------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------------:| | model | sun-light | point | point-collection | | | | | |
| billboard | div-icon | 3d-tiles | 3d-tiles-osgb |
| | | | | | 3d-tiles-cesium-ion | 3d-gs-cesium-ion | 3d-gs-splat | heat-map |

Docs

MapScene

examples

const mapScene = new MapScene(map)

creation

• constructor(map,[options])
  • params
    • {Map} map : map instance
    • {Object} options : config

// config
Object({
  /**
   * Existing THREE.Scene instance.
   * If not provided, an internal default scene will be created.
   */
  scene: null,

  /**
   * Existing THREE.Camera instance.
   * If not provided, an internal default camera will be created.
   */
  camera: null,

  /**
   * Existing THREE.WebGLRenderer instance.
   * If not provided, an internal default renderer will be created.
   */
  renderer: null,

  /**
   * Whether to preserve the drawing buffer.
   * When enabled, the canvas content will be retained after rendering,
   * which is useful for screenshots or readPixels operations.
   * Note: Enabling this may have a performance impact.
   */
  preserveDrawingBuffer: false,

  /**
   * Whether to enable post-processing rendering.
   * When enabled, Three.js content will be rendered through
   * an offscreen render target before being composited onto the map.
   * When disabled, Three.js renders directly into the shared MapLibre canvas
   * for maximum performance and stability.
   */
  enablePostProcessing: false,

  /**
   * Custom frame render loop.
   *
   * This function will be called every frame.
   * If not provided, the internal default render loop will be used.
   *
   * ⚠️ Note:
   * Providing a custom renderLoop means you take full control
   * of the render lifecycle. The built-in rendering pipeline
   * will be bypassed.
   *
   * As a result, the following internal event hooks will
   * NOT be triggered automatically:
   *
   * - preReset
   * - postReset
   * - preRender
   * - postRender
   *
   * If needed, you must manually call the corresponding logic
   * inside your custom renderLoop.
   *
   * @param {MapScene} ins - The current MapScene instance
   */
  renderLoop: (ins) => {
  }
})

event hooks

These hooks are only triggered when using the internal render loop.

• preReset : A hook that calls renderer.resetState before each animation frame
• postReset: A hook that calls renderer.resetState after each animation frame
• preRender: A hook that calls renderer.render before each animation frame
• postRender: A hook that calls renderer.render after each animation frame

properties

• {maplibregl.Map} map : readonly
• {HTMLCanvasElement} canvas : readonly
• {THREE.Camera} camera : readonly
• {THREE.Sence} scene : readonly
• {THREE.Group} lights: readonly
• {THREE.Group} world : readonly
• {THREE.WebGLRenderer} renderer : readonly
• {EffectComposer} composer : readonly
• {RenderPass} renderPass : readonly
• {OutputPass} outputPass : readonly

methods

• addLight(light)

  Add light to the scene, support custom light objects, but the custom light objects need to support the delegate property, and the delegate type is THREE.Object3D

  • params
    • {THREE.Object3D | Sun | CustomLight } light
  • returns
    • this

• removeLight(light)

  Remove light from the scene

  • params
    • {THREE.Object3D | Sun | CustomLight } light
  • returns
    • this

• addObject(object)

  Add an object to world，support custom object, but the custom object need to support the delegate property, and the delegate type is THREE.Object3D

  • params
    • {THREE.Object3D | CustomObject} object
  • returns
    • this

• removeObject(object)

  Remove an object from world

  • params
    • {THREE.Object3D | CustomObject} object
  • returns
    • this

• flyTo(target,[completed],[duration])

  Fly the map to the provided target over a period of time, the completion callback will be triggered when the flight is complete, the target needs to contain the position property

  • params
    • {THREE.Object3D | CustomObject} target
    • {Function} completed
    • {Number} duration
  • returns
    • this

• zoomTo(target,[completed])

  Zoom the map to the provided target

  • params
    • {Ojbect} target
    • {Function} completed
  • returns
    • this

• on(type,callback)

  Registers an event listener for the specified event type

  • params
    • {String} type
    • {Function} callback
  • returns
    • this

• off(type,callback)

  Removes a previously registered event listener for the specified event type

  • params
    • {String} type
    • {Function} callback
  • returns
    • this

• layerBeforeTo([beforeId])

  Moves the three to a different z-position, If beforeId is omitted, the layer will be appended to the end of the layers array and appear above all other layers on the map.

  • params
    • {String} beforeId
  • returns
    • this

• addPass(pass)

  Adds a post-processing pass to the internal EffectComposer. The pass will be inserted before the final output pass to ensure correct rendering order.

  • params
    • {THREE.Pass} pass
  • returns
    • this

• removePass(pass)

  Removes a previously added post-processing pass from the internal EffectComposer.

  • params
    • {THREE.Pass} pass
  • returns
    • this

SceneTransform

examples

const scale = new SceneTransform.projectedUnitsPerMeter(24)

static methods

• projectedMercatorUnitsPerMeter()

  • params
  • returns
    • {Number} value

• projectedUnitsPerMeter(lat)

  • params
    • {Number} lat
  • returns
    • {Number} value

• lngLatToVector3(lng, [lat], [alt] )

  • params
    • {Array | Number} lng
    • {Number} lat
    • {Number} alt
  • returns
    • {THREE.Vector3} v

• vector3ToLngLat(v)

  • params
    • {THREE.Vector3} v
  • returns
    • {Array} value

Sun

examples

const sun = new Sun()

creation

• constructor()
  • params

properties

• {THREE.Group} delegate : readonly
• {Boolean} castShadow
• {Date | String} currentTime
• {THREE.DirectionalLight} sunLight : readonly
• {THREE.HemisphereLight} hemiLight: readonly

methods

• update(frameState)
  • params
    • {Object} frameState:
  • returns
    • this

Creator

examples

const rtcGroup = Creator.createRTCGroup([-1000, 0, 0])

static methods

• createRTCGroup(center, [rotation], [scale])

  • params
    • {Array} center
    • {Array} rotation: default value is [0,0,0]
    • {Array} scale: scale corresponding to the current latitude
  • returns
    • {THREE.Group} group

• createMercatorRTCGroup(center, [rotation], [scale])

  • params
    • {Array} center
    • {Array} rotation: default value is [0,0,0]
    • {Array} scale: scale corresponding to the current latitude
  • returns
    • {THREE.Group} group

• createShadowGround(center, [width], [height])

  • params
    • {THREE.Vector3} center
    • {Number} width: default value is 100
    • {Number} height : default value is 100
  • returns
    • {THREE.Mesh} mesh