SDK JS
    Preparing search index...

    Class ModelInstancesLayer

    Draws ONE shared glTF/GLB model at many geographic points in a single instanced pass. An "instance" is a [lng, lat, height] position plus an optional scale and heading (degrees CW from north), so the caller supplies exactly two things: the model — a URL, raw GLB bytes, or a pre-built NormalizedMesh — and the instance list. The layer anchors at the instances' centroid and, on the default 'basemap' datum, samples the terrain PER INSTANCE and re-seats as DEM tiles land, so a spread of models follows a slope. Add it with map.addLayer; it needs a WebGL2 context (on WebGL1 it draws nothing rather than throwing) and Mercator — a non-affine (globe) frame hides it. Nothing is fetched until the layer is added to a map.

    import { ModelInstancesLayer } from '@bitruvius/sdk-maplibre';

    map.addLayer(
      new ModelInstancesLayer({
        id: 'turbines',
        model: 'https://…/turbine.glb',
        instances: [
          { position: [4.9, 52.4, 0], scale: 80, heading: 30 },
          { position: [4.91, 52.41, 0], scale: 80, heading: 210 },
        ],
      }),
    );

    Implements

    • CustomLayerInterface
    Index

    Constructors

    constructor

    Properties

    id renderingMode type

    Methods

    clearSun getCenter onAdd onRemove pickPosition prerender render setOpacity setSunState setVisible

    Constructors

    Properties

    id: string

    A unique layer id.

    renderingMode: "3d" = ...

    Either "2d" or "3d". Defaults to "2d".

    type: "custom" = ...

    The layer's type. Must be "custom".

    Methods

    • Revert to the default (no-sun) lighting — the clearSun half of SunLightable (used when the geo-sun system is disabled).

      Returns void

    • The model anchor [lng, lat] (instances' centroid).

      Returns [number, number] | null

      [lng, lat] in degrees, or null until loaded.

    • MapLibre CustomLayerInterface hook — invoked when the layer is added with map.addLayer; initializes GL resources and uploads the instances.

      Parameters

      Returns void

    • MapLibre CustomLayerInterface hook — invoked when the layer is removed with map.removeLayer; releases GL resources.

      Returns void

    • Resolve a canvas point to the 3D geographic position of the frontmost rendered instance surface — the screen→scene primitive behind measurement and slice placement.

      Parameters

      • x: number

        Canvas X in CSS pixels, top-left origin (e.g. a MapLibre click event's e.point.x).

      • y: number

        Canvas Y in CSS pixels, top-left origin.

      • snapRadiusPx: number = 0

        Snap radius in CSS pixels (default 0 = exact pixel): the nearest mesh hit within the radius wins, so a click slightly off an edge still lands on the mesh.

      Returns PickedPosition | null

      The picked position (lng/lat degrees, height metres above the rendered ground datum, plus the cross-layer-comparable depth01), or null on a miss / before the first frame.

    • Optional method called during a render frame to allow a layer to prepare resources or render into a texture.

      The layer cannot make any assumptions about the current GL state and must bind a framebuffer before rendering.

      Parameters

      Returns void

    • Called during a render frame allowing the layer to draw into the GL context.

      The layer can assume blending and depth state is set to allow the layer to properly blend and clip other layers. The layer cannot make any other assumptions about the current GL state.

      If the layer needs to render to a texture, it should implement the prerender method to do this and only use the render method for drawing directly into the main framebuffer.

      The blend function is set to gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA). This expects colors to be provided in premultiplied alpha form where the r, g and b values are already multiplied by the a value. If you are unable to provide colors in premultiplied form you may want to change the blend function to gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA).

      Parameters

      Returns void

    • Fade the models over the basemap.

      Parameters

      • opacity: number

        Opacity in [0, 1] (clamped); 0 = transparent, 1 = opaque.

      Returns void

    • Light this layer from a SunState — satisfies @bitruvius/sdk-maplibre's SunLightable, so a GeoSunSystem / RendererSunController drives it directly.

      Parameters

      • sun: SunState

        The sun state (direction in ENU, altitude in degrees) to light the models with.

      Returns void

    • Show/hide the layer without removing it.

      Parameters

      • visible: boolean

        true to show, false to hide.

      Returns void

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods