Pointcloud styling

Cognite Data Fusion has a concept of "objects" in point clouds, represented by one or more bounding volumes for each object. The objects are backed by the CDF Annotations API or CDF CognitePointCloudVolume. Reveal supports styling individual objects within a point cloud.

In this context, a stylable object is represented by a volume in space. Styling an object results in all points that lie within the corresponding volume to attain the assigned style.

Stylable objects must be supplied separately from the model itself. Upon adding a new point cloud model to the viewer, Reveal will automatically fetch data describing the point cloud objects from CDF's Annotations API or CDF's CognitePointCloudVolume, if any are available. To get the number of fetched stylable objects, use the property model.stylableObjectCount, where model is a CognitePointCloudModel.

After the model and associated stylable objects are loaded, you may list the objects using model.stylableObjects. This contains all stylable objects as instances of PointCloudObjectMetadata, containing the following fields for CDF's Annotations:

Field	Field type	Description
annotationId	number	The ID of the CDF annotation that this stylable object corresponds to.
assetRef	AnnotationsAssetRef?	A reference to an asset. Either the internal ID or the external ID, if any.
boundingBox	THREE.Box3	The bounding box of the stylable object in Reveal space.

And contains following fields for CDF's CognitePointCloudVolume

Field	Field type	Description
volumeInstanceRef	DMInstanceRef	Reference to the CognitePointCloudVolume. It consists of a space and an external Id.
assetRef	DMInstanceRef?	Reference to the CogniteAsset. It consists of a space and an external Id, if any.
boundingBox	THREE.Box3	The bounding box of the stylable object in Reveal space.

To visualize all bounding boxes associated with the stylable objects:

Live Editor

Point cloud objects can be styled with a PointCloudAppearance object, containing the following attributes:

Field	Field type	Description
color	THREE.Color?	Override color. If all components equal to zero, the override is unused.
visible	boolean?	When false, stylable object will be invisible. Default value is true.

To assign a style to one or more stylable objects, you must first create an instance of the abstract class PointCloudAnnotationVolumeCollection. The AnnotationIdPointCloudObjectCollection class can be used for CDF's Annotations, which is initialized with a list of annotation IDs corresponding to stylable objects.

The PointCloudDMVolumeCollection class can be used for styling with CDF's Core datamodel CognitePointCloudVolume, which is initialized with a list of DM references. To see all available annotation IDs or point cloud volume references associated with the model, you may use the model.stylableObjects.

To color all stylable objects green for annotation IDs:

Live Editor

To color all stylable objects blue for point cloud volume references:

const pointCloudVolumeRefs = [];

model.stylableObjects.forEach(objectMetadata => {
  if (isDMPointCloudVolume(objectMetadata))
    pointCloudVolumeRefs.push(objectMetadata.volumeInstanceRef);
});

const objectCollection = new PointCloudDMVolumeCollection(pointCloudVolumeRefs);
const appearance = { color: new THREE.Color(0, 0, 1) };

model.assignStyledObjectCollection(objectCollection, appearance);

After assigning style to an object collection, you may use the property model.styledCollections to get a list of all object collections and their assigned styles registered on the model.

Default appearance

It is also possible to set a default appearance for the point cloud using the model.setDefaultPointCloudAppearance. The following example makes all annotated objects visible, while hiding everything else:

Live Editor

For Cognite core data model point cloud model

const pointCloudVolumeRefs = [];

model.stylableObjects.forEach(objectMetadata => {
  if (isDMPointCloudVolume(objectMetadata))
    pointCloudVolumeRefs.push(objectMetadata.volumeInstanceRef);
});

const objectCollection = new PointCloudDMVolumeCollection(pointCloudVolumeRefs);
const appearance = { visible: true };

model.assignStyledObjectCollection(objectCollection, appearance);
model.setDefaultPointCloudAppearance({ visible: false });

Like in CAD styling, stylable objects that are part of multiple styled object collections will attain the appearance of the object set whose first style assignment was last.

Unassigning styled object collections

To reset style of an object collection, use model.unassignStyledObjectCollection with the previously styled PointCloudAnnotationVolumeCollection as argument. To reset all styled objects use model.removeAllStyledCollections

Reset all styled object collections

To reset all styled object collections, use the method model.removeAllStyledObjectCollections().

This example removes all style on stylable object collections and makes sure the rest of the point cloud is visible.

Live Editor

Point cloud shapes

Currently, the only supported shapes that constitute point cloud objects are cylinders and boxes. The specification for how this data is stored, can be found in the API documentation for Retrieve Annotation under Responses -> 200 Successful retrieval -> data -> pointcloud.BoundingVolume. And for Cognite core data model refer CognitePointCloudVolume.

Note that Reveal will visualize the shapes with a somewhat larger size than how they are stored, as to make sure that all points that lie on the surface of the objects also are included as parts of it.