Class Map<UserData>

A map is an Entity3D that represents a flat surface displaying one or more layer(s).

Supported layers

Maps support various types of layers.

Color layers

Maps can contain any number of color layers, as well as any number of mask layers.

Color layers are used to display satellite imagery, vector features or any other dataset. Mask layers are used to mask parts of a map (like an alpha channel).

Elevation layers

Up to one elevation layer can be added to a map, to provide features related to elevation, such as terrain deformation, hillshading, contour lines, etc. Without an elevation layer, the map will appear like a flat rectangle on the specified extent.

Note: to benefit from the features given by elevation layers (shading for instance) while keeping a flat map, disable terrain in the TerrainOptions.

💡 If the TerrainOptions.enableCPUTerrain is enabled, the elevation data can be sampled by the getElevation method.

Picking on maps

Maps can be picked like any other 3D entity, using the pick() method.

However, if TerrainOptions.enableCPUTerrain is enabled, then the map provides an alternate methods for: raycasting-based picking, in addition to GPU-based picking.

GPU-based picking

This is the default method for picking maps. When the user calls pick(), the camera's field of view is rendered into a temporary texture, then the pixel(s) around the picked point are analyzed to determine the location of the picked point.

The main advantage of this method is that it ignores transparent pixels of the map (such as no-data elevation pixels, or transparent color layers).

Raycasting-based picking

💡 This method requires that TerrainOptions.enableCPUTerrain is enabled, and that core.picking.PickOptions.gpuPicking is disabled.

This method casts a ray that is then intersected with the map's meshes. The first intersection is returned.

The main advantage of this method is that it's much faster and puts less pressure on the GPU.

Type Parameters

Hierarchy (view full)

Implements

Constructors

constructor

Properties

_distance extent hasLayers id isEntity isEntity3D isMap isMemoryUsage isPickable isPickableFeatures maxSubdivisionLevel name showOutline subdivisionThreshold type userData

Accessors

backgroundColor backgroundOpacity clippingPlanes colorimetry contourLines depthTest discardNoData distance elevationRange frozen graticule hillshading imageSize instance layerCount loading object3d opacity progress ready renderOrder segments showColliderMeshes showTileOutlines side subdivisions terrain tileOutlineColor visible wireframe

Methods

addEventListener addLayer assignRenderOrder canSubdivide contains dispatchEvent dispose filterChangeSources forEachLayer getBoundingBox getColorLayers getElevation getElevationLayers getElevationMinMax getIndex getLayers getMemoryUsage hasEventListener insertLayerAfter isOwned moveLayerDown moveLayerUp notifyChange onObjectCreated onRenderingContextLost onRenderingContextRestored pick pickFeaturesFrom postUpdate preprocess preUpdate raycast removeEventListener removeLayer setupMaterial shouldCheckForUpdate shouldFullUpdate shouldUpdate sortColorLayers traverse traverseMaterials traverseMeshes traverseTiles update updateClippingPlanes updateOpacity updateRenderOrder updateVisibility

Constructors

constructor

Properties

Protected_distance

_distance: {
    max: number;
    min: number;
}

Readonlyextent

extent: Extent

ReadonlyhasLayers

hasLayers: true = ...

Read-only flag to check if a given object is of type HasLayers.

Readonlyid

id: string

The unique identifier of this entity.

ReadonlyisEntity

isEntity: boolean = ...

Read-only flag to check if a given object is of type Entity.

ReadonlyisEntity3D

isEntity3D: boolean = ...

Read-only flag to check if a given object is of type Entity3D.

ReadonlyisMap

isMap: true = ...

ReadonlyisMemoryUsage

isMemoryUsage: true = ...

Readonly flag to indicate that his object implements MemoryUsage.

ReadonlyisPickable

isPickable = true

ReadonlyisPickableFeatures

isPickableFeatures = true

ReadonlymaxSubdivisionLevel

maxSubdivisionLevel: number

name

name: undefined | string

The name of this entity.

ReadonlyshowOutline

showOutline = false

subdivisionThreshold

subdivisionThreshold: number

The global factor that drives SSE (screen space error) computation. The lower this value, the sooner a tile is subdivided. Note: changing this scale to a value less than 1 can drastically increase the number of tiles displayed in the scene, and can even lead to WebGL crashes.

Default Value

DEFAULT_SUBDIVISION_THRESHOLD

Readonlytype

type: "Map" = ...

The name of the type of this object.

ReadonlyuserData

userData: UserData

An object that can be used to store custom data about the Entity.

Accessors

backgroundColor

backgroundOpacity

  • get backgroundOpacity(): number

  • Gets or sets the background opacity.

    Returns number

  • set backgroundOpacity(opacity): void

  • Parameters

    • opacity: number

    Returns void

