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(
        nodeID: number,
        properties: string[],
        recursive?: boolean,
    ): Promise<void>;
    resetProperty(
        nodeID: number,
        property: string,
        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)

InstanceGraphAPI
- ContextAPI

Methods

add

add(options: AddNodeOptions): number
Adds a new node to the instance graph.
Parameters
- options: AddNodeOptions
  Specifies the options for the new Node.
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
- nodeID: number
- nodeType: NodeType
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(
    nodeID: number,
    properties: string[],
    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.
Parameters
- nodeID: number
  The ID of the node whose Property should be reset.
- properties: string[]
  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(
    nodeID: number,
    property: string,
    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.
Parameters
- nodeID: number
  The ID of the node whose Property should be reset.
- property: string
  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>

Did you find this page useful? Please give it a rating:

★ ★ ★ ★ ★

Thank you for rating this page!

Any issues or feedback?

What kind of problem would you like to report?

This page needs code samples
Code samples do not work
Information is missing
Please tell us more about what's wrong:
Information is incorrect
Please tell us more about what's wrong:
Information is unclear or confusing
Please tell us more about what's wrong:
The page is rendered incorrectly (styling/CSS)
Give Feedback

InstanceGraphAPI¶

Interface InstanceGraphAPI