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.

InstanceGraphAPI

Interface InstanceGraphAPI

InstanceGraphAPI

Overview

The InstanceGraphAPI allows for the control and manipulation of webvis content. The instance graph represents a scene graph-like tree structure of nodes, where each node can contain links to 3D geometry and/or group other nodes.

The getProperty and setProperty functions enable setting and retrieving properties of various types on the nodes. Properties are used to modify any node-dependent data, such as color, local transformation, etc. While there is a set of predefined node properties that webvis will respond to, the surrounding application can add any other custom properties to the nodes using registerCustomProperty.

All properties can be persisted by the different functionalities of the SessionStorageAPI.

Quick Start

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

// Add a new node to the InstanceGraph
const nodeId = context.add(
{
    dataURI: "urn:x-i3d:shape:box",
    label: "My node",
    initialProperties: { enabled: true }
});

// Register a custom property
context.registerCustomProperty("myCustomProperty", 0);

// Getting and setting properties
await context.setProperty(nodeId, "myCustomProperty", 42);
const [label, customProp] = await context.getProperties(nodeId, [webvis.Property.LABEL, "myCustomProperty"]);

console.log(label, customProp); // My node 42

Events

The InstanceGraphAPI emits the following events:

interface InstanceGraphAPI {
    add(options: AddNodeOptions): number;
    add(
        dataURI: string,
        parentID?: number,
        usage?: UsageString,
        label?: string,
        contentType?: string,
        initialProperties?: InitialNodeProperties,
        cacheStrategy?: CacheStrategy,
    ): number;
    addCustomNode(
        customNodeType: string,
        data: any,
        dataType?: AttachmentType,
    ): number;
    collectRuntimeNodesOfType(nodeType: NodeType, subType?: string): number[];
    getEnabledAuxNodes(nodeID: number): Promise<number[]>;
    getMetadata(nodeID: number): Promise<{ [key: string]: string }>;
    getProperties<T extends string>(
        nodeID: number,
        properties: T[],
    ): Promise<PropertyType<T>[]>;
    getProperty<T extends string>(
        nodeID: number,
        property: T,
    ): Promise<PropertyType<T>>;
    getRootNodeId(
        target: number | TopologyHandle,
        includeTarget?: boolean,
    ): number;
    getStatistics(
        nodeType?: NodeType,
        nodeID?: number,
        recursive?: boolean,
    ): Promise<any>;
    invertEnabledStates(): void;
    isNodeDeletable(nodeID: number): boolean;
    isNodeType(nodeID: number, nodeType: NodeType): boolean;
    registerCustomProperty(
        name: string,
        defaultValue: any,
        recursive?: boolean,
    ): void;
    remove(nodeID?: number | number[], safe?: boolean): Promise<RemoveState>;
    requestActiveSceneVolume(): Promise<BoxVolume>;
    requestAuxRootNodeIds(scopeNodeId?: number): Promise<number[]>;
    requestFullSceneVolume(): Promise<BoxVolume>;
    requestL3DInformation(targetNodeId: number): Promise<any>;
    requestNodeIdsByBoxVolume(
        boxVolume: BoxVolume,
        includeOverlappingNodes?: boolean,
        includeDisabledNodes?: boolean,
        forceExpand?: boolean,
        scopeNodeId?: number,
    ): Promise<number[]>;
    requestRootNodeIds(
        scopeNodeId?: number,
        recursive?: boolean,
    ): Promise<number[]>;
    resetProperties<T extends string>(
        nodeID: number,
        properties: T[],
        recursive?: boolean,
    ): Promise<void>;
    resetProperty<T extends string>(
        nodeID: number,
        property: T,
        recursive?: boolean,
    ): Promise<void>;
    setParent(nodeID: number, newParentID: number): void;
    setProperty<T extends string>(
        nodeID: number | number[],
        property: T,
        value: PropertyType<T>,
        silent?: boolean,
    ): Promise<void>;
}

Hierarchy (View Summary)

Methods

