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

Properties

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

Type declaration

  • max: number
  • min: number
extent: Extent
hasLayers: true = ...

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

id: string

The unique identifier of this entity.

isEntity: boolean = ...

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

isEntity3D: boolean = ...

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

isMap: true = ...
isMemoryUsage: true = ...
isPickable: true = true
isPickableFeatures: true = true
maxSubdivisionLevel: number
name: undefined | string

The name of this entity.

showOutline: false = false
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

{@link DEFAULT_SUBDIVISION_THRESHOLD}
type: "Map" = ...

The name of the type of this object.

userData: UserData

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

Accessors

  • get backgroundOpacity(): number
  • Gets or sets the background opacity.

    Returns number

  • set backgroundOpacity(opacity): void
  • Parameters

    • opacity: number

    Returns void

  • 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

  • get depthTest(): boolean
  • Gets or sets depth testing on materials.

    Returns boolean

  • set depthTest(v): void
  • Parameters

    • v: boolean

    Returns void

  • get discardNoData(): boolean
  • Toggles discard no-data pixels.

    Returns boolean

  • set discardNoData(opacity): void
  • Parameters

    • opacity: boolean

    Returns void

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

    • max: number
    • min: number
  • 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

  • get layerCount(): number
  • Returns the number of layers currently in this object.

    Returns number

  • get loading(): boolean
  • Returns true if this map is currently processing data.

    Returns boolean

  • get opacity(): number
  • Gets or sets the opacity of this entity.

    Returns number

  • set opacity(v): void
  • Parameters

    • v: number

    Returns void

  • 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

  • get ready(): boolean
  • Determine if this entity is ready to use.

    Returns boolean

  • get renderOrder(): number
  • Gets or sets the render order of this entity.

    Returns number

  • set renderOrder(v): void
  • Parameters

    • v: number

    Returns void

  • get showColliderMeshes(): boolean
  • Shows meshes used for raycasting purposes.

    Returns boolean

  • set showColliderMeshes(show): void
  • Parameters

    • show: boolean

    Returns void

  • get showTileOutlines(): boolean
  • Shows tile outlines.

    Returns boolean

  • set showTileOutlines(show): void
  • Parameters

    • show: boolean

    Returns void

  • 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

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

    • x: number
    • y: number
  • 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

  • get wireframe(): boolean
  • Displays the map tiles in wireframe.

    Returns boolean

  • set wireframe(v): void
  • Parameters

    • v: boolean

    Returns void

Methods

  • Adds a listener to an event type.

    Type Parameters

    • T extends "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

  • Type Parameters

    • T extends string

    Parameters

    Returns void

  • 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

  • Parameters

    • node: TileMesh

      The node to subdivide.

    Returns boolean

    True if the node can be subdivided.

  • 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.

  • Fire an event type.

    Type Parameters

    • T extends "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

  • 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.

      • Optional disposeLayers?: boolean

    Returns void

  • Sample the elevation at the specified coordinate.

    Note: this method does nothing if TerrainOptions.enableCPUTerrain is not enabled, or if no elevation layer is present on the map, or if the sampling coordinate is not inside the map's extent.

    Note: sampling might return more than one sample for any given coordinate. You can sort them by resolution to select the best sample for your needs.

    Parameters

    • options: GetElevationOptions

      The options.

    • result: GetElevationResult = ...

      The result object to populate with the samples. If none is provided, a new empty result is created. The existing samples in the array are not removed. Useful to cumulate samples across different maps.

    Returns GetElevationResult

    The GetElevationResult containing the updated sample array. If the map has no elevation layer or if TerrainOptions.enableCPUTerrain is not enabled, this array is left untouched.

  • 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.

  • Checks if listener is added to an event type.

    Type Parameters

    • T extends "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

  • Type Parameters

    • T extends string

    Parameters

    Returns boolean

  • 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
  • Returns true if this object belongs to this entity.

    Parameters

    • obj: unknown

      The object to test.

    Returns boolean

  • 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
  • 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
  • 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);
  • Called when the rendering context has been lost.

    Parameters

    • options: {
          canvas: HTMLCanvasElement;
      }

      The options.

      • canvas: HTMLCanvasElement

    Returns void

  • 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().

  • 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.

  • Perform raycasting on visible tiles.

    Parameters

    • raycaster: Raycaster

      The THREE raycaster.

    • intersects: Intersection<TileMesh>[]

      The intersections array to populate with intersections.

    Returns void

  • Removes a listener from an event type.

    Type Parameters

    • T extends "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

  • Type Parameters

    • T extends string

    Parameters

    Returns void

  • Removes a layer from the map.

    Parameters

    • layer: Layer<LayerEvents, LayerUserData>

      the layer to remove

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

      The options.

      • Optional disposeLayer?: boolean

        If true, the layer is also disposed.

    Returns boolean

    true if the layer was present, false otherwise.

  • 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

  • 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

  • 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

  • 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

  • Sort the color layers according to the comparator function.

    Parameters

    Returns void

  • Traverses all materials in the hierarchy of this entity.

    Parameters

    • callback: ((arg0) => void)

      The callback.

        • (arg0): void
        • Parameters

          Returns void

    • root: undefined | Object3D<Object3DEventMap> = undefined

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

    Returns void

  • Traverses all tiles in the hierarchy of this entity.

    Parameters

    • callback: ((arg0) => 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

  • 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

      the element to update. This is one of the elements returned by preUpdate.

    Returns undefined | unknown[]

    New elements to update