@maptiler/3d/dist/Layer3D.d.ts

Add 3D things to your map, plugin for MapTiler SDK

import { Map as MapSDK, CustomRenderMethodInput } from '@maptiler/sdk';
import { Group, ColorRepresentation, Mesh, Clock, Object3D } from 'three';
import { Layer3DOptions, MeshOptions, AddMeshFromURLOptions, CloneMeshOptions, PointLightOptions, Layer3DInternalAPIInterface, Layer3DInternalApiEvent } from './types';
import { WebGLRenderManager } from './WebGLRenderManager';
import { Item3D } from './Item3D';
import { handleMeshClickMethodSymbol, handleMeshDoubleClickMethodSymbol, handleMeshMouseEnterMethodSymbol, handleMeshMouseLeaveMethodSymbol, handleMeshMouseUpSymbol, handleMeshMouseDownSymbol, prepareRenderMethodSymbol } from './symbols';
/**
 * The Layer3D class is the main class for the 3D layer.
 * It is used to add meshes to the layer, and to manage the items in the layer.
 * @example
 * ```ts
  const layer3D = new Layer3D("layer-id");
  map.addLayer(layer3D);

  layer3D.setAmbientLight({ intensity: 2 });
  layer3D.addPointLight("point-light", { intensity: 30 });
  layer3D.modifyPointLight("point-light", { intensity: 100 });

  await layer3D.addMeshFromURL("duck", "./models/Duck.glb", {
    ...state,
    sourceOrientation: SourceOrientation.Y_UP,
  });
```
 */