add addCustomNode collectRuntimeNodesOfType getEnabledAuxNodes getMetadata getProperties getProperty getRootNodeId getStatistics invertEnabledStates isNodeDeletable isNodeType registerCustomProperty remove requestActiveSceneVolume requestAuxRootNodeIds requestFullSceneVolume requestL3DInformation requestNodeIdsByBoxVolume requestRootNodeIds resetProperties resetProperty setParent setProperty

Methods

add

  • add(options: AddNodeOptions): number

  • Adds a new node to the instance graph.

    Parameters

    Returns number

    The ID of the added node

  • add(
        dataURI: string,
        parentID?: number,
        usage?: UsageString,
        label?: string,
        contentType?: string,
        initialProperties?: InitialNodeProperties,
        cacheStrategy?: CacheStrategy,
    ): number

  • Parameters

    • dataURI: string

      Specifies the URI to the data resource.

    • OptionalparentID: number

      Specifies the parent Node ID of the added Node.

    • Optionalusage: UsageString

      The usage parameter allows to define how the resource should be inserted in the InstanceGraph.

    • Optionallabel: string

      Specifies a custom label for the added Node.

    • OptionalcontentType: string

      Specifies the MimeType of the data resource.

    • OptionalinitialProperties: InitialNodeProperties

      Specifies initialProperties of the added Node.

    • OptionalcacheStrategy: CacheStrategy

      Specifies the strategy which is used when a data cache is requested from the Hub.

    Returns number

    The ID of added node

    Deprecated

    This function will no longer be available in future webvis releases. Please use the add function with AddNodeOptions instead.

    Adds a new Node to the InstanceGraph.

    Triggers a NodeAddedEvent. In case of an error, a NodeErrorEvent is triggered.

addCustomNode

  • addCustomNode(
        customNodeType: string,
        data: any,
        dataType?: AttachmentType,
    ): number

  • Creates a custom node along with custom data which is stored in an attachment.

    The attached data can be accessed via the Property.ATTACHMENT property of the node.

    Triggers a NodeAddedEvent. In case of an error, a NodeErrorEvent is triggered.

    Parameters

    • customNodeType: string

      Specifies the custom node type.

    • data: any

      Specifies the data of the custom node.

    • OptionaldataType: AttachmentType

      Specifies the type of the data. Default: "json".

    Returns number

    The ID of the newly created custom node.

    See

    AttachmentAPI

collectRuntimeNodesOfType

  • collectRuntimeNodesOfType(nodeType: NodeType, subType?: string): number[]

  • Returns a list of all existing runtime node IDs of a specified type.

    Parameters

    • nodeType: NodeType

      The node type to collect.

    • OptionalsubType: string

      The sub type to collect. Only used for custom nodes. See Property.SUBTYPE.

    Returns number[]

    A list of runtime node IDs of the specified type.

getEnabledAuxNodes

  • getEnabledAuxNodes(nodeID: number): Promise<number[]>

  • Parameters

    • nodeID: number

      Specifies the entry point of the subtree traversal. Default: 0

    Returns Promise<number[]>

    An Array of all enabled aux node IDs

    Deprecated

    This function will no longer be available in future webvis releases. Use the QueryAPI instead.

    Traverses the subtree of a given node ID and collects all enabled aux nodes.

getMetadata

  • getMetadata(nodeID: number): Promise<{ [key: string]: string }>

  • Returns a JSON object containing the metadata for the given node ID.

    Parameters

    • nodeID: number

      The ID of a node.

    Returns Promise<{ [key: string]: string }>

    A JSON object containing the requested metadata.

getProperties

  • getProperties<T extends string>(
        nodeID: number,
        properties: T[],
    ): Promise<PropertyType<T>[]>

  • Returns the values of the specified properties of the given node.

    Type Parameters

    • T extends string

    Parameters

    • nodeID: number

      The ID of the node whose properties should be read.

    • properties: T[]

      The names of the Properties whose values should be read.

    Returns Promise<PropertyType<T>[]>

    The retrieved values of the node's properties.

