MeasurementAPI

Interface MeasurementAPI

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.

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];

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:

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;

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>;
    measureNormal(
        topology: { class: TOPOLOGY; value: TopologyHandle },
        point: { class: POINT; value: [number, number, number] },
    ): Promise<NormalMeasurementResult>;
    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)

Index

Methods

changeMeasurement createMeasurement getMeasurements measureBetween measureNormal measurePointsByDistance measureTangent measureThickness removeMeasurement requestMeasurementData

Methods

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

    Returns number[]

    The IDs of all measurement entities.

    createMeasurement

  • 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.

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

    Parameters

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

      The measurement target representing the face via a TopologyHandle.

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

      The point at which the normal should be measured.

    Returns Promise<NormalMeasurementResult>

    The result of the normal measurement.

  • 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.

  • 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.

  • 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.

  • 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.

    createMeasurement

  • 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.

    createMeasurement