export declare class Layer3D implements Layer3DInternalAPIInterface {
    /**
     * The id of the layer, this is used to identify the layer in the map
     */
    readonly id: string;
    /**
     * The type of the layer, this is used to identify the layer in the map
     * @see {CustomLayerInterface#type} https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/#type
     */
    readonly type = "custom";
    /**
     * The rendering mode of the layer, this is used to identify the layer in the map
     * @see {CustomLayerInterface#renderingMode} https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/#renderingmode
     */
    readonly renderingMode: "2d" | "3d";
    /**
     * The map instance of the layer
     * @see {MapSDK} https://docs.maptiler.com/sdk-js/api/map/#map
     */
    private map;
    /**
     * The minimum zoom of the layer
     * @see {CustomLayerInterface#minZoom} https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/#minzoom
     */
    minZoom: number;
    /**
     * The maximum zoom of the layer
     * @see {CustomLayerInterface#maxZoom} https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/#maxzoom
     */
    maxZoom: number;
    /**
     * The renderer instance of the layer
     * @see {WebGLRenderManager} https://docs.maptiler.com/sdk-js/api/webglrendermanager/#webglrendermanager
     */
    private renderer;
    /**
     * The three.js clock instance of the layer. Used internally for animations.
     * @see {Clock} https://threejs.org/docs/#api/en/core/Clock
     */
    readonly clock: Clock;
    /**
     * The three.js scene instance of the layer.
     * @see {Scene} https://threejs.org/docs/#api/en/scenes/Scene
     */
    private readonly scene;
    /**
     * The three.js camera instance of the layer.
     * @see {Camera} https://threejs.org/docs/#api/en/cameras/Camera
     */
    private readonly camera;
    /**
     * The three.js ambient light instance of the layer.
     * @see {AmbientLight} https://threejs.org/docs/#api/en/lights/AmbientLight
     */
    private readonly ambientLight;
    /**
     * The map of the items in the layer.
     */
    private readonly items3D;
    /**
     * The callbacks to unsubscribe when the layer is removed.
     * This is used to unsubscribe from internal events.
     * @see {Array} https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
     */
    private onRemoveCallbacks;
    /**
     * Whether the elevation needs to be updated.
     * This is used to update the elevation of the items in the layer.
     */
    private isElevationNeedUpdate;
    constructor(id: string, options?: Layer3DOptions);
    /**
     * Tells if the meshes should be displayed, based on the zoom range provided as layer options
     */
    private isInZoomRange;
    /**
     * Automatically called when the layer is added. (should not be called manually)
     */
    onAdd?(map: MapSDK, gl: WebGL2RenderingContext): void;
    /**
     * Automatically called when the layer is removed. (should not be called manually)
     */
    onRemove?(_map: MapSDK, _gl: WebGLRenderingContext | WebGL2RenderingContext): void;
    /**
     * Get the map instance of the layer.
     * @returns {MapSDK} The map instance
     */
    getMapInstance(): MapSDK;
    /**
     * Get the renderer instance of the layer. This is internally for animations and batch rendering layers.
     * @returns {WebGLRenderManager} The renderer instance
     */
    getRendererInstance(): WebGLRenderManager;
    /**
     * Handle the click event for a mesh
     * This is used to trigger the `click` event for the item by WebGLRenderManager.
     * @see {WebGLRenderManager#handleMouseClick}
     * @param event - The event data
     * @internal
     */
    [handleMeshClickMethodSymbol](event: Layer3DInternalApiEvent): void;
    /**
     * Handle the mouse enter event for a mesh.
     * This is used to trigger the `mouseenter` event for the item by WebGLRenderManager.
     * @internal
     * @private
     * @see {WebGLRenderManager#handleMouseMove}
     * @param event - The event data
     */
    [handleMeshMouseEnterMethodSymbol](event: Layer3DInternalApiEvent): void;
    /**
     * Handle the mouse leave event for a mesh.
     * This is used to trigger the `mouseleave` event for the item by WebGLRenderManager.
     * @internal
     * @private
     * @see {WebGLRenderManager#handleMouseMove}
     * @param event - The event data
     */
    [handleMeshMouseLeaveMethodSymbol](event: Layer3DInternalApiEvent): void;
    /**
     * Handle the mouse down event for a mesh.
     * This is used to trigger the `mousedown` event for the item by WebGLRenderManager.
     * @internal
     * @private
     * @see {WebGLRenderManager#handleMouseDown}
     * @param event - The event data
     */
    [handleMeshMouseDownSymbol](event: Layer3DInternalApiEvent): void;
    /**
     * Handle the mouse up event for a mesh.
     * This is used to trigger the `mouseup` event for the item by WebGLRenderManager.
     * @internal
     * @private
     * @see {WebGLRenderManager#handleMouseUp}
     * @param event - The event data
     */
    [handleMeshMouseUpSymbol](event: Layer3DInternalApiEvent): void;
    /**
     * Handle the double click event for a mesh.
     * This is used to trigger the `dblclick` event for the item by WebGLRenderManager.
     * @internal
     * @private
     * @see {WebGLRenderManager#handleMouseDoubleClick}
     * @param event - The event data
     */
    [handleMeshDoubleClickMethodSymbol](event: Layer3DInternalApiEvent): void;
    /**
     * Prepare the render of the layer. This is called externally by the `WebGLManagerLayer`.
     * This is equivalent to the `render` method in a MapLibre GL JS layer.
     * The difference being it merely prepares state for the render in `WebGLRenderManager`.
     * @see {WebGLRenderManager}
     * @param {CustomRenderMethodInput} options - The render options from the map.
     * @internal
     * @private
     */
    [prepareRenderMethodSymbol](options: CustomRenderMethodInput): void;
    /**
     * Render the layer. Normally this method is called by the Map instance on every frame to calculate matrices
     * and update the camera projection matrix.
     * However, this would require a multiple instances of Three.js renderers, which is not optimal.
     * So instead we use the `WebGLManagerLayer` to render the layer and return null.
     * @see {Layer3D#[prepareRenderMethodSymbol]} where all the calculations for the layer are done.
     * @see {WebGLManagerLayer}
     * @returns {null}
     */
    render(): null;
    /**
     * Adjust the settings of the ambient light
     * @param options - The options to set the ambient light with
     * @returns {Layer3D} The layer
     */
    setAmbientLight(options?: {
        color?: ColorRepresentation;
        intensity?: number;
    }): this;
    /**
     * Add an existing mesh to the map
     * @param id - The ID of the mesh
     * @param options - The options to add the mesh with
     * @returns {Item3D} The item
     */
    addMesh(id: string, mesh: Mesh | Group | Object3D, options?: MeshOptions): Item3D;
    /**
     * Add an existing mesh to the map, with options.
     * @param id - The ID of the mesh
     * @param mesh - The mesh to add
     * @param animations - The animations to add
     * @param {MeshOptions} options - The options for the mesh
     * @returns {Layer3D} The layer
     */
    private addMeshInternal;
    getItem3D(id: string): Item3D | null;
    /**
     *
     * Clone an existing mesh. Extra options can be provided to overwrite the clone configuration
     * @param sourceId - The ID of the mesh to clone
     * @param id - The ID of the cloned mesh
     * @param options - The options to clone the mesh with
     */
    cloneMesh(sourceId: string, id: string, options?: CloneMeshOptions): void;
    /**
     * Modify a point light
     * @param id - The ID of the point light
     * @param options - The options to modify the point light with
     */
    modifyPointLight(id: string, options: PointLightOptions): this | undefined;
    /**
     * Load a GLTF file from its URL and add it to the map
     * @param id - The ID of the mesh
     * @param options - The options to add the mesh with
     */
    addMeshFromURL(id: string, url: string, options?: AddMeshFromURLOptions): Promise<Item3D>;
    /**
     * Remove all the meshes and point lights of the scene.
     * @returns {Layer3D} The layer
     */
    clear(): this;
    /**
     * Remove a mesh from the scene using its ID.
     * @param id - The ID of the mesh to remove
     * @returns {Layer3D} The layer
     */
    removeMesh(id: string): this;
    /**
     * Traverse a Mesh/Group/Object3D to modify the opacities of the all the materials it finds
     * @param obj - The object to modify the opacities of
     * @param opacity - The opacity to set
     * @param forceRepaint - Whether to force a repaint
     * @returns {Layer3D} The layer
     */
    private setMeshOpacity;
    /**
     * If a mesh is a point cloud, it defines the size of the points
     * @param obj - The object to modify the point size of
     * @param size - The size to set
     * @param forceRepaint - Whether to force a repaint
     * @returns {Layer3D} The layer
     */
    private setMeshPointSize;
    /**
     * If a mesh can be rendered as wireframe, then the option is toggled according to the wireframe param
     * @param obj - The object to modify the wireframe of
     * @param wireframe - The wireframe to set
     * @param forceRepaint - Whether to force a repaint
     * @returns {Layer3D} The layer
     */
    private setMeshWireframe;
    /**
     * Adding a point light. The default options are mimicking the sun:
     * lngLat: `[0, 0]` (null island)
     * altitude: `2_000_000` meters
     * altitudeReference: `AltitudeReference.MEAN_SEA_LEVEL`
     * color: `0xffffff` (white)
     * intensity: `75`
     * decay: `0.2`
     * @param id - The ID of the point light
     * @param options - The options to add the point light with
     * @returns {Layer3D} The layer
     */
    addPointLight(id: string, options?: PointLightOptions): this;
    /**
     * Throw an error if a mesh with such ID already exists
     * @param id - The ID of the mesh to throw an error for
     */
    private throwUniqueID;
}