Warning

Nightly releases are generated automatically from the latest source code and are intended for experimental purposes only. These builds may contain incomplete or untested features, bugs, or security vulnerabilities, and as such, are not for production use. Users should be aware that nightly releases may cause unexpected behavior, data loss, or system instability. Use of these releases is at the user's own risk, and it is advised to have adequate backups before testing. The software is provided as is with no guarantees or support.

AnnotationAPI

Interface AnnotationAPI

Overview

The AnnotationAPI provides a set of tools for creating and managing annotations via the webvis context. It allows you to:

  • Create annotations and attach them to specific nodes in a scene.
  • Edit and update existing annotations.
  • Retrieve all annotations at once.
  • Request detailed annotation data for a specific annotations.
  • Remove annotations when they are no longer needed.

Examples of all operations are provided below.

Quick Start

The fastest way to get familiar with the AnnotationAPI is by creating annotations via the webvis context. Once you have the context, you can call the annotation methods directly.

Example: Create, update and remove an annotation using the AnnotationAPI and connect the annotation to a node.

// Get the webvis context
const context = webvis.getContext();

// Create a node to attach the annotation to and enable the resource to make it visible
const nodeID = context.add({dataURI: "urn:x-i3d:shape:box", initialProperties: {enabled: true}});

// Define custom annotation data using the AnnotationProperties type
const customAnnotationData = {
     anchorPosition: [0, 0, 0],
     connectedNodeId: 1,
     content: "New Annotation",
     contentOffset: [0, 0.5, 0],
     enabled: true,
     name: "Annotation 1",
     trustedSource: true
 };

// Create an annotation using the custom annotation data
const annotationId = context.createAnnotation(customAnnotationData);

// Fetch the data of the newly created annotation 
const annotationData = await context.requestAnnotationData(annotationId); 
console.log("Fetched annotation data:", annotationData);

// Update the annotation with new content
context.changeAnnotation(annotationId, { content: "Updated Annotation" }); 

// Fetch the data of the updated annotation 
const updatedAnnotationData = await context.requestAnnotationData(annotationId); 
console.log("Fetched updated annotation data:", updatedAnnotationData);

// Remove the annotation if no longer required 
context.removeAnnotation(annotationId);

Events

The following events are associated with the AnnotationAPI:

interface AnnotationAPI {
    changeAnnotation(
        annotationId: number,
        properties: AnnotationProperties,
    ): AnnotationProperties;
    changeAnnotation(
        annotationID: number,
        label?: string,
        visible?: boolean,
        anchorPosition?: number[] | Float32Array<ArrayBufferLike>,
        labelPosition?: number[] | Float32Array<ArrayBufferLike>,
        active?: boolean,
        transform?: number[] | Float32Array<ArrayBufferLike>,
    ): void;
    createAnnotation(properties?: AnnotationProperties): number;
    createAnnotation(
        nodeID: number,
        label: string,
        visible?: boolean,
        anchorPosition?: number[] | Float32Array<ArrayBufferLike>,
        labelOffset?: number[] | Float32Array<ArrayBufferLike>,
    ): number;
    getAnnotationData(annotationId: number): AnnotationData;
    getAnnotations(): number[];
    removeAnnotation(annotationId: number, safe?: boolean): RemoveState;
    requestAnnotationData(annotationId: number): Promise<AnnotationProperties>;
}

Hierarchy (View Summary)

Methods

changeAnnotation createAnnotation getAnnotationData getAnnotations removeAnnotation requestAnnotationData

Methods

changeAnnotation

  • changeAnnotation(
        annotationId: number,
        properties: AnnotationProperties,
    ): AnnotationProperties

  • Changes one or more properties of an Annotation with the specified ID and triggers an AnnotationChangedEvent.

    Parameters

    • annotationId: number

      The ID of the Annotation you want to change.

    • properties: AnnotationProperties

      The properties of the Annotation you want change.

    Returns AnnotationProperties

    An Object with the changed Properties.

  • changeAnnotation(
        annotationID: number,
        label?: string,
        visible?: boolean,
        anchorPosition?: number[] | Float32Array<ArrayBufferLike>,
        labelPosition?: number[] | Float32Array<ArrayBufferLike>,
        active?: boolean,
        transform?: number[] | Float32Array<ArrayBufferLike>,
    ): void

  • Parameters

    • annotationID: number

      The ID of the Annotation.

    • Optionallabel: string

      The text of the Annotation.

    • Optionalvisible: boolean

      Indicates if the Annotation should be visible or hidden.

    • OptionalanchorPosition: number[] | Float32Array<ArrayBufferLike>

      Anchor position in world space coordinates.

    • OptionallabelPosition: number[] | Float32Array<ArrayBufferLike>

      The position of the label.

    • Optionalactive: boolean

      DEPRECATED

    • Optionaltransform: number[] | Float32Array<ArrayBufferLike>

      The transformation of the Annotation.

    Returns void

    Deprecated

    Changes an annotation. Should use a properties object AnnotationProperties as an argument rather than passing individual values.

createAnnotation

  • createAnnotation(properties?: AnnotationProperties): number

  • Creates a new Annotation and triggers an AnnotationCreatedEvent.

    Parameters

    Returns number

    The ID of the newly created Annotation.

  • createAnnotation(
        nodeID: number,
        label: string,
        visible?: boolean,
        anchorPosition?: number[] | Float32Array<ArrayBufferLike>,
        labelOffset?: number[] | Float32Array<ArrayBufferLike>,
    ): number

  • Parameters

    • nodeID: number

      The ID of the node that the Annotation belongs to.

    • label: string

      The text of the Annotation.

    • Optionalvisible: boolean

      Indicates if the Annotation should be visible or hidden.

    • OptionalanchorPosition: number[] | Float32Array<ArrayBufferLike>

      Anchor position in world space coordinates.

    • OptionallabelOffset: number[] | Float32Array<ArrayBufferLike>

      The offset between anchorPosition and where the label should be displayed.

    Returns number

    The ID of the new annotation.

    Deprecated

    Creates a new annotation. Should use a properties object AnnotationProperties as an argument rather than passing individual values.

getAnnotationData

  • getAnnotationData(annotationId: number): AnnotationData

  • Parameters

    • annotationId: number

      The ID of the Annotation.

    Returns AnnotationData

    The content and properties of an annotation.

    Deprecated

getAnnotations

  • getAnnotations(): number[]

  • Returns number[]

    The IDs of all available Annotations.

removeAnnotation

  • removeAnnotation(annotationId: number, safe?: boolean): RemoveState

  • Removes the Annotation from the scene and all related Snapshots and triggers an AnnotationRemovedEvent.

    Parameters

    • annotationId: number

      The ID of the Annotation.

    • Optionalsafe: boolean

      Performs a safe remove which interrupt the removal process if the Annotation is part of one or more Snapshots.

    Returns RemoveState

requestAnnotationData

  • requestAnnotationData(annotationId: number): Promise<AnnotationProperties>

  • Returns the AnnotationData for the specified Annotation ID.

    Parameters

    • annotationId: number

      The ID of the Annotation you want to request the data for.

    Returns Promise<AnnotationProperties>

    The requested Annotation data.