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.

MeasurementAPI

Interface MeasurementAPI

MeasurementAPI

Overview

The MeasurementAPI provides functionality to:

  • Perform different kinds of measurements between 3D objects
  • Create and manage measurements as first-class entities in the webvis context

Possible measurement inputs include nodes, shapes, faces, edges, and points, as well as planes and lines. All available input types are defined in the MeasurementTargetClass enum.

Quick Start

To measure the distance between a point and a plane, we need to represent them as MeasurementTargets as follows:

const point = [0, 0, 0];
const plane = [1, 0, 0, 1]; // [normal_x, normal_y, normal_z, distance]

const pointTarget = {
    class: webvis.MeasurementTargetClass.POINT,
    value: point
};

const planeTarget = {
    class: webvis.MeasurementTargetClass.PLANE,
    value: plane
};

For other target types, see MeasurementTargetClass. With these targets, we can now measure the distance using the measureBetween function:

const context = webvis.getContext();

const result = await context.measureBetween(pointTarget, planeTarget);

const distance = result.distance;
const pointOnPlane = result.points[1];

Measurement Functions

The API contains two sets of functions. The first is used to perform a measurement and return the result without creating a new measurement entity in the webvis context. These include:

The second set of functions is used to create and manage measurements as first-class entities in the webvis context. Here, createMeasurement is used to perform different kinds of measurements and create a new measurement entity holding the result. The available measurement types for this scenario are defined in the MeasurementType enum. Besides this function, this set also includes:

Creating a Measurement Entity

If we want to perform the same measurement as in the quick start example, but also create a corresponding measurement entity in the webvis context, we can use the createMeasurement function:

// Define targets as in the quick start example...

const context = webvis.getContext();

const measurementId = context.createMeasurement(
    webvis.MeasurementType.MULTIPLE, // Analogous to measureBetween
    [pointTarget, planeTarget]
);

// We can access the result of the measurement by requesting
// its properties
const measurementProperties = await context.requestMeasurementData(measurementId);
const result = measurementProperties.result;

Working With Model Geometry

In webvis, a part of a model's geometry can be referenced via a TopologyHandle. Given such a handle, we can create a corresponding MeasurementTarget to use in measurements:

const topologyHandle = getTopologyHandle(); // Replace with your topology handle

const edgeMeasurementTarget = {
    class: webvis.MeasurementTargetClass.TOPOLOGY,
    value: topologyHandle
};
interface MeasurementAPI {
    changeMeasurement(
        measurementID: number,
        properties: MeasurementProperties,
    ): MeasurementProperties;
    createMeasurement<T extends keyof MeasurementTypeToTargetMap>(
        type: T,
        targets: MeasurementTypeToTargetMap[T],
        properties?: MeasurementProperties,
    ): number;
    getMeasurements(): number[];
    measureBetween(
        target0: MeasurementTarget,
        target1: MeasurementTarget,
    ): Promise<BetweenMeasurementResult>;
    measurePointsByDistance(
        searchCurve: {
            class: CURVE;
            value: [[number, number, number], [number, number, number]][];
        },
        distanceCurves: { class: TOPOLOGY; value: TopologyHandle }[],
        distance: number,
    ): Promise<DistanceConstraintMatch[]>;
    measureTangent(
        topology: { class: TOPOLOGY; value: TopologyHandle },
        point: { class: POINT; value: [number, number, number] },
    ): Promise<TangentMeasurementResult>;
    measureThickness(
        topology: { class: TOPOLOGY; value: TopologyHandle },
        point: { class: POINT; value: [number, number, number] },
    ): Promise<ThicknessMeasurementResult>;
    removeMeasurement(measurementID: number, safe?: boolean): RemoveState;
    requestMeasurementData(
        measurementID: number,
    ): Promise<MeasurementProperties>;
}

Hierarchy (View Summary)

Methods

changeMeasurement createMeasurement getMeasurements measureBetween measurePointsByDistance measureTangent measureThickness removeMeasurement requestMeasurementData

Methods

changeMeasurement

createMeasurement

getMeasurements

  • getMeasurements(): number[]

  • Returns the IDs of all measurement entities in the webvis context.

    Returns number[]

    The IDs of all measurement entities.

    See

    createMeasurement

measureBetween

  • measureBetween(
        target0: MeasurementTarget,
        target1: MeasurementTarget,
    ): Promise<BetweenMeasurementResult>

  • Measures the distance and, if applicable, the angle between two measurement targets. The result also includes the corresponding closest points on the targets.

    If the targets intersect, the result will contain a representation of the intersection. Note that the intersection is not available for measurements involving target classes TOPOLOGY or NODE, except for the cases plane-face and face-face.

    Parameters

    Returns Promise<BetweenMeasurementResult>

    The result of the measurement.

measurePointsByDistance

  • measurePointsByDistance(
        searchCurve: {
            class: CURVE;
            value: [[number, number, number], [number, number, number]][];
        },
        distanceCurves: { class: TOPOLOGY; value: TopologyHandle }[],
        distance: number,
    ): Promise<DistanceConstraintMatch[]>
  • Experimental

    Attention: This function is experimental and may be changed or removed in future versions.

    Returns points from a search space that have the specified distance to a set of measurement targets. The search space is defined by a measurement target. Currently only supports a search space that is defined by a curve and edges as distance targets.

    Parameters

    • searchCurve: { class: CURVE; value: [[number, number, number], [number, number, number]][] }

      The curve on which to search.

    • distanceCurves: { class: TOPOLOGY; value: TopologyHandle }[]

      The targets from which the distance is measured.

    • distance: number

      The distance.

    Returns Promise<DistanceConstraintMatch[]>

    An array of points that match the distance constraint.

measureTangent

  • measureTangent(
        topology: { class: TOPOLOGY; value: TopologyHandle },
        point: { class: POINT; value: [number, number, number] },
    ): Promise<TangentMeasurementResult>

  • Measures the tangent of an edge at a given point. The edge is specified by a measurement target that points to a corresponding TopologyHandle. If the point does not lie on the edge, the closest point on the edge is used.

    Parameters

    • topology: { class: TOPOLOGY; value: TopologyHandle }

      The measurement target representing the edge via a TopologyHandle.

    • point: { class: POINT; value: [number, number, number] }

      The point at which the tangent should be measured.

    Returns Promise<TangentMeasurementResult>

    The result of the tangent measurement.

measureThickness

  • measureThickness(
        topology: { class: TOPOLOGY; value: TopologyHandle },
        point: { class: POINT; value: [number, number, number] },
    ): Promise<ThicknessMeasurementResult>

  • Measures the thickness of a shape at a given point. The shape is specified by a measurement target that points to a corresponding TopologyHandle. If the point does not lie on the shape, the closest point on the shape is used. The thickness is measured along the line defined by the normal of the shape at the given point.

    Parameters

    • topology: { class: TOPOLOGY; value: TopologyHandle }

      The measurement target representing the shape via a TopologyHandle.

    • point: { class: POINT; value: [number, number, number] }

      The point at which the thickness should be measured.

    Returns Promise<ThicknessMeasurementResult>

    The result of the thickness measurement.

removeMeasurement

  • removeMeasurement(measurementID: number, safe?: boolean): RemoveState

  • Removes the measurement entity with the specified ID from the webvis context and all related snapshots.

    Triggers a MeasurementRemovedEvent when the measurement entity has been removed.

    Parameters

    • measurementID: number

      The ID of the measurement entity that should be removed.

    • Optionalsafe: boolean

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

    Returns RemoveState

    The resulting state of the removal process.

    See

    createMeasurement

requestMeasurementData

  • requestMeasurementData(measurementID: number): Promise<MeasurementProperties>

  • Returns the properties of the measurement entity with the specified ID. These include the result of the measurement, as well as its type and targets.

    Parameters

    • measurementID: number

      The ID of the measurement entity.

    Returns Promise<MeasurementProperties>

    The properties of the measurement entity.

    See

    createMeasurement