Class FeatureCollection<UserData>

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:

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 and maxLevel to this level.

For example, in the case of a WFS source:

import VectorSource from 'ol/source/Vector.js';
import FeatureCollection from '@giro3d/giro3d/entities/FeatureCollection';

const vectorSource = new VectorSource({
 // ...
});
const featureCollection = new FeatureCollection('features', {
 source: vectorSource
 minLevel: 10,
 maxLevel: 10,
 elevation: (feature) => feat.getProperties().elevation,
});

instance.add(featureCollection);

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.

Type Parameters

Hierarchy (view full)

Constructors

constructor

Properties

_distance dataProjection extent hasDefaultPointOfView id isEntity isEntity3D isFeatureCollection isMemoryUsage isPickable maxLevel minLevel name sseScale type userData

Accessors

castShadow clippingPlanes distance frozen instance loading materialCount object3d opacity progress ready receiveShadow renderOrder visible

Methods

addEventListener assignRenderOrder contains dispatchEvent dispose filterChangeSources getBoundingBox getDefaultPointOfView getMemoryUsage hasEventListener isOwned notifyChange onObjectCreated onRenderingContextLost onRenderingContextRestored pick postUpdate preprocess preUpdate removeEventListener setupMaterial shouldCheckForUpdate shouldFullUpdate shouldUpdate traverse traverseGeometries traverseMaterials traverseMeshes update updateClippingPlanes updateOpacity updateRenderOrder updateStyles updateVisibility

Constructors

constructor

  • new FeatureCollection<UserData>(options): FeatureCollection<UserData>

  • Construct a FeatureCollection.

    Type Parameters

    Parameters

    • options: {
          dataProjection?: string;
          elevation?: FeatureElevation | FeatureElevationCallback;
          extent: Extent;
          extrusionOffset?: FeatureExtrusionOffset | FeatureExtrusionOffsetCallback;
          ignoreZ?: boolean;
          lineMaterialGenerator?: LineMaterialGenerator;
          maxLevel?: number;
          minLevel?: number;
          object3d?: Object3D<Object3DEventMap>;
          pointMaterialGenerator?: PointMaterialGenerator;
          shadedSurfaceMaterialGenerator?: SurfaceMaterialGenerator;
          source: Vector<Feature<Geometry>>;
          style?: FeatureStyle | FeatureStyleCallback;
          unshadedSurfaceMaterialGenerator?: SurfaceMaterialGenerator;
      }

      Constructor options.

      • OptionaldataProjection?: string

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

      • Optionalelevation?: FeatureElevation | FeatureElevationCallback

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

      • extent: Extent

        The geographic extent of the entity.

      • OptionalextrusionOffset?: FeatureExtrusionOffset | FeatureExtrusionOffsetCallback

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

      • OptionalignoreZ?: boolean

        If true, the Z-coordinates of geometries will be ignored and set to zero.

        Default Value

        false
      • OptionallineMaterialGenerator?: LineMaterialGenerator

        An optional material generator for lines.

      • OptionalmaxLevel?: number

        The max level to subdivide the extent and process features.

      • OptionalminLevel?: number

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

      • Optionalobject3d?: Object3D<Object3DEventMap>

        The optional 3D object to use as the root

      • OptionalpointMaterialGenerator?: PointMaterialGenerator

        An optional material generator for points.

      • OptionalshadedSurfaceMaterialGenerator?: SurfaceMaterialGenerator

        An optional material generator for shaded surfaces.

      • source: Vector<Feature<Geometry>>

        The OpenLayers VectorSource providing features to this entity

      • Optionalstyle?: FeatureStyle | FeatureStyleCallback

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

      • OptionalunshadedSurfaceMaterialGenerator?: SurfaceMaterialGenerator

        An optional material generator for unshaded surfaces.

    Returns FeatureCollection<UserData>

Properties

Protected_distance

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

ReadonlydataProjection

dataProjection: null | string

The projection code of the data source.

Readonlyextent

extent: Extent

The extent of this entity.

ReadonlyhasDefaultPointOfView

hasDefaultPointOfView: true = ...

Readonly flag to check if a given object implements HasDefaultPointOfView.

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.

ReadonlyisFeatureCollection

isFeatureCollection: true = ...

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

ReadonlyisMemoryUsage

isMemoryUsage: true = ...

Readonly flag to indicate that his object implements MemoryUsage.

ReadonlyisPickable

isPickable = true

ReadonlymaxLevel

maxLevel: number = 0

The maximum LOD at which this entity is displayed.

ReadonlyminLevel

minLevel: number = 0

The minimum LOD at which this entity is displayed.

name

name: undefined | string

The name of this entity.

sseScale

sseScale: number = 1

The factor to drive the subdivision of feature nodes. The heigher, the bigger the nodes.

Readonlytype

type: "FeatureCollection" = ...

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

castShadow

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

distance

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

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

    • max: number
    • min: number

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

instance

loading

materialCount

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

ready

  • get ready(): boolean

  • Determine if this entity is ready to use.

    Returns boolean

receiveShadow

renderOrder

  • get renderOrder(): number

  • Gets or sets the render order of this entity.

    Returns number

  • set renderOrder(v): void

  • Parameters

    • v: number

    Returns void

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

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"
          | "opacity-property-changed"
          | "clippingPlanes-property-changed"
          | "renderOrder-property-changed"
          | "object-created"

    Parameters

    Returns void

ProtectedassignRenderOrder

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"
          | "opacity-property-changed"
          | "clippingPlanes-property-changed"
          | "renderOrder-property-changed"
          | "object-created"

    Parameters

    Returns void

dispose

  • dispose(): void

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

    Returns void

filterChangeSources

getBoundingBox

getDefaultPointOfView

  • getDefaultPointOfView(params): null | Readonly<PointOfView>

  • Default implementation that computes a point of view from the bounding box of the entity, if any.

    Parameters

    • params: {
          camera: Camera;
      }
      • camera: Camera

        The camera to compute the point of view.

    Returns null | Readonly<PointOfView>

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"
          | "opacity-property-changed"
          | "clippingPlanes-property-changed"
          | "renderOrder-property-changed"
          | "object-created"

    Parameters

    Returns boolean

ProtectedisOwned

  • isOwned(obj): boolean

  • Returns true if this object belongs to this entity.

    Parameters

    • obj: unknown

      The object to test.

    Returns boolean

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

postUpdate

  • postUpdate(context, changeSources): void

  • Method called after Entity.update.

    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 void

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(_, changeSources): FeatureTile[]

  • 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

      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 FeatureTile[]

    the elements to update during update().

removeEventListener

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

  • Removes a listener from an event type.

    Type Parameters

    • T extends
          | "initialized"
          | "frozen-property-changed"
          | "visible-property-changed"
          | "opacity-property-changed"
          | "clippingPlanes-property-changed"
          | "renderOrder-property-changed"
          | "object-created"

    Parameters

    Returns void

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

traverse

traverseGeometries

traverseMaterials

traverseMeshes

update

  • update(ctx, tile): undefined | null | FeatureTile[]

  • Performs an update on an element of the entity.

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

    Parameters

    Returns undefined | null | FeatureTile[]

    New elements to update

updateClippingPlanes

updateOpacity

updateRenderOrder

updateStyles

updateVisibility

Settings

Member Visibility

On This Page

Supported geometriesData sourcesSupported CRSesStyling
Constructors
Properties
Accessors
Methods