getProperty

  • getProperty<T extends string>(
        nodeID: number,
        property: T,
    ): Promise<PropertyType<T>>

  • Returns the value of the specified property of the given node.

    Type Parameters

    • T extends string

    Parameters

    • nodeID: number

      The ID(s) of the node(s) whose property should be read.

    • property: T

      The name of the Property whose value should be read.

    Returns Promise<PropertyType<T>>

    The retrieved value of the node property.

getRootNodeId

  • getRootNodeId(target: number | TopologyHandle, includeTarget?: boolean): number

  • Returns the root node ID of the given node or topology element.

    Parameters

    • target: number | TopologyHandle

      Specifies the target node or topology element.

    • OptionalincludeTarget: boolean

      Controls if the target node itself can be returned as root node. If set to false and a root node ID is passed in, it returns the next higher root node ID. Default: true

    Returns number

    The root node ID of the given node ID or topology handle.

getStatistics

  • getStatistics(
        nodeType?: NodeType,
        nodeID?: number,
        recursive?: boolean,
    ): Promise<any>

  • Traverses the subtree of a given node ID and collects all statistics (currently only available for AUX nodes).

    Parameters

    • OptionalnodeType: NodeType

      Specifies the target node type. Default: NodeType.ALL

    • OptionalnodeID: number

      Specifies the node ID as the entry point of the subtree traversal. Default: 0

    • Optionalrecursive: boolean

    Returns Promise<any>

    An object of type/count pairs.

invertEnabledStates

  • invertEnabledStates(): void

  • Inverts all enabled states.

    Triggers a NodeChangedEvent.

    Returns void

isNodeDeletable

  • isNodeDeletable(nodeID: number): boolean

  • Checks if a node is deletable.

    Parameters

    • nodeID: number

    Returns boolean

    true if the node is deletable.

isNodeType

  • isNodeType(nodeID: number, nodeType: NodeType): boolean

  • Checks if a node is a specific type.

    Parameters

    Returns boolean

    true if the node is of the specified type, otherwise false.

registerCustomProperty

  • registerCustomProperty(
        name: string,
        defaultValue: any,
        recursive?: boolean,
    ): void

  • Registers a new custom node property.

    Custom properties allow developers to hook into the node hierarchy with custom data. This enables the creation of custom behaviors and interactions that can benefit from the NODE_* events, like the NodeChangedEvent, emitted by the InstanceGraphAPI.

    Triggers a CustomPropertyRegisteredEvent

    Parameters

    • name: string

      The name of the new property.

    • defaultValue: any

      Specifies the default value.

    • Optionalrecursive: boolean

      Defines whether the property is recursive. Default: false

    Returns void

remove

  • remove(nodeID?: number | number[], safe?: boolean): Promise<RemoveState>

  • Removes the node for the given node ID from the scene and all related snapshots. If no node ID is supplied, all nodes are deleted.

    Triggers a NodeRemovedEvent.

    Parameters

    • OptionalnodeID: number | number[]

      The ID of the node that should be removed or undefined to remove all nodes.

    • Optionalsafe: boolean

      Performs a safe remove which interrupt the removal process if the node is part of one or more snapshots. Default: false.

    Returns Promise<RemoveState>

    A promise that resolves with the RemoveState once the operation is complete.

    See

    SessionStorageAPI

requestActiveSceneVolume

  • requestActiveSceneVolume(): Promise<BoxVolume>

  • Returns the active volume of the current scene. It is the smallest volume that contains all nodes of the scene that are enabled.

    Returns Promise<BoxVolume>

    See

    Property.ENABLED

requestAuxRootNodeIds

  • requestAuxRootNodeIds(scopeNodeId?: number): Promise<number[]>

  • Returns a list of all existing AUX root node IDs below the specified subtree.

    Parameters

    • OptionalscopeNodeId: number

      Specifies the top one node ID of the subtree to be searched. Default: 0

    Returns Promise<number[]>

    A list of AUX root node IDs.

requestFullSceneVolume

  • requestFullSceneVolume(): Promise<BoxVolume>

  • Returns the full volume of the current scene. It is the smallest volume that contains all nodes of the scene, regardless of their Property.ENABLED state.

    Returns Promise<BoxVolume>