clippingPlanes

  • get clippingPlanes(): null | Plane[]

  • Gets or sets the clipping planes set on this entity. Default is null (no clipping planes).

    Note: custom entities must ensure that the materials and shaders used do support the clipping plane feature of three.js. Refer to the three.js documentation for more information.

    Returns null | Plane[]

  • set clippingPlanes(planes): void

  • Parameters

    Returns void

colorimetry

contourLines

depthTest

  • get depthTest(): boolean

  • Gets or sets depth testing on materials.

    Returns boolean

  • set depthTest(v): void

  • Parameters

    • v: boolean

    Returns void

discardNoData

  • get discardNoData(): boolean

  • Toggles discard no-data pixels.

    Returns boolean

  • set discardNoData(opacity): void

  • Parameters

    • opacity: boolean

    Returns void

distance

  • get distance(): {
        max: number;
        min: number;
    }

  • Returns {
        max: number;
        min: number;
    }

    • max: number
    • min: number

elevationRange

frozen

  • get frozen(): boolean

  • Gets or sets the frozen status of this entity. A frozen entity is still visible but will not be updated automatically.

    Useful for debugging purposes.

    Returns boolean

  • set frozen(v): void

  • Parameters

    • v: boolean

    Returns void

graticule

hillshading

imageSize

instance

layerCount

  • get layerCount(): number

  • Returns the number of layers currently in this object.

    Returns number

loading

  • get loading(): boolean

  • Returns true if this map is currently processing data.

    Returns boolean

object3d

opacity

  • get opacity(): number

  • Gets or sets the opacity of this entity.

    Returns number

  • set opacity(v): void

  • Parameters

    • v: number

    Returns void

progress

  • get progress(): number

  • Gets the loading progress (between 0 and 1) of the map. This is the average progress of all layers in this map. Note: if no layer is present, this will always be 1. Note: This value is only meaningful is loading is true.

    Returns number

ready

  • get ready(): boolean

  • Determine if this entity is ready to use.

    Returns boolean

renderOrder

  • get renderOrder(): number

  • Gets or sets the render order of this entity.

    Returns number

  • set renderOrder(v): void

  • Parameters

    • v: number

    Returns void

segments

showColliderMeshes

  • get showColliderMeshes(): boolean

  • Shows meshes used for raycasting purposes.

    Returns boolean

  • set showColliderMeshes(show): void

  • Parameters

    • show: boolean

    Returns void

showTileOutlines

  • get showTileOutlines(): boolean

  • Shows tile outlines.

    Returns boolean

  • set showTileOutlines(show): void

  • Parameters

    • show: boolean

    Returns void

side

  • get side(): Side

  • Gets or sets the sidedness of the map surface:

    • FrontSide will only display the "above ground" side of the map (in cartesian maps), or the outer shell of the map (in globe settings).
    • BackSide will only display the "underground" side of the map (in cartesian maps), or the inner shell of the map (in globe settings).
    • DoubleSide will display both sides of the map.

    Returns Side

    Default Value

    FrontSide

  • set side(newSide): void

  • Parameters

    Returns void

subdivisions

  • get subdivisions(): {
        x: number;
        y: number;
    }

  • Returns {
        x: number;
        y: number;
    }

    • x: number
    • y: number

terrain

tileOutlineColor

visible

  • get visible(): boolean

  • Gets or sets the visibility of this entity. A non-visible entity will not be automatically updated.

    Returns boolean

  • set visible(v): void

  • Parameters

    • v: boolean

    Returns void

wireframe

  • get wireframe(): boolean

  • Displays the map tiles in wireframe.

    Returns boolean

  • set wireframe(v): void

  • Parameters

    • v: boolean

    Returns void

Methods

addEventListener

  • addEventListener<T>(type, listener): void

  • Adds a listener to an event type.

    Type Parameters

    • T extends
          | "initialized"
          | "frozen-property-changed"
          | "visible-property-changed"
          | "layer-order-changed"
          | "layer-added"
          | "layer-removed"
          | "elevation-changed"
          | "opacity-property-changed"
          | "clippingPlanes-property-changed"
          | "renderOrder-property-changed"
          | "object-created"

    Parameters

    Returns void

  • addEventListener<T>(type, listener): void

  • Type Parameters

    • T extends string

    Parameters

    Returns void

addLayer

  • addLayer<TLayer>(layer): Promise<TLayer>

  • Adds a layer, then returns the created layer. Before using this method, make sure that the map is added in an instance. If the extent or the projection of the layer is not provided, those values will be inherited from the map.

    Type Parameters

    Parameters

    • layer: TLayer

      the layer to add

    Returns Promise<TLayer>

    a promise resolving when the layer is ready

ProtectedassignRenderOrder

