ViewerInteractionAPI

Interface ViewerInteractionAPI

ViewerInteractionAPI

Overview

The ViewerInteractionAPI provides methods to control the user's interaction with a viewer.

Quick Start

The following example enables snapping to topological entities and then reacts to NodeClickedEvents:

const context = webvis.getContext();
const viewer = context.getViewer();

// Render topological entities
// This is required to enable interaction with and snapping
// to topological entities
viewer.forceRenderMode(webvis.RenderMode.FacesTopology);

viewer.setInteractionLevel(webvis.ViewerInteractionLevel.TOPOLOGY);
viewer.enableSnapping(true);

// Disable the default node selection on click.
// This is not required, but recommended to improve the user experience
context.setInteractionMode(webvis.InteractionMode.NONE);

const listenerId = context.registerListener([webvis.EventType.NODE_CLICKED], async (event) => {
    const pointerInfo = event.pointerInfo;
    console.log("Click position in 3D: ", pointerInfo.position);

    const topologyHandle = await pointerInfo.requestTopologyHandle();
    console.log("Topological entity: ", topologyHandle);
}, 0, true); // Set option 'observeSubTree' to true to observe all entities

//...

// Don't forget to unregister the listener when you are done
context.unregisterListener(listenerId);

Interaction Levels

Get the current interaction level of a viewer:

const viewer = webvis.getContext().getViewer("my-viewer");
const interactionLevel = viewer.getInteractionLevel();

By default, the interaction level is set to NODE, which means that the user will interact with viewer at the node level. In other words, on a desktop device using a mouse, the viewer will respond to clicks with the respective node under the mouse cursor.

Changing the interaction level to TOPOLOGY will make the viewer respond to clicks with the respective topology under the mouse cursor:

viewer.setInteractionLevel(webvis.ViewerInteractionLevel.TOPOLOGY);

Snapping

The ViewerInteractionAPI also provides the option to enable or disable snapping. Snapping is a feature that allows the user to snap to the nearest edge or point.

viewer.enableSnapping(true); // Enable snapping

Remarks

Interaction and snapping only work on entities that are being rendered in the viewer. For example, if the ViewerInteractionLevel is set to ViewerInteractionLevel.TOPOLOGY, but the viewer's ViewerSettingStrings.RENDER_MODE is set to RenderMode.Faces only, then snapping to edges will not work. To enable snapping to all topological entities, the render mode should be set to RenderMode.FacesTopology instead.

Events

The ViewerInteractionAPI emits the following events:

interface ViewerInteractionAPI {
    enableSnapping(useSnapping: boolean): void;
    getInteractionLevel(): ViewerInteractionLevel;
    isSnappingEnabled(): boolean;
    setInteractionLevel(level: ViewerInteractionLevel): void;
}

Hierarchy (View Summary)

Methods

enableSnapping getInteractionLevel isSnappingEnabled setInteractionLevel

Methods

enableSnapping

  • enableSnapping(useSnapping: boolean): void

  • Enables or disables snapping in the viewer.

    Parameters

    • useSnapping: boolean

      Whether to enable or disable snapping.

    Returns void

getInteractionLevel

isSnappingEnabled

  • isSnappingEnabled(): boolean

  • Returns whether snapping is enabled in the viewer.

    Returns boolean

    true if snapping is enabled, false otherwise.

setInteractionLevel