--- title: "Layer3D | 3D JS | JavaScript maps SDK" description: "Documentation for 3D objects" --- > For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL. # Class Layer3D 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[](#example) ```typescript 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, }); ``` #### Implements - Layer3DInternalAPIInterface - Defined in [src/Layer3D.ts:75](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L75) ##### Index ### Constructors [constructor](#constructor) ### Properties [clock](#clock) [id](#id) [maxZoom](#maxzoom) [minZoom](#minzoom) [renderingMode](#renderingmode) [type](#type) ### Methods [\[handleMeshClickMethodSymbol\]](#handlemeshclickmethodsymbol) [\[removeItem3DFromIndexSymbol\]](#removeitem3dfromindexsymbol) [addClonedMesh](#addclonedmesh) [addMesh](#addmesh) [addMeshFromURL](#addmeshfromurl) [addPointLight](#addpointlight) [clear](#clear) [cloneMesh](#clonemesh) [getItem3D](#getitem3d) [getMapInstance](#getmapinstance) [getRendererInstance](#getrendererinstance) [modifyPointLight](#modifypointlight) [onAdd?](#onadd) [onRemove?](#onremove) [removeMesh](#removemesh) [render](#render) [setAmbientLight](#setambientlight) [updateItemMatrices](#updateitemmatrices) ## Constructors ### constructor[](#constructor) - new Layer3D(id: string, options?: [Layer3DOptions](https://docs.maptiler.com/sdk-js/modules/3d/api/types/Layer3DOptions/)): Layer3D[](#constructorlayer3d) #### Parameters - id: string - options: [Layer3DOptions](https://docs.maptiler.com/sdk-js/modules/3d/api/types/Layer3DOptions/) = {} #### Returns Layer3D - Defined in [src/Layer3D.ts:151](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L151) ## Properties ### `Readonly`clock[](#clock) clock: Clock = ... The three.js clock instance of the layer. Used internally for animations. #### See[](#see) [https://threejs.org/docs/#api/en/core/Clock](https://threejs.org/docs/#api/en/core/Clock) - Defined in [src/Layer3D.ts:118](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L118) ### `Readonly`id[](#id) id: string The id of the layer, this is used to identify the layer in the map Implementation of Layer3DInternalAPIInterface.id - Defined in [src/Layer3D.ts:79](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L79) ### maxZoom[](#maxzoom) maxZoom: number The maximum zoom of the layer #### See[](#see-1) [https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/#maxzoom](https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/#maxzoom) - Defined in [src/Layer3D.ts:107](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L107) ### minZoom[](#minzoom) minZoom: number The minimum zoom of the layer #### See[](#see-2) [https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/#minzoom](https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/#minzoom) - Defined in [src/Layer3D.ts:102](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L102) ### `Readonly`renderingMode[](#renderingmode) renderingMode: "2d" | "3d" = "3d" The rendering mode of the layer, this is used to identify the layer in the map #### See[](#see-3) [https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/#renderingmode](https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/#renderingmode) Implementation of Layer3DInternalAPIInterface.renderingMode - Defined in [src/Layer3D.ts:90](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L90) ### `Readonly`type[](#type) type: "custom" The type of the layer, this is used to identify the layer in the map #### See[](#see-4) [https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/#type](https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/#type) Implementation of Layer3DInternalAPIInterface.type - Defined in [src/Layer3D.ts:85](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L85) ## Methods ### \[handleMeshClickMethodSymbol\][](#handlemeshclickmethodsymbol) - "\[handleMeshClickMethodSymbol\]"(event: Layer3DInternalApiEvent): void[](#handlemeshclickmethodsymbol-1) `Internal` Handle the click event for a mesh This is used to trigger the `click` event for the item by WebGLRenderManager. #### Parameters - event: Layer3DInternalApiEvent The event data #### Returns void #### See[](#see-5) Implementation of Layer3DInternalAPIInterface.\[handleMeshClickMethodSymbol\] - Defined in [src/Layer3D.ts:247](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L247) ### \[removeItem3DFromIndexSymbol\][](#removeitem3dfromindexsymbol) - "\[removeItem3DFromIndexSymbol\]"(id: string): void[](#removeitem3dfromindexsymbol-1) #### Parameters - id: string #### Returns void - Defined in [src/Layer3D.ts:750](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L750) ### addClonedMesh[](#addclonedmesh) - addClonedMesh(     params: [GenericObject3DOptions](https://docs.maptiler.com/sdk-js/modules/3d/api/types/GenericObject3DOptions/) & {         animationMode?: [AnimationMode](https://docs.maptiler.com/sdk-js/modules/3d/api/types/AnimationMode/);         heading?: number;         opacity?: number;         pitch?: number;         pointSize?: number;         roll?: number;         scale?: number | \[number, number, number\];         sourceOrientation?: [SourceOrientation](https://docs.maptiler.com/sdk-js/modules/3d/api/enums/SourceOrientation/);         states?: [Item3DMeshUIStates](https://docs.maptiler.com/sdk-js/modules/3d/api/types/Item3DMeshUIStates/);         userData?: Record;         wireframe?: boolean;     } & {         animations?: AnimationClip\[\];         id: string;         mesh: | Object3D         | Mesh<             BufferGeometry,             Material | Material\[\],             Object3DEventMap,         \>         | Group;     }, ): [Item3D](https://docs.maptiler.com/sdk-js/modules/3d/api/interfaces/Item3D/)[](#addclonedmesh-1) `Internal` Used by Item3D.clone() to add a cloned mesh to the layer. #### Parameters - params: [GenericObject3DOptions](https://docs.maptiler.com/sdk-js/modules/3d/api/types/GenericObject3DOptions/) & {     animationMode?: [AnimationMode](https://docs.maptiler.com/sdk-js/modules/3d/api/types/AnimationMode/);     heading?: number;     opacity?: number;     pitch?: number;     pointSize?: number;     roll?: number;     scale?: number | \[number, number, number\];     sourceOrientation?: [SourceOrientation](https://docs.maptiler.com/sdk-js/modules/3d/api/enums/SourceOrientation/);     states?: [Item3DMeshUIStates](https://docs.maptiler.com/sdk-js/modules/3d/api/types/Item3DMeshUIStates/);     userData?: Record;     wireframe?: boolean; } & {     animations?: AnimationClip\[\];     id: string;     mesh: | Object3D     | Mesh<         BufferGeometry,         Material | Material\[\],         Object3DEventMap,     \>     | Group; } - ##### `Optional`animationMode?: [AnimationMode](https://docs.maptiler.com/sdk-js/modules/3d/api/types/AnimationMode/) Animation mode. Default: `continuous` - ##### `Optional`heading?: number Heading measured in degrees clockwise from true north. - ##### `Optional`opacity?: number Opacity of the mesh - ##### `Optional`pitch?: number Pitch measured in degrees. - ##### `Optional`pointSize?: number Point size, applicable only to point clouds. Default: 1 - ##### `Optional`roll?: number Roll measured in degrees. - ##### `Optional`scale?: number | \[number, number, number\] Scale the mesh by a factor. Default: no scaling added - ##### `Optional`sourceOrientation?: [SourceOrientation](https://docs.maptiler.com/sdk-js/modules/3d/api/enums/SourceOrientation/) Rotation to apply to the model to add, as a Quaternion. Default: a rotation of PI/2 around the x axis, to adjust from the default ThreeJS space (right-hand, Y up) to the Maplibre space (right-hand, Z up) - ##### `Optional`states?: [Item3DMeshUIStates](https://docs.maptiler.com/sdk-js/modules/3d/api/types/Item3DMeshUIStates/) - ##### `Optional`userData?: Record - ##### `Optional`wireframe?: boolean Displays a mesh as wireframe if true (does not apply to point cloud) Default: `false` - ##### `Optional`animations?: AnimationClip\[\] - ##### id: string - ##### mesh:     | Object3D     | Mesh<         BufferGeometry,         Material | Material\[\],         Object3DEventMap,     \>     | Group #### Returns [Item3D](https://docs.maptiler.com/sdk-js/modules/3d/api/interfaces/Item3D/) - Defined in [src/Layer3D.ts:595](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L595) ### addMesh[](#addmesh) - addMesh(     id: string,     mesh:         | Object3D         | Mesh<             BufferGeometry,             Material | Material\[\],             Object3DEventMap,         \>         | Group,     options?: [MeshOptions](https://docs.maptiler.com/sdk-js/modules/3d/api/types/MeshOptions/), ): [Item3D](https://docs.maptiler.com/sdk-js/modules/3d/api/interfaces/Item3D/)[](#addmesh-1) Add an existing mesh to the map #### Parameters - id: string The ID of the mesh - mesh:     | Object3D     | Mesh<         BufferGeometry,         Material | Material\[\],         Object3DEventMap,     \>     | Group - options: [MeshOptions](https://docs.maptiler.com/sdk-js/modules/3d/api/types/MeshOptions/) = {} The options to add the mesh with #### Returns [Item3D](https://docs.maptiler.com/sdk-js/modules/3d/api/interfaces/Item3D/) The item - Defined in [src/Layer3D.ts:482](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L482) ### addMeshFromURL[](#addmeshfromurl) - addMeshFromURL(     id: string,     url: string,     options?: [AddMeshFromURLOptions](https://docs.maptiler.com/sdk-js/modules/3d/api/types/AddMeshFromURLOptions/), ): Promise<[Item3D](https://docs.maptiler.com/sdk-js/modules/3d/api/interfaces/Item3D/)\>[](#addmeshfromurl-1) Load a GLTF file from its URL and add it to the map #### Parameters - id: string The ID of the mesh - url: string - options: [AddMeshFromURLOptions](https://docs.maptiler.com/sdk-js/modules/3d/api/types/AddMeshFromURLOptions/) = {} The options to add the mesh with #### Returns Promise<[Item3D](https://docs.maptiler.com/sdk-js/modules/3d/api/interfaces/Item3D/)\> - Defined in [src/Layer3D.ts:676](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L676) ### addPointLight[](#addpointlight) - addPointLight(id: string, options?: [PointLightOptions](https://docs.maptiler.com/sdk-js/modules/3d/api/types/PointLightOptions/)): Layer3D[](#addpointlight-1) 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` #### Parameters - id: string The ID of the point light - options: [PointLightOptions](https://docs.maptiler.com/sdk-js/modules/3d/api/types/PointLightOptions/) = {} The options to add the point light with #### Returns Layer3D The layer - Defined in [src/Layer3D.ts:836](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L836) ### clear[](#clear) - clear(): Layer3D[](#clear-1) Remove all the meshes and point lights of the scene. #### Returns Layer3D The layer - Defined in [src/Layer3D.ts:723](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L723) ### cloneMesh[](#clonemesh) - cloneMesh(sourceId: string, id: string, options?: [AddMeshFromURLOptions](https://docs.maptiler.com/sdk-js/modules/3d/api/types/AddMeshFromURLOptions/)): [Item3D](https://docs.maptiler.com/sdk-js/modules/3d/api/interfaces/Item3D/)[](#clonemesh-1) Clone an existing mesh. Extra options can be provided to overwrite the clone configuration. Delegates to the source item's clone() method. #### Parameters - sourceId: string The ID of the mesh to clone - id: string The ID of the cloned mesh - options: [AddMeshFromURLOptions](https://docs.maptiler.com/sdk-js/modules/3d/api/types/AddMeshFromURLOptions/) = {} The options to clone the mesh with #### Returns [Item3D](https://docs.maptiler.com/sdk-js/modules/3d/api/interfaces/Item3D/) - Defined in [src/Layer3D.ts:612](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L612) ### getItem3D[](#getitem3d) - getItem3D(id: string): [Item3D](https://docs.maptiler.com/sdk-js/modules/3d/api/interfaces/Item3D/) | null[](#getitem3d-1) #### Parameters - id: string #### Returns [Item3D](https://docs.maptiler.com/sdk-js/modules/3d/api/interfaces/Item3D/) | null - Defined in [src/Layer3D.ts:601](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L601) ### getMapInstance[](#getmapinstance) - getMapInstance(): Map[](#getmapinstance-1) Get the map instance of the layer. #### Returns Map The map instance - Defined in [src/Layer3D.ts:228](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L228) ### getRendererInstance[](#getrendererinstance) - getRendererInstance(): WebGLRenderManager[](#getrendererinstance-1) Get the renderer instance of the layer. This is internally for animations and batch rendering layers. #### Returns WebGLRenderManager The renderer instance - Defined in [src/Layer3D.ts:236](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L236) ### modifyPointLight[](#modifypointlight) - modifyPointLight(id: string, options: [PointLightOptions](https://docs.maptiler.com/sdk-js/modules/3d/api/types/PointLightOptions/)): Layer3D | undefined[](#modifypointlight-1) Modify a point light #### Parameters - id: string The ID of the point light - options: [PointLightOptions](https://docs.maptiler.com/sdk-js/modules/3d/api/types/PointLightOptions/) The options to modify the point light with #### Returns Layer3D | undefined - Defined in [src/Layer3D.ts:627](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L627) ### `Optional`onAdd[](#onadd) - onAdd?(map: Map, gl: WebGL2RenderingContext): void[](#onadd-1) Automatically called when the layer is added. (should not be called manually) #### Parameters - map: Map - gl: WebGL2RenderingContext #### Returns void Implementation of Layer3DInternalAPIInterface.onAdd - Defined in [src/Layer3D.ts:186](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L186) ### `Optional`onRemove[](#onremove) - onRemove?(\_map: Map, \_gl: WebGL2RenderingContext | WebGLRenderingContext): void[](#onremove-1) Automatically called when the layer is removed. (should not be called manually) #### Parameters - \_map: Map - \_gl: WebGL2RenderingContext | WebGLRenderingContext #### Returns void Implementation of Layer3DInternalAPIInterface.onRemove - Defined in [src/Layer3D.ts:213](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L213) ### removeMesh[](#removemesh) - removeMesh(id: string): Layer3D[](#removemesh-1) Remove a mesh from the scene using its ID. #### Parameters - id: string The ID of the mesh to remove #### Returns Layer3D The layer - Defined in [src/Layer3D.ts:736](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L736) ### render[](#render) - render(): null[](#render-1) 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. #### Returns null #### See[](#see-6) - where all the calculations for the layer are done. Implementation of Layer3DInternalAPIInterface.render - Defined in [src/Layer3D.ts:456](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L456) ### setAmbientLight[](#setambientlight) - setAmbientLight(     options?: { color?: ColorRepresentation; intensity?: number }, ): Layer3D[](#setambientlight-1) Adjust the settings of the ambient light #### Parameters - options: { color?: ColorRepresentation; intensity?: number } = {} The options to set the ambient light with #### Returns Layer3D The layer - Defined in [src/Layer3D.ts:465](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L465) ### updateItemMatrices[](#updateitemmatrices) - updateItemMatrices(matrix: ArrayLike): void[](#updateitemmatrices-1) `Internal` Updates the world matrices of all Item3D dollies. Must be called before any intersection checks to ensure bounds are computed with current positions. #### Parameters - matrix: ArrayLike #### Returns void - Defined in [src/Layer3D.ts:395](https://github.com/maptiler/maptiler-3d-js/blob/d1455de4164bd626ae604b498181010b0ec9ac4b/src/Layer3D.ts#L395)