DistanceMeasurementsPlugin

Viewer plugin for measuring point-to-point distances.

• [Example 1: Model with distance measurements]
• [Example 2: Create distance measurements with mouse]
• [Example 3: Configuring units and scale

Overview

• A DistanceMeasurement represents a point-to-point measurement between two 3D points on one or two Entitys.
• As shown on the screen capture above, a DistanceMeasurement has one wire (light blue) that shows the direct point-to-point measurement, and three more wires (red, green and blue) that show the distance on each of the World-space X, Y and Z axis.
• Create DistanceMeasurements programmatically with DistanceMeasurementsPlugin#createMeasurement.
• Create DistanceMeasurements interactively using a DistanceMeasurementsControl.
• Existing DistanceMeasurements are registered by ID in DistanceMeasurementsPlugin#measurements.
• Destroy DistanceMeasurements using DistanceMeasurementsPlugin#destroyMeasurement.
• Configure global measurement units and scale via Metrics, located at Scene#metrics.

Example 1: Creating DistanceMeasurements Programmatically

In our first example, we'll use an XKTLoaderPlugin to load a model, and then use a DistanceMeasurementsPlugin to programmatically create two DistanceMeasurements.

Note how each DistanceMeasurement has origin and target endpoints, which each indicate a 3D World-space position on the surface of an Entity. The endpoints can be attached to the same Entity, or to different Entitys.

[Run example]

import {Viewer, XKTLoaderPlugin, DistanceMeasurementsPlugin} from "xeokit-sdk.es.js";

const viewer = new Viewer({
    canvasId: "myCanvas",
    transparent: true
});

viewer.scene.camera.eye = [-2.37, 18.97, -26.12];
viewer.scene.camera.look = [10.97, 5.82, -11.22];
viewer.scene.camera.up = [0.36, 0.83, 0.40];

const xktLoader = new XKTLoaderPlugin(viewer);

const distanceMeasurements = new DistanceMeasurementsPlugin(viewer);

const model = xktLoader.load({
     src: "./models/xkt/duplex/duplex.xkt"
});

model.on("loaded", () => {

     const myMeasurement1 = distanceMeasurements.createMeasurement({
         id: "distanceMeasurement1",
         origin: {
             entity: viewer.scene.objects["2O2Fr$t4X7Zf8NOew3FLOH"],
             worldPos: [0.044, 5.998, 17.767]
         },
         target: {
             entity: viewer.scene.objects["2O2Fr$t4X7Zf8NOew3FLOH"],
             worldPos: [4.738, 3.172, 17.768]
         },
         visible: true,
         wireVisible: true
     });

     const myMeasurement2 = distanceMeasurements.createMeasurement({
         id: "distanceMeasurement2",
         origin: {
             entity: viewer.scene.objects["2O2Fr$t4X7Zf8NOew3FNr2"],
             worldPos: [0.457, 2.532, 17.766]
         },
         target: {
             entity: viewer.scene.objects["1CZILmCaHETO8tf3SgGEXu"],
             worldPos: [0.436, 0.001, 22.135]
         },
         visible: true,
         wireVisible: true
     });
});

Example 2: Creating DistanceMeasurements with Mouse Input

In our second example, we'll use an XKTLoaderPlugin to load a model, then we'll use a DistanceMeasurementsMouseControl to interactively create DistanceMeasurements with mouse input.

After we've activated the DistanceMeasurementsMouseControl, the first click on any Entity begins constructing a DistanceMeasurement, fixing its origin to that Entity. The next click on any Entity will complete the DistanceMeasurement, fixing its target to that second Entity.

The DistanceMeasurementsMouseControl will then wait for the next click on any Entity, to begin constructing another DistanceMeasurement, and so on, until deactivated again.

[Run example]

import {Viewer, XKTLoaderPlugin, DistanceMeasurementsPlugin, DistanceMeasurementsMouseControl, PointerLens} from "xeokit-sdk.es.js";

const viewer = new Viewer({
    canvasId: "myCanvas",
    transparent: true
});

viewer.scene.camera.eye = [-2.37, 18.97, -26.12];
viewer.scene.camera.look = [10.97, 5.82, -11.22];
viewer.scene.camera.up = [0.36, 0.83, 0.40];

const xktLoader = new XKTLoaderPlugin(viewer);

const distanceMeasurements = new DistanceMeasurementsPlugin(viewer);

const distanceMeasurementsControl  = new DistanceMeasurementsMouseControl(distanceMeasurements, {
    pointerLens : new PointerLens(viewer)
})

distanceMeasurementsControl.snapToVertex = true;
distanceMeasurementsControl.snapToEdge = true;

distanceMeasurementsControl.activate();

const model = xktLoader.load({
    src: "./models/xkt/duplex/duplex.xkt"
});

Example 3: Configuring Measurement Units and Scale

In our third example, we'll use the Scene's Metrics to set the global unit of measurement to "meters". We'll also specify that a unit within the World-space coordinate system represents ten meters.

The wires belonging to our DistanceMeasurements show their lengths in Real-space coordinates, in the current unit of measurement. They will dynamically update as we set these configurations.

• [Run example]

const metrics = viewer.scene.metrics;

metrics.units = "meters";
metrics.scale = 10.0;

Example 4: Attaching Mouse Handlers

In our fourth example, we'll attach event handlers to our plugin, to catch when the user hovers or right-clicks over our measurements.

[Run example]

import {Viewer, XKTLoaderPlugin, DistanceMeasurementsPlugin, DistanceMeasurementsMouseControl, PointerLens} from "xeokit-sdk.es.js";

const viewer = new Viewer({
    canvasId: "myCanvas",
    transparent: true
});

viewer.scene.camera.eye = [-2.37, 18.97, -26.12];
viewer.scene.camera.look = [10.97, 5.82, -11.22];
viewer.scene.camera.up = [0.36, 0.83, 0.40];

const xktLoader = new XKTLoaderPlugin(viewer);

const distanceMeasurements = new DistanceMeasurementsPlugin(viewer);

const distanceMeasurementsControl  = new DistanceMeasurementsMouseControl(distanceMeasurements, {
    pointerLens : new PointerLens(viewer)
})

distanceMeasurementsControl.snapToVertex = true;
distanceMeasurementsControl.snapToEdge = true;

distanceMeasurementsControl.activate();

distanceMeasurements.on("mouseOver", (e) => {
    e.measurement.setHighlighted(true);
});

distanceMeasurements.on("mouseLeave", (e) => {
    e.measurement.setHighlighted(false);
});

distanceMeasurements.on("contextMenu", (e) => {
    // Show context menu
    e.event.preventDefault();
});

const model = xktLoader.load({
     src: "Duplex.xkt"
});

model.on("loaded", () => {

     const myMeasurement1 = distanceMeasurements.createMeasurement({
         id: "distanceMeasurement1",
         origin: {
             entity: viewer.scene.objects["2O2Fr$t4X7Zf8NOew3FLOH"],
             worldPos: [0.044, 5.998, 17.767]
         },
         target: {
             entity: viewer.scene.objects["2O2Fr$t4X7Zf8NOew3FLOH"],
             worldPos: [4.738, 3.172, 17.768]
         },
         visible: true,
         wireVisible: true
     });

     const myMeasurement2 = distanceMeasurements.createMeasurement({
         id: "distanceMeasurement2",
         origin: {
             entity: viewer.scene.objects["2O2Fr$t4X7Zf8NOew3FNr2"],
             worldPos: [0.457, 2.532, 17.766]
         },
         target: {
             entity: viewer.scene.objects["1CZILmCaHETO8tf3SgGEXu"],
             worldPos: [0.436, 0.001, 22.135]
         },
         visible: true,
         wireVisible: true
     });
});

Example 5: Creating DistanceMeasurements with Touch Input

In our fifth example, we'll show how to create distance measurements with touch input, with snapping to the nearest vertex or edge. While creating the measurements, a long-touch when setting the start or end point will cause the point to snap to the nearest vertex or edge. A quick touch-release will immediately set the point at the tapped position on the object surface.

[Run example]

import {Viewer, XKTLoaderPlugin, DistanceMeasurementsPlugin, DistanceMeasurementsTouchControl} from "xeokit-sdk.es.js";

const viewer = new Viewer({
    canvasId: "myCanvas",
    transparent: true
});

viewer.scene.camera.eye = [-2.37, 18.97, -26.12];
viewer.scene.camera.look = [10.97, 5.82, -11.22];
viewer.scene.camera.up = [0.36, 0.83, 0.40];

const xktLoader = new XKTLoaderPlugin(viewer);

const distanceMeasurements = new DistanceMeasurementsPlugin(viewer);

const model = xktLoader.load({
     src: "./models/xkt/duplex/duplex.xkt"
});

const distanceMeasurements = new DistanceMeasurementsPlugin(viewer);

const distanceMeasurementsTouchControl  = new DistanceMeasurementsTouchControl(distanceMeasurements, {
    pointerLens : new PointerLens(viewer),
    snapToVertex: true,
    snapToEdge: true
})

distanceMeasurementsTouchControl.activate();