Construct a FeatureCollection
.
Constructor options.
Optional
dataThe projection code for the projections of the features. If null or empty,
no reprojection will be done. If a valid epsg code is given and if different from
instance.referenceCrs
, each feature will be reprojected before mesh
conversion occurs. Note that reprojection can be somewhat heavy on CPU resources.
Optional
elevation?: number | number[] | FeatureElevationCallbackSet the elevation of the features received from the source.
It can be a constant for every feature, or a callback.
The callback version is particularly useful to derive the elevation
from the properties of the feature.
Requires _ignoreZ to be false
.
The geographic extent of the entity.
Optional
extrusionIf set, this will cause 2D features to be extruded of the corresponding amount. If a single value is given, it will be used for all the vertices of every feature. If an array is given, each extruded vertex will use the corresponding value. If a callback is given, it allows to extrude each feature individually.
Optional
ignoreZ?: booleanIf true, the Z-coordinates of geometries will be ignored and set to zero.
false
Optional
lineAn optional material generator for lines.
Optional
maxThe max level to subdivide the extent and process features.
Optional
minThe min subdivision level to start processing features. Useful for WFS or other untiled servers, to avoid to download the entire dataset when the whole extent is visible.
Optional
object3d?: Object3D<Object3DEventMap>The optional 3D object to use as the root
Optional
pointAn optional material generator for points.
Optional
shadedAn optional material generator for shaded surfaces.
The OpenLayers VectorSource providing features to this entity
Optional
style?: FeatureStyle | FeatureStyleCallbackAn style or a callback returning a style to style the individual features. If an object is used, the informations it contains will be used to style every feature the same way. If a function is provided, it will be called with the feature. This allows to individually style each feature.
Optional
unshadedAn optional material generator for unshaded surfaces.
Protected
_distanceReadonly
dataThe projection code of the data source.
Readonly
extentThe extent of this entity.
Readonly
idThe unique identifier of this entity.
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 FeatureCollection.
Readonly
isReadonly
isReadonly
maxThe maximum LOD at which this entity is displayed.
Readonly
minThe minimum LOD at which this entity is displayed.
The name of this entity.
The factor to drive the subdivision of feature nodes. The heigher, the bigger the nodes.
Readonly
typeThe name of the type of this object.
Readonly
userAn object that can be used to store custom data about the Entity.
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 whether this entity is currently loading data.
The number of materials managed by this entity.
Returns the root object of this entity.
Gets or sets the opacity of this entity.
Gets the progress value of the data loading.
Determine if this entity is ready to use.
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 listener to an event type.
The type of event to listen to.
The function that gets called when the event is fired.
Protected
assignAssigns the render order of this object.
This may be overriden to perform custom logic.
Fire an event type.
The event that gets fired.
Disposes this entity and all resources associated with it.
The default implementation of this method does nothing. You should implement it in your custom entities to handle any special logic of disposal.
For example: disposing materials, geometries, stopping HTTP requests, etc.
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
Returns an approximation of the memory used by this object, in bytes.
The graphics context.
Checks if listener is added to an event type.
The type of event to listen to.
The function that gets called when the event is fired.
Protected
isProtected
notifyProtected
onApplies 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: PickOptionsMethod called after Entity.update.
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.
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 listener from an event type.
The type of the listener that gets removed.
The listener function that gets removed.
Protected
setupApplies 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.
the material of the newly created object
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
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.
Performs an update on an element of the entity.
Note: this method will be called for each element returned by preUpdate()
.
New elements to update
Updates the styles of the given objects, or all objects if unspecified.
Optional
objects: (SimpleGeometryMesh<MeshUserData, SimpleGeometryMeshEventMap> | default<MeshUserData>)[]The objects to update.
An Entity3D that represent simple features as 3D meshes.
❗ Arbitrary triangulated meshes (TINs) are not supported.
Supported geometries
Both 2D and 3D geometries are supported. In the case of 2D geometries (with only XY coordinates), you can specify an elevation (Z) to display the geometries at arbitrary heights, using the
elevation
option in the constructor.Supported geometries:
extrusionOffset
constructor option.Data sources
At the moment, this entity accepts an OpenLayers VectorSource that returns features.
NOTE: if your source doesn't have a notion of level of detail, like a WFS server, you must choose one level where data will be downloaded. The level giving the best user experience depends on the data source. You must configure both
minLevel
andmaxLevel
to this level.For example, in the case of a WFS source:
Supported CRSes
The
FeatureCollection
supports the reprojection of geometries if the source has a different CRS than the scene. Any custom CRS must be registered first with Instance.registerCRS().Related examples:
Styling
Features can be styled using a FeatureStyle, either using the same style for the entire entity, or using a style function that will return a style for each feature.
❗ All features that share the same style will internally use the same material. It is not advised to modify this material to avoid affecting all shared objects. Those materials are automatically disposed when the entity is removed from the instance.
Textures used by point styles are also disposed if they were created internally by the entity (from a provided URL) rather than provided as a texture.
Overriding material generators
By default, styles are converted to materials using default generator functions. It is possible to override those function to create custom materials. For example, to use custom line materials, you can pass the
lineMaterialGenerator
option to the constructor.