canSubdivide

  • canSubdivide(node): boolean

  • Parameters

    • node: TileMesh

      The node to subdivide.

    Returns boolean

    True if the node can be subdivided.

contains

  • contains(obj): boolean

  • Test whether this entity contains the given object.

    The object may be a component of the entity, or a 3D object.

    Parameters

    • obj: unknown

      The object to test.

    Returns boolean

    true if the entity contains the object.

dispatchEvent

  • dispatchEvent<T>(event): void

  • Fire an event type.

    Type Parameters

    • T extends
          | "initialized"
          | "frozen-property-changed"
          | "visible-property-changed"
          | "layer-order-changed"
          | "layer-added"
          | "layer-removed"
          | "elevation-changed"
          | "opacity-property-changed"
          | "clippingPlanes-property-changed"
          | "renderOrder-property-changed"
          | "object-created"

    Parameters

    Returns void

dispose

  • dispose(options?): void

  • Disposes this map and associated unmanaged resources.

    Note: By default, layers in this map are not automatically disposed, except when disposeLayers is true.

    Parameters

    • options: {
          disposeLayers?: boolean;
      } = ...

      Options.

      • OptionaldisposeLayers?: boolean

    Returns void

filterChangeSources

forEachLayer

getBoundingBox

getColorLayers

getElevation

getElevationLayers

getElevationMinMax

  • getElevationMinMax(): ElevationRange

  • Returns the minimal and maximal elevation values in this map, in meters.

    If there is no elevation layer present, returns { min: 0, max: 0 }.

    Returns ElevationRange

    The min/max value.

getIndex

getLayers

getMemoryUsage

hasEventListener

  • hasEventListener<T>(type, listener): boolean

  • Checks if listener is added to an event type.

    Type Parameters

    • T extends
          | "initialized"
          | "frozen-property-changed"
          | "visible-property-changed"
          | "layer-order-changed"
          | "layer-added"
          | "layer-removed"
          | "elevation-changed"
          | "opacity-property-changed"
          | "clippingPlanes-property-changed"
          | "renderOrder-property-changed"
          | "object-created"

    Parameters

    Returns boolean

  • hasEventListener<T>(type, listener): boolean

  • Type Parameters

    • T extends string

    Parameters

    Returns boolean

insertLayerAfter

  • insertLayerAfter(layer, target): void

  • Moves the specified layer after the other layer in the list.

    Parameters

    Returns void

    Throws

    If the layer is not present in the map.

    Example

    map.addLayer(foo);
    map.addLayer(bar);
    map.addLayer(baz);
    // Layers (back to front) : foo, bar, baz

    map.insertLayerAfter(foo, baz);
    // Layers (back to front) : bar, baz, foo

ProtectedisOwned

  • isOwned(obj): boolean

  • Returns true if this object belongs to this entity.

    Parameters

    • obj: unknown

      The object to test.

    Returns boolean

moveLayerDown

  • moveLayerDown(layer): void

  • Moves the layer closer to the background.

    Note: this only applies to color layers.

    Parameters

    Returns void

    Throws

    If the layer is not present in the map.

    Example

    map.addLayer(foo);
    map.addLayer(bar);
    map.addLayer(baz);
    // Layers (back to front) : foo, bar, baz

    map.moveLayerDown(baz);
    // Layers (back to front) : foo, baz, bar

moveLayerUp

  • moveLayerUp(layer): void

  • Moves the layer closer to the foreground.

    Note: this only applies to color layers.

    Parameters

    Returns void

    Throws

    If the layer is not present in the map.

    Example

    map.addLayer(foo);
    map.addLayer(bar);
    map.addLayer(baz);
    // Layers (back to front) : foo, bar, baz

    map.moveLayerUp(foo);
    // Layers (back to front) : bar, foo, baz

ProtectednotifyChange

ProtectedonObjectCreated

  • onObjectCreated(obj): void

  • Applies entity-level setup on a new object.

    Note: this method should be called from the subclassed entity to notify the parent class that a new 3D object has just been created, so that it can be setup with entity-wide parameters.

    Parameters

    Returns void

    Example

    // In the subclass
    const obj = new Object3D();

    // Notify the parent class
    this.onObjectCreated(obj);

onRenderingContextLost

  • onRenderingContextLost(options): void

  • Called when the rendering context has been lost.

    Parameters

    • options: {
          canvas: HTMLCanvasElement;
      }

      The options.

      • canvas: HTMLCanvasElement

    Returns void

onRenderingContextRestored

pick

pickFeaturesFrom

postUpdate

preprocess

  • preprocess(): Promise<void>

  • Asynchronously preprocess the entity. This method may be overriden to perform any operation that must be done before the entity can be used in the scene, such as fetching metadata about a dataset, etc.

    Returns Promise<void>

    A promise that resolves when the entity is ready to be used.

