360 Image Annotations

360-images may be connected to annotations that outline regions of interest in the images. They are only visible when the user has entered the 360 image with which they are associated. Reveal automatically finds and downloads any relevant annotations from CDF and displays them by default.

Annotation requirements

Reveal only considers annotations following specific requirements. For an annotation to be found by Reveal, it must have its annotatedResourceId set to the ID of an image file belonging to the 360 image set. Furthermore, annotatedResourceType must be "file" and annotationType must be either "images.ObjectDetection" or "images.AssetLink". Currently, only annotations containing either a boundingBox or a polygon is supported, polyline annotations will not be displayed. Refer to the CDF documentation for details on the annotation types.

Annotations are represented by Image360Annotation instances. The annotations associated with a given entity revision can be queried with the getAnnotations() method on the Image360Revision instance. Note that annotations are loaded lazily, i.e. they will only be loaded when entering the relevant 360 image revision or when calling getAnnotations().

Styling Annotations

The appearance of annotations can be changed both through a "default" style and through styling annotations individually.

Default style

To set a default style for all annotations in an Image360Collection, you may call the collection.setDefaultStyle(appearance), where collection is an Image360Collection instance. The appearance argument is an Image360AnnotationAppearance instance, which has the following content:

Image360AnnotationAppearance

Field	Field type	Description
color	THREE.Color?	The color of the annotation
visible	boolean?	Whether the annotation should be visible or not

Leaving any of the fields undefined causes the annotations to revert to the original value for that property.

Using this, we can e.g. hide all annotations using

collection.setDefaultAnnotationStyle({ visible: false });

Individual style

Setting individual style can be done directly on an Image360Annotation object. Styling fields set this way will override those of the default appearance. E.g. to hide all annotations created by 'user0' in a revision, you may write

revision
  .getAnnotations()
  .then(annotations =>
    {
      annotations
        .filter(annotation => annotation.annotation.creatingUser === 'user0')
        .forEach(annotation => annotation.setVisible(false));
      viewer.requestRedraw();
    }
  );

Changes to individual styles are not visible until the next render, thus one should issue a call to viewer.requestRedraw() after applying styles to image annotations.

Since annotations are lazy-loaded, it is usually appropriate to only first apply styling upon entering the relevant revision. This can be done e.g. through registering a listener on the collection:

collection.on('image360Entered', (entity, revision) => {
  revision
    .getAnnotations()
    .then(annotations => { styleAnnotations(annotations); viewer.requestRedraw(); });
});

Mouse pointer interaction

The application may react to mouse interactions with annotations by subscribing to e.g. click-events on the viewer object, and subsequently using the received mouse position in the get360AnnotationIntersectionFromPixel method on the Cognite3DViewer instance. Note that this method will only check interactions with annotations that are associated with the current image360 revision and visible.

To e.g. color every clicked annotation with a blue color, you may write

viewer.on('click', event => {
  viewer.get360AnnotationIntersectionFromPixel(
    event.offsetX, event.offsetY
  ).then(
    intersection => {
      intersection?.annotation.setColor(new THREE.Color(0, 0, 1));
      viewer.requestRedraw();
    }
  );
});