The type of the entities.Entity#userData property.
Constructs a Map object.
The unique identifier of the map.
Constructor options.
Protected _distanceProtected _instanceReadonly hasRead-only flag to check if a given object is of type HasLayers.
Readonly isRead-only flag to check if a given object is of type Entity.
Readonly isRead-only flag to check if a given object is of type Entity3D.
Readonly isRead-only flag to check if a given object is of type Map.
Readonly isReadonly isReadonly materialReadonly maxOptional readyReadonly showThe 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.
1.5
The name of the type of this object.
Readonly userAn object that can be used to store custom data about the Entity.
Optional whenDisplays the map tiles in wireframe.
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.
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.
Gets the unique identifier of this entity.
Returns the number of layers currently in this object.
Returns true if this map is currently processing data.
Returns the root object of this entity.
Gets or sets the opacity of this entity.
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.
Gets or sets the render order of this entity.
Gets or sets the visibility of this entity. A non-visible entity will not be automatically updated.
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.
the layer to add
a promise resolving when the layer is ready
Filters what objects need to be updated, based on updatedSources.
The returned objects are then passed to preUpdate and postUpdate.
Inherited classes should override shouldFullUpdate and shouldUpdate if they need to change this behavior.
Sources that triggered an update
Set of objects to update
Applies the callback to each layer in the object.
Gets all color layers in this map.
the color layers
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.
The options.
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.
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.
Gets all elevation layers in this map.
the elevation layers
Returns the minimal and maximal elevation values in this map, in meters.
If there is no elevation layer present, returns { min: 0, max: 0 }.
The min/max value.
Returns the position of the layer in the layer list.
The layer to search.
The index of the layer.
Gets all layers that satisfy the filter predicate.
Optional predicate: ((arg0) => boolean)the optional predicate.
the layers that matched the predicate or all layers if no predicate was provided.
Returns an approximation of the memory used by this object, in bytes.
The graphics context.
Optional target: MemoryUsageReportIf specified, the values computed during this call must be added to the existing values in the target. Otherwise, a new report must be built.
The memory usage report. If target is specified, then this must be returned.
Attached layers expect to receive the visual representation of a layer (= THREE object with a material). So if a layer's update function don't process this kind of object, the layer must provide a getObjectToUpdateForAttachedLayers function that returns the correct object to update for attached layer from the objects returned by preUpdate.
the Mesh or the object containing a Mesh. These are the objects returned by preUpdate or update.
an object passed to the update function of attached layers.
Moves the specified layer after the other layer in the list.
The layer to move.
The target layer. If null, then the layer is put at the
beginning of the layer list.
If the layer is not present in the map.
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
Protected isMoves the layer closer to the background.
Note: this only applies to color layers.
The layer to move.
If the layer is not present in the map.
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.
The layer to move.
If the layer is not present in the map.
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.
The object to prepare.
// In the subclass
const obj = new Object3D();
// Notify the parent class
this.onObjectCreated(obj);
Optional options: PickOptionsOptional options: PickOptionsMethod called after Entity.update.
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.
the update context.
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.
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.
A promise that resolves when the entity is ready to be used.
Removes a layer from the map.
the layer to remove
The options.
Optional disposeIf true, the layer is also disposed.
true if the layer was present, false otherwise.
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.
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);
Source of change
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);
Source of change
true if requires an update of updateSource
Sort the color layers according to the comparator function.
The comparator function.
Traverses all objects in the hierarchy of this entity.
The callback.
The traversal root. If undefined, the traversal starts at the root object of this entity.
Traverses all materials in the hierarchy of this entity.
The callback.
The traversal root. If undefined, the traversal starts at the root object of this entity.
Traverses all meshes in the hierarchy of this entity.
The callback.
The raversal root. If undefined, the traversal starts at the root object of this entity.
Traverses all tiles in the hierarchy of this entity.
The callback.
The raversal root. If undefined, the traversal starts at the root object of this entity.
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.