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
• {ShaderPass} customOutPass : 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