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 the DistanceMeasurementsControl, located at DistanceMeasurementsPlugin#control.
• 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 Interactively

In our second example, we'll use an XKTLoaderPlugin to load a model, then we'll use the DistanceMeasurementPlugin's DistanceMeasurementsControl to interactively create DistanceMeasurements with mouse or touch input.

After we've activated the DistanceMeasurementsControl, 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 DistanceMeasurementControl 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} 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"
});

distanceMeasurements.control.activate();  // <------------ Activate the DistanceMeasurementsControl

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;