requestL3DInformation

  • requestL3DInformation(targetNodeId: number): Promise<any>

  • Returns the L3D information of the specified node.

    Parameters

    • targetNodeId: number

      Specifies the target node ID.

    Returns Promise<any>

    The L3D information of the specified node

requestNodeIdsByBoxVolume

  • requestNodeIdsByBoxVolume(
        boxVolume: BoxVolume,
        includeOverlappingNodes?: boolean,
        includeDisabledNodes?: boolean,
        forceExpand?: boolean,
        scopeNodeId?: number,
    ): Promise<number[]>

  • Returns a list of all node IDs that are included in or overlapped by the specified bounding volume.

    Parameters

    • boxVolume: BoxVolume

      Specifies the bounding volume.

    • OptionalincludeOverlappingNodes: boolean

      Specifies whether the result should include nodes which overlap the specified bounding volume as well. Default: false

    • OptionalincludeDisabledNodes: boolean

      Specifies whether the result should include nodes which are disabled as well. Default: false

    • OptionalforceExpand: boolean

      If set to true, L3D instances may be expanded to find their leaf nodes. Default: false

    • OptionalscopeNodeId: number

      Specifies the top one node ID of the subtree to be searched. Default: 0

    Returns Promise<number[]>

    List of all node IDs which are included or overlapped by the specified bounding volume.

requestRootNodeIds

  • requestRootNodeIds(scopeNodeId?: number, recursive?: boolean): Promise<number[]>

  • Returns a list of all existing root node IDs below the specified subtree.

    Parameters

    • OptionalscopeNodeId: number

      Specifies the top one node ID of the subtree to be searched. Default: 0

    • Optionalrecursive: boolean

      Specifies if the subtree is traversed recursively. Default: false

    Returns Promise<number[]>

    A list of root node IDs.

resetProperties

  • resetProperties<T extends string>(
        nodeID: number,
        properties: T[],
        recursive?: boolean,
    ): Promise<void>

  • Resets the value of the specified properties of the given node.

    Triggers a NodePropertiesResetEvent. If the property has changed, this will additionally trigger a NodeChangedEvent.

    Type Parameters

    • T extends string

    Parameters

    • nodeID: number

      The ID of the node whose Property should be reset.

    • properties: T[]

      List of properties which should be reset.

    • Optionalrecursive: boolean

      If set to true, the properties are reset recursively. Default: false

    Returns Promise<void>

resetProperty

  • resetProperty<T extends string>(
        nodeID: number,
        property: T,
        recursive?: boolean,
    ): Promise<void>

  • Resets the value of the specified property of the given node.

    Triggers a NodePropertiesResetEvent. If the property has changed, this will additionally trigger a NodeChangedEvent.

    Type Parameters

    • T extends string

    Parameters

    • nodeID: number

      The ID of the node whose Property should be reset.

    • property: T

      The Property that should be reset.

    • Optionalrecursive: boolean

      If set to true, the properties are reset recursively. Default: false

    Returns Promise<void>

setParent

  • setParent(nodeID: number, newParentID: number): void

  • Sets a new parent for a given node ID.

    Triggers a NodeChangedEvent.

    Parameters

    • nodeID: number

      The ID of the node whose parent should be set.

    • newParentID: number

      The ID of the new parent node.

    Returns void

setProperty

  • setProperty<T extends string>(
        nodeID: number | number[],
        property: T,
        value: PropertyType<T>,
        silent?: boolean,
    ): Promise<void>

  • Sets the specified property to the given value on the node(s) with the specified ID(s).

    Triggers a NodeChangedEvent. Depending on the property it can trigger additional events, e.g. ActiveSceneVolumeChangedEvent.

    Type Parameters

    • T extends string

    Parameters

    • nodeID: number | number[]

      The ID(s) of the node(s) whose property has to be set.

    • property: T

      The name of the Property that has to be set.

    • value: PropertyType<T>

      The new value of the specified property.

    • Optionalsilent: boolean

      The silent flag indicates that no NODE_CHANGED event is fired. Default: false

    Returns Promise<void>