TopologyAPI

Interface TopologyAPI

TopologyAPI

Overview

The TopologyAPI provides access to low-level topological entities within a 3D model. A topological entity can be a point, some kind of edge or face, or a shape that groups several of these entities together.

A topological entity is usually represented by a TopologyHandle. Each topological entity has a general type and a more specific subtype.

Given a TopologyHandle, a more detailed descriptor can be requested via the requestTopologyDescriptor function. This descriptor contains the subtype and an object with a series of known attributes of the topological entity. For example, a descriptor for a circle includes the center and radius of the circle.

Quick Start

A topology handle can be obtained via mapOriginalToInternalTopologyHandles by providing the identifier of the entity in the original CAD file.

Alternatively, you can use a click event listener to obtain a handle for the topological entity under the mouse cursor:

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

// Disable node selection on click and enable interaction
// with topological entities
context.setInteractionMode(webvis.InteractionMode.NONE);
viewer.setInteractionLevel(webvis.ViewerInteractionLevel.TOPOLOGY);
viewer.forceRenderMode(webvis.RenderMode.FacesTopology);
viewer.enableSnapping(true);

const listenerId = context.registerListener([webvis.EventType.NODE_CLICKED], async (event) => {
    const pointerInfo = event.pointerInfo;
    const topologyHandle = await pointerInfo.requestTopologyHandle();

    await context.addTopologyToSelection(topologyHandle);

    const topologyDescriptor = await context.requestTopologyDescriptor(topologyHandle);
    console.log("Descriptor: ", topologyDescriptor);

    const [originalIdentifier] = await context.mapInternalToOriginalTopologyHandles([topologyHandle]);
    console.log("Identifier in original CAD file: ", originalIdentifier);
}, 0, true); // Set option 'observeSubTree' to true to observe all entities

Combination With Other APIs

When the viewer interaction level is set to TOPOLOGY via the function ViewerInteractionAPI.setInteractionLevel, webvis will emit TopologyPointerEnterEvents and TopologyPointerOutEvents when the mouse cursor enters or leaves a topological entity:

// Setup as shown in the previous example, including setting
// the viewer interaction level to TOPOLOGY

const listenerId = context.registerListener([webvis.EventType.TOPOLOGY_POINTER_ENTER], (event) => {
    const topologyHandle = event.topologyHandle;
    viewer.highlightEntity(topologyHandle, {color: [1, 0.8, 0, 0.5]});
}, 0, true); // Set option 'observeSubTree' to true to observe all entities

As demonstrated in the example above, you can use the function ViewerHighlightAPI.highlightEntity to highlight a topological entity.

In addition to that, the MeasurementAPI can be used to perform different kinds of measurements with topological entities. Examples include distance, angle, and thickness measurements, as well as tangent calculations.

interface TopologyAPI {
    addTopologyToSelection(
        handle: TopologyHandle | TopologyHandle[],
    ): Promise<void>;
    clearTopologySelection(): Promise<void>;
    createCircularArcDescriptor(
        point0: [number, number, number],
        point1: [number, number, number],
        point2: [number, number, number],
    ): { descriptor: TopologyCircularArcDescriptor; type: CIRCULAR_ARC };
    createPointDescriptor(
        point: [number, number, number],
    ): { descriptor: TopologyPointDescriptor; type: POINT };
    getSelectedTopologyHandles(): TopologyHandle[];
    getShapeHandle(handle: TopologyHandle): TopologyHandle;
    getTopologyType(handle: TopologyHandle): TopologyType;
    isTopologySelected(handle: TopologyHandle): boolean;
    mapInternalToOriginalTopologyHandles(
        handles: TopologyHandle[],
    ): Promise<OriginalTopologyHandle[]>;
    mapOriginalToInternalTopologyHandles(
        nodeID: number,
        handles: OriginalTopologyHandle[],
    ): Promise<TopologyHandle[]>;
    removeTopologyFromSelection(
        handle: TopologyHandle | TopologyHandle[],
    ): Promise<void>;
    requestBoxDescriptor(
        nodeIds: number[],
    ): Promise<{ descriptor: TopologyBoxDescriptor; type: BOX }>;
    requestNeighboringEdges(handle: TopologyHandle): Promise<TopologyHandle[]>;
    requestNeighboringFaces(handle: TopologyHandle): Promise<TopologyHandle[]>;
    requestTopologyDescriptor(
        handle: TopologyHandle,
    ): Promise<TopologyDescriptor>;
    setTopologyProperty<T extends keyof TopologyPropertyTypeMap>(
        handle: TopologyHandle | TopologyHandle[],
        property: T,
        value: TopologyPropertyTypeMap[T],
    ): Promise<PromiseSettledResult<void>[]>;
    setTopologySelection(
        handle: TopologyHandle | TopologyHandle[],
    ): Promise<void>;
}