preUpdate

  • preUpdate(context, changeSources): TileMesh[]

  • This method is called just before update() to filter and select which elements should be actually updated. For example, in the case of complex entities made of a hierarchy of elements, the entire hierarchy may not need to be updated.

    Use this method to optimize the update step by reducing the number of elements to process.

    Note: if this functions returns nothing, update() will not be called.

    Parameters

    • context: Context

      the update context.

    • changeSources: Set<unknown>

      the objects that triggered an update step. This is useful to filter out unnecessary updates if no sources are relevant to this entity. For example, if one of the sources is a camera that moved during the previous frame, any entity that depends on the camera's field of view should be updated.

    Returns TileMesh[]

    the elements to update during update().

raycast

  • raycast(raycaster, intersects): void

  • Perform raycasting on visible tiles.

    Parameters

    • raycaster: Raycaster

      The THREE raycaster.

    • intersects: Intersection<TileMesh>[]

      The intersections array to populate with intersections.

    Returns void

removeEventListener

  • removeEventListener<T>(type, listener): void

  • Removes a listener from an event type.

    Type Parameters

    • T extends
          | "initialized"
          | "frozen-property-changed"
          | "visible-property-changed"
          | "layer-order-changed"
          | "layer-added"
          | "layer-removed"
          | "elevation-changed"
          | "opacity-property-changed"
          | "clippingPlanes-property-changed"
          | "renderOrder-property-changed"
          | "object-created"

    Parameters

    Returns void

  • removeEventListener<T>(type, listener): void

  • Type Parameters

    • T extends string

    Parameters

    Returns void

removeLayer

  • removeLayer(layer, options?): boolean

  • Removes a layer from the map.

    Parameters

    • layer: Layer<LayerEvents, LayerUserData>

      the layer to remove

    • options: {
          disposeLayer?: boolean;
      } = {}

      The options.

      • OptionaldisposeLayer?: boolean

        If true, the layer is also disposed.

    Returns boolean

    true if the layer was present, false otherwise.

ProtectedsetupMaterial

  • setupMaterial(material): void

  • Applies entity-level setup on new object's material.

    Subclasses can override this to setup custom logic, for instance if the entity can produce objects that are naturally transparent.

    Parameters

    • material: Material

      the material of the newly created object

    Returns void

shouldCheckForUpdate

  • shouldCheckForUpdate(): boolean

  • This method is called before update to check if the MainLoop should try to update this entity or not. For better performances, it should return false if the entity has no impact on the rendering (e.g. the element is not visible).

    The inherited child can completely ignore this value if it makes sense.

    Returns boolean

    true if should check for update

shouldFullUpdate

  • shouldFullUpdate(updateSource): boolean

  • This method is called at the beginning of the update step to determine if we should do a full render of the object. This should be the case if, for instance, the source is the camera.

    You can override this depending on your needs. The inherited child should not ignore this value, it should do a boolean OR, e.g.: return super.shouldFullUpdate(updateSource) || this.contains(updateSource);

    Parameters

    • updateSource: unknown

      Source of change

    Returns boolean

    true if requires a full update of this object

shouldUpdate

  • shouldUpdate(updateSource): boolean

  • This method is called at the beginning of the update step to determine if we should re-render updateSource. Not used when shouldFullUpdate returns true.

    You can override this depending on your needs. The inherited child should not ignore this value, it should do a boolean OR, e.g.: return super.shouldUpdate(updateSource) || this.contains(updateSource);

    Parameters

    • updateSource: unknown

      Source of change

    Returns boolean

    true if requires an update of updateSource

sortColorLayers

  • sortColorLayers(compareFn): void

  • Sort the color layers according to the comparator function.

    Parameters

    Returns void

traverse

traverseMaterials

traverseMeshes

traverseTiles

  • traverseTiles(callback, root?): void

  • Traverses all tiles in the hierarchy of this entity.

    Parameters

    • callback: ((arg0: TileMesh) => void)

      The callback.

        • (arg0): void

        • Parameters

          • arg0: TileMesh

          Returns void

    • root: undefined | Object3D<Object3DEventMap> = undefined

      The raversal root. If undefined, the traversal starts at the root object of this entity.

    Returns void

update

  • update(context, node): undefined | unknown[]

  • Performs an update on an element of the entity.

    Note: this method will be called for each element returned by preUpdate().

    Parameters

    • context: Context

      the update context. This is the same object that the entity whose update() is being called.

    • node: TileMesh

    Returns undefined | unknown[]

    New elements to update

updateClippingPlanes

updateOpacity

updateRenderOrder

updateVisibility

Settings

Member Visibility

On This Page

Supported layersPicking on maps
Constructors
Properties
Accessors
Methods