Reference Source
public class | source

DistanceMeasurementsPlugin

Extends:

Plugin → DistanceMeasurementsPlugin

Viewer plugin for measuring point-to-point distances.

Overview

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.

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();

Constructor Summary

Public Constructor
public

constructor(viewer: Viewer, cfg: Object)

Member Summary

Public Members
public get
this get was deprecated.

Gets the default DistanceMeasurementsControl.

public
public
public
public
public
public
public
public
public
public
public
public
public
public
public
public set

Sets the minimum length, in pixels, of an axis wire beyond which its label is shown.

public get

Gets the minimum length, in pixels, of an axis wire beyond which its label is shown.

public get

Gets the existing DistanceMeasurements, each mapped to its DistanceMeasurement#id.

public get

Gets the PointerLens attached to this DistanceMeasurementsPlugin.

public set

Sets whether the measurement added is rotation adjusted or not.

public get

Gets whether the measurement added is rotation adjusted or not.

public

zIndex: *

Method Summary

Public Methods
public

clear()

Destroys all DistanceMeasurements.

public
public

Destroys this DistanceMeasurementsPlugin.

public

Destroys a DistanceMeasurement.

public

Gets if the axis wires of each DistanceMeasurement are visible.

public

getContainerElement(): * | HTMLElement | HTMLElement

Gets the plugin's HTML container element, if any.

public

setAxisVisible(labelsShown: Boolean)

Shows all or hides the axis wires of each DistanceMeasurement.

public

setLabelsShown(labelsShown: Boolean)

Shows all or hides the distance label of each DistanceMeasurement.

Inherited Summary

From class Plugin
public

ID for this Plugin, unique within its Viewer.

public

The Viewer that contains this Plugin.

public

Destroys this Plugin and removes it from its Viewer.

public

error(msg: String)

Logs an error message to the JavaScript developer console, prefixed with the ID of this Plugin.

public

fire(event: String, value: Object, forget: Boolean)

Fires an event on this Plugin.

public

Returns true if there are any subscribers to the given event on this Plugin.

public

log(msg: String)

Logs a message to the JavaScript developer console, prefixed with the ID of this Plugin.

public

off(subId: String)

Cancels an event subscription that was previously made with Plugin#on or Plugin#once.

public

on(event: String, callback: Function, scope: Object): String

Subscribes to an event on this Plugin.

public

once(event: String, callback: Function, scope: Object)

Subscribes to the next occurrence of the given event, then un-subscribes as soon as the event is subIdd.

public

scheduleTask(task: *)

Schedule a task to perform on the next browser interval

public

warn(msg: String)

Logs a warning message to the JavaScript developer console, prefixed with the ID of this Plugin.

Public Constructors

public constructor(viewer: Viewer, cfg: Object) source

Creates this Plugin and installs it into the given Viewer.

Override:

Plugin#constructor

Params:

NameTypeAttributeDescription
viewer Viewer

The Viewer.

cfg Object
  • optional

Plugin configuration.

cfg.id String
  • optional
  • default: "DistanceMeasurements"

Optional ID for this plugin, so that we can find it within Viewer#plugins.

cfg.labelMinAxisLength Number
  • optional
  • default: 25

The minimum length, in pixels, of an axis wire beyond which its label is shown.

cfg.container HTMLElement
  • optional

Container DOM element for markers and labels. Defaults to document.body.

cfg.defaultVisible boolean
  • optional
  • default: true

The default value of the DistanceMeasurements visible property.

cfg.defaultOriginVisible boolean
  • optional
  • default: true

The default value of the DistanceMeasurements originVisible property.

cfg.defaultTargetVisible boolean
  • optional
  • default: true

The default value of the DistanceMeasurements targetVisible property.

cfg.defaultWireVisible boolean
  • optional
  • default: true

The default value of the DistanceMeasurements wireVisible property.

cfg.defaultLabelsVisible boolean
  • optional
  • default: true

The default value of the DistanceMeasurements labelsVisible property.

cfg.defaultXLabelEnabled boolean
  • optional
  • default: true

The default value of the DistanceMeasurements xLabelEnabled property.

cfg.defaultYLabelEnabled boolean
  • optional
  • default: true

The default value of the DistanceMeasurements yLabelEnabled property.

cfg.defaultZLabelEnabled boolean
  • optional
  • default: true

The default value of the DistanceMeasurements zLabelEnabled property.

cfg.defaultLengthLabelEnabled boolean
  • optional
  • default: true

The default value of the DistanceMeasurements lengthLabelEnabled property.

cfg.defaultAxisVisible boolean
  • optional
  • default: true

The default value of the DistanceMeasurements axisVisible property.

cfg.defaultXAxisVisible boolean
  • optional
  • default: true

The default value of the DistanceMeasurements xAxisVisible property.

cfg.defaultYAxisVisible boolean
  • optional
  • default: true

The default value of the DistanceMeasurements yAxisVisible property.

cfg.defaultZAxisVisible boolean
  • optional
  • default: true

The default value of the DistanceMeasurements zAxisVisible property.

cfg.useRotationAdjustment boolean
  • optional
  • default: false

The default value of DistanceMeasurements useRotationAdjustment property.

cfg.defaultColor string
  • optional
  • default: #00BBFF

The default color of the length dots, wire and label.

cfg.zIndex number
  • optional

If set, the wires, dots and labels will have this zIndex (+1 for dots and +2 for labels).

cfg.defaultLabelsOnWires boolean
  • optional
  • default: true

The default value of the DistanceMeasurements labelsOnWires property.

cfg.pointerLens PointerCircle
  • optional

A PointerLens to help the user position the pointer. This can be shared with other plugins.

Public Members

public get control: DistanceMeasurementsControl source

this get was deprecated.

Gets the default DistanceMeasurementsControl.

public defaultAxisVisible: * source

public defaultColor: * source

public defaultLabelsOnWires: * source

public defaultLabelsVisible: * source

public defaultLengthLabelEnabled: * source

public defaultOriginVisible: * source

public defaultTargetVisible: * source

public defaultVisible: * source

public defaultWireVisible: * source

public defaultXAxisVisible: * source

public defaultXLabelEnabled: * source

public defaultYAxisVisible: * source

public defaultYLabelEnabled: * source

public defaultZAxisVisible: * source

public defaultZLabelEnabled: * source

public set labelMinAxisLength: number source

Sets the minimum length, in pixels, of an axis wire beyond which its label is shown.

The axis wire's label is not shown when its length is less than this value.

This is 25 pixels by default.

Must not be less than 1.

public get labelMinAxisLength: number: * source

Gets the minimum length, in pixels, of an axis wire beyond which its label is shown.

Return:

number

public get measurements: {String: DistanceMeasurement} source

Gets the existing DistanceMeasurements, each mapped to its DistanceMeasurement#id.

public get pointerLens: PointerCircle: * source

Gets the PointerLens attached to this DistanceMeasurementsPlugin.

Return:

PointerCircle

public set useRotationAdjustment: boolean source

Sets whether the measurement added is rotation adjusted or not.

public get useRotationAdjustment: number: * source

Gets whether the measurement added is rotation adjusted or not.

Return:

number

public zIndex: * source

Public Methods

public clear() source

Destroys all DistanceMeasurements.

public createMeasurement(params: Object): DistanceMeasurement source

Creates a DistanceMeasurement.

The DistanceMeasurement is then registered by DistanceMeasurement#id in DistanceMeasurementsPlugin#measurements.

Params:

NameTypeAttributeDescription
params Object

DistanceMeasurement configuration.

params.id String

Unique ID to assign to DistanceMeasurement#id. The DistanceMeasurement will be registered by this in DistanceMeasurementsPlugin#measurements and Scene.components. Must be unique among all components in the Viewer.

params.origin.worldPos Number[]

Origin World-space 3D position.

params.origin.entity Entity

Origin Entity.

params.target.worldPos Number[]

Target World-space 3D position.

params.target.entity Entity

Target Entity.

params.visible Boolean
  • optional
  • default: true

Whether to initially show the DistanceMeasurement.

params.originVisible Boolean
  • optional
  • default: true

Whether to initially show the DistanceMeasurement origin.

params.targetVisible Boolean
  • optional
  • default: true

Whether to initially show the DistanceMeasurement target.

params.wireVisible Boolean
  • optional
  • default: true

Whether to initially show the direct point-to-point wire between DistanceMeasurement#origin and DistanceMeasurement#target.

params.axisVisible Boolean
  • optional
  • default: true

Whether to initially show the axis-aligned wires between DistanceMeasurement#origin and DistanceMeasurement#target.

params.xAxisVisible Boolean
  • optional
  • default: true

Whether to initially show the X-axis-aligned wires between DistanceMeasurement#origin and DistanceMeasurement#target.

params.yAxisVisible Boolean
  • optional
  • default: true

Whether to initially show the Y-axis-aligned wires between DistanceMeasurement#origin and DistanceMeasurement#target.

params.zAxisVisible Boolean
  • optional
  • default: true

Whether to initially show the Z-axis-aligned wires between DistanceMeasurement#origin and DistanceMeasurement#target.

params.xLabelEnabled Boolean
  • optional
  • default: true

Whether to initially show the x label.

params.yLabelEnabled Boolean
  • optional
  • default: true

Whether to initially show the y label.

params.zLabelEnabled Boolean
  • optional
  • default: true

Whether to initially show the z label.

params.lengthLabelEnabled Boolean
  • optional
  • default: true

Whether to initially show the length label.

params.labelsVisible Boolean
  • optional
  • default: true

Whether to initially show the labels.

params.lengthLabelVisible Boolean
  • optional
  • default: true

Whether to initially show the labels.

params.color string
  • optional

The color of the length dot, wire and label.

params.labelsOnWires Boolean
  • optional
  • default: true

Determines if labels will be set on wires or one below the other.

public destroy() source

Destroys this DistanceMeasurementsPlugin.

Destroys all DistanceMeasurements first.

Override:

Plugin#destroy

public destroyMeasurement(id: String) source

Destroys a DistanceMeasurement.

Params:

NameTypeAttributeDescription
id String

ID of DistanceMeasurement to destroy.

public getAxisVisible(): Boolean source

Gets if the axis wires of each DistanceMeasurement are visible.

Return:

Boolean

Whether or not the axis wires are visible.

public getContainerElement(): * | HTMLElement | HTMLElement source

Gets the plugin's HTML container element, if any.

Return:

* | HTMLElement | HTMLElement

public setAxisVisible(labelsShown: Boolean) source

Shows all or hides the axis wires of each DistanceMeasurement.

Params:

NameTypeAttributeDescription
labelsShown Boolean

Whether or not to show the axis wires.

public setLabelsShown(labelsShown: Boolean) source

Shows all or hides the distance label of each DistanceMeasurement.

Params:

NameTypeAttributeDescription
labelsShown Boolean

Whether or not to show the labels.