Hierarchy (View Summary)

Methods

addTopologyToSelection clearTopologySelection createCircularArcDescriptor createPointDescriptor getSelectedTopologyHandles getShapeHandle getTopologyType isTopologySelected mapInternalToOriginalTopologyHandles mapOriginalToInternalTopologyHandles removeTopologyFromSelection requestBoxDescriptor requestNeighboringEdges requestNeighboringFaces requestTopologyDescriptor setTopologyProperty setTopologySelection

Methods

addTopologyToSelection

clearTopologySelection

createCircularArcDescriptor

  • createCircularArcDescriptor(
        point0: [number, number, number],
        point1: [number, number, number],
        point2: [number, number, number],
    ): { descriptor: TopologyCircularArcDescriptor; type: CIRCULAR_ARC }

  • Creates a circular arc descriptor based on three points.

    Parameters

    • point0: [number, number, number]

      The first point.

    • point1: [number, number, number]

      The second point.

    • point2: [number, number, number]

      The third point.

    Returns { descriptor: TopologyCircularArcDescriptor; type: CIRCULAR_ARC }

    A circular arc descriptor.

createPointDescriptor

  • createPointDescriptor(
        point: [number, number, number],
    ): { descriptor: TopologyPointDescriptor; type: POINT }

  • Creates a point descriptor for the specified point.

    Parameters

    • point: [number, number, number]

      The point.

    Returns { descriptor: TopologyPointDescriptor; type: POINT }

    A point descriptor.

getSelectedTopologyHandles

getShapeHandle

getTopologyType

isTopologySelected

mapInternalToOriginalTopologyHandles

mapOriginalToInternalTopologyHandles

removeTopologyFromSelection

requestBoxDescriptor

  • requestBoxDescriptor(
        nodeIds: number[],
    ): Promise<{ descriptor: TopologyBoxDescriptor; type: BOX }>

  • Returns a box descriptor for the combined bounding box of the specified nodes.

    Parameters

    • nodeIds: number[]

      The nodes for which the box descriptor should be created.

    Returns Promise<{ descriptor: TopologyBoxDescriptor; type: BOX }>

    The box descriptor for the combined bounding box of the specified nodes.

requestNeighboringEdges

  • requestNeighboringEdges(handle: TopologyHandle): Promise<TopologyHandle[]>

  • Returns the neighboring edges of the specified topological entity.

    Parameters

    • handle: TopologyHandle

      The topological entity for which the neighboring edges should be requested.

    Returns Promise<TopologyHandle[]>

    The neighboring edges of the specified topological entity.

requestNeighboringFaces

  • requestNeighboringFaces(handle: TopologyHandle): Promise<TopologyHandle[]>

  • Returns the neighboring faces of the specified topological entity.

    Parameters

    • handle: TopologyHandle

      The topological entity for which the neighboring faces should be requested.

    Returns Promise<TopologyHandle[]>

    The neighboring faces of the specified topological entity.

requestTopologyDescriptor

  • requestTopologyDescriptor(handle: TopologyHandle): Promise<TopologyDescriptor>

  • Returns a detailed descriptor for the specified topological entity. The descriptor contains the subtype and an object with a series of known attributes of the topological entity. For example, a descriptor for a circle includes the center and radius of the circle.

    Parameters

    Returns Promise<TopologyDescriptor>

    A detailed descriptor for the specified topological entity.

setTopologyProperty

setTopologySelection