GLTFLayer

GLTFLayer is a layer for drawing GLTF 3D models based on WebGL.

GLTFLayer only supports adding GLTFMarker and MultiGLTFMarker; adding any other data will throw an error.

It is a subclass of maptalks.OverlayLayer and inherits all the methods of OverlayLayer.

Note: In the 2026 source code, the actual inheritance chain of GLTFLayer is GLTFLayer → MaskLayerMixin(AbstractGLTFLayer) → maptalks.OverlayLayer, and the constructor signature supports new GLTFLayer(id, geometries?, options?); when geometries is omitted, options can be passed as the second argument (verified against 2026 source code).

Constructor

import { GLTFLayer } from '@maptalks/gl-layers';

const layer = new GLTFLayer('gltf0');

Details

Parameters:

• id* String The layer id
• options* Object Configuration options, available options are as follows:

Option	Type	Description	Default
attribution	String	The attribution of the layer	null
minZoom	Number	The minimum zoom level at which the layer is displayed	null
maxZoom	Number	The maximum zoom level at which the layer is displayed	null
visible	Boolean	Whether the layer is visible	true
opacity	Number	The opacity of the layer	1
hitDetect	Boolean	Whether to enable layer drawing detection (dynamic mouse cursor styles); disabling it can improve performance	true
collisionScope	String	The scope of the collision detection index: "map" or "layer"	"layer"

GLTFLayer-specific options (supplemented from 2026 source code):

Option	Type	Description	Default
markerTypes	String[]	Geometry types accepted by the layer	['gltfmarker', 'multigltfmarker']
pointSize	Number	Point size (pixels)	1
renderer	String	Renderer type	'gl'
doubleBuffer	Boolean	Whether to use double-buffered rendering	false
glOptions	Object	GL context options	null
markerEvents	Boolean	Whether to respond to marker mouse events	true
forceRenderOnZooming	Boolean	Whether to force a redraw when zooming	true
forceRenderOnMoving	Boolean	Whether to force a redraw when moving	true
forceRenderOnRotating	Boolean	Whether to force a redraw when rotating	true
style	Object	The layer style, either an array of [{filter, symbol}, ...] or { $root, style: [{filter, symbol}, ...] } ($root is used to replace {$root} in symbol.url)	—

Methods Inherited from OverlayLayer

See the API documentation of the parent class OverlayLayer for details.

getGeometryById(id)

Gets the geometry with the given id.

Parameters:

• id Number | String the id of the geometry

Returns:

• Geometry

getGeometries(filter, context)

Gets all geometries matching the given condition.

Parameters:

• filter Function the filter function
• context Object the this value used when the function runs

Returns:

• Geometry[]

getFirstGeometry()

Gets the first geometry.

Returns:

• Geometry

getLastGeometry()

Gets the last geometry.

Returns:

• Geometry

getCount()

Gets the number of geometries.

Returns:

• Number

getExtent()

Gets the geographic extent of all geometries on the layer.

Returns:

• Extent

forEach(fn, context)

Iterates over the geometries and executes the function.

Parameters:

• fn Function the function applied to each geometry, function(geometry) {}
• context Object the this value used when the function runs

Returns:

• this

isEmpty()

Checks whether the layer is empty.

Returns:

• Boolean

addGeometry(geometries, fitView)

Adds geometries to the layer.

Parameters:

• geometries Geometry | Geometry[] a geometry or an array of geometries
• fitView Boolean

Returns:

• this

removeGeometry(geometries)

Removes geometries from the layer.

Parameters:

• geometries Geometry | Geometry[]

Returns:

• this

clear()

Clears the layer and removes all geometries.

Returns:

• this

setStyle(style)

Sets the style of the layer. See this link for the style documentation.

const style = [
  {
    filter : true,            // 数据的过滤条件
    symbol: {                 // 样式定义
      markerWidth: 6,
      markerHeight: 6,
      markerType: 'ellipse',
      markerFill: '#0f0'
    }
  }
];
layer.setStyle(style);

Parameters:

• style Object[] the layer style object. Each style object contains two properties, filter and symbol: filter is a filter condition of the feature-filter type, and symbol is a style object.

Returns:

• this

getStyle()

Gets the layer style.

Returns:

• Object[]

removeStyle()

Removes the layer style.

Returns:

• this

Methods Inherited from Layer

See the API documentation of the parent class Layer for details.

getId()

Gets the layer id.

Returns:

• Number | String

setId(id)

Sets the layer id.

Returns:

• this

addTo(map)

Adds the layer to the map.

Returns:

• this

getMinZoom()

Gets the minimum zoom level.

Returns:

• Number

getMaxZoom()

Gets the maximum zoom level.

Returns:

• Number

getMap()

Gets the map object that the layer is added to.

Returns:

• Map

getProjection()

Gets the projection of the layer.

Returns:

• Projection

show()

Shows the layer.

Returns:

• this

hide()

Hides the layer.

Returns:

• this

isVisible()

Checks whether the layer is visible.

Returns:

• Boolean

remove()

Removes the layer.

Returns:

• this

on(events, handler, context)

Registers an event listener on the layer.

Returns:

• this

addEventListener(events, handler, context)

Same as the on method.

Returns:

• this

once(events, handler, context)

Registers a one-time event listener on the layer; it is removed after being fired.

Returns:

• this

off(events, handler, context)

Removes the registered event listener from the layer.

Returns:

• this

removeEventListener(events, handler, context)

Same as the off method.

Returns:

• this

listens(events, handler, context)

Checks whether the layer is listening to the given events.

Returns:

• Boolean

fire(event, params)

Manually fires an event; params is the event parameter.

Returns:

• this

setOptions(options)

Sets the layer options.

Returns:

• this

config(key, value)

Updates a layer option.

Returns:

• this

Static Methods

fromJSON(json)

Creates a GLTFLayer object from the layer's JSON object.

const json = layer.toJSON();

const layerCopied = maptalks.Layer.fromJSON(json);

Returns:

• GLTFLayer

Methods (supplemented from 2026 source code)

NOTE

The following GLTFLayer-specific methods are provided in the 2026 source code of @maptalks/gl-layers and were not documented in older docs:

Method	Simplified signature	Description
setURLModifier / getURLModifier	(fn) / ()	Set/get the model url rewriting function
identify	(coordinate, options?): Object[]	Identify models by coordinate (internally converted to a container point, then picking is performed)
identifyAtPoint	(point, options={}): Object[]	Pick models at a container point; options.filter filters the results, includeInternals returns internal data
addGeometry	(geometries, fitView?)	Add geometries (GeoJSON supported), registering a pickingId for each
addMarker	(markers)	Add markers to the internal markerMap
setStyle / getStyle	(layerStyle) / ()	Set/get the layer style (filter-symbol); setStyle fires the setstyle event
updateSymbol	(idx, symbolProperties)	Update the symbol at index idx in the style, firing the updatesymbol event
getGLTFUrls	(): string[]	Get the list of loaded model urls
outlineBatch / outlineAll / cancelOutline	(filterIndex?) / () / ()	Outline models in batch by filter index / outline all / cancel outline
clear	()	Clear all geometries
toJSON	(options?)	Export the layer JSON
static registerShader / removeShader / getShaders	—	Register/remove/get shaders (built-in: phong, pbr, pbr-lite, depth, pointline, wireframe)

Events

Example code for listening to layer events:

// 监听workerready事件
layer.once('workerready', e => {
  // e为事件参数
  console.log('worker is ready');
});

// 监听tileload事件
layer.on('tileload', e => {
  // e为事件参数
  console.log('loaded a tile', e.tile);
});

Layer Events

updatesymbol

Fired when the symbol at index in the Layer's style is updated.

Event properties:

Property	Type	Value
type	String	"updatesymbol"
target	GLTFLayer	this
index	Number	The style index
symbol	Object	The symbol object

setstyle

Fired after the Layer's style is set (supplemented from 2026 source code).

Event properties:

Property	Type	Value
type	String	"setstyle"
target	GLTFLayer	this
style	Object	The layer style after it is set (a filter-symbol array or object)

workerready

Fired when the worker is ready.

Event properties:

Property	Type	Value
type	String	"workerready"
target	GLTFLayer	this

modelerror

Fired when a model fails to load.

Event properties:

Property	Type	Value
type	String	"modelerror"
target	GLTFLayer	this
url	String	The url of the model that failed to load
info	Object	The error info

modelload

Fired when models are loaded successfully.

Event properties:

Property	Type	Value
type	String	"modelload"
target	GLTFLayer	this
models	String[]	The urls of the models loaded successfully

Events Inherited from OverlayLayer

addgeo

Fired when a geometry is added.

Properties:

Property	Type	Value
type	String	"addgeo"
target	Layer	this
geometries	Geometry[]	the added geometries

removegeo

Fired when a geometry is removed.

Properties:

Property	Type	Value
type	String	"removegeo"
target	Layer	this
geometries	Geometry[]	the removed geometries

setstyle

Fired after the layer style is set with setStyle.

Properties:

Property	Type	Value
type	String	"setstyle"
target	Layer	this
style	Object[]	the style array

removestyle

Fired after the layer style is cleared with removeStyle.

Properties:

Property	Type	Value
type	String	"removestyle"
target	Layer	this

Events Inherited from Layer

clear

Fired when the layer is cleared.

Properties:

Property	Type	Value
type	String	"clear"
target	VectorTileLayer	this

idchange

Fired when the layer id changes.

Properties:

Property	Type	Value
type	String	"idchange"
target	VectorTileLayer	this
old	String	the old id
new	String	the new id

renderercreate

Fired when the renderer is created.

Properties:

Property	Type	Value
type	String	"renderercreate"
target	VectorTileLayer	this
renderer	VectorTileLayerRenderer

canvascreate

Fired when the canvas is created.

Properties:

Property	Type	Value
type	String	"canvascreate"
target	VectorTileLayer	this
gl	WebGLRenderingContext2D

renderstart

Fired when rendering starts.

Properties:

Property	Type	Value
type	String	"renderstart"
target	VectorTileLayer	this

renderend

Fired when rendering ends.

Properties:

Property	Type	Value
type	String	"renderend"
target	VectorTileLayer	this

Event verification (2026 source code)

• modelload: fired when all models are loaded; parameters: { models: url list }
• modelerror: fired when a model fails to load; parameters: { url, info }
• setstyle: fired after setting the style; parameters: { style }
• updatesymbol: fired after updating a symbol; parameters: { index, symbol }
• load / add: fired on the marker when the model is loaded / when the marker is added (including the layer reference)

This document has been verified against the 2026 source code of @maptalks/gl-layers (api-notes-others.md)