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} from "../src/viewer/Viewer.js";
import {XKTLoaderPlugin} from "../src/plugins/XKTLoaderPlugin/XKTLoaderPlugin.js";
import {DistanceMeasurementsPlugin} from "../src/plugins/DistanceMeasurementsPlugin/DistanceMeasurementsPlugin.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} from "../src/viewer/Viewer.js";
import {XKTLoaderPlugin} from "../src/plugins/XKTLoaderPlugin/XKTLoaderPlugin.js";
import {DistanceMeasurementsPlugin} from "../src/plugins/DistanceMeasurementsPlugin/DistanceMeasurementsPlugin.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.

const metrics = viewer.scene.metrics;

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

Constructor Summary

Public Constructor
public

constructor(viewer: Viewer, cfg: Object)

Member Summary

Public Members
public get

Gets the DistanceMeasurementsControl, which creates DistanceMeasurements from user input.

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.

Method Summary

Public Methods
public

clear()

Destroys all DistanceMeasurements.

public
public

Destroys this DistanceMeasurementsPlugin.

public

Destroys a 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)

Fires an event at this Plugin.

public

log(msg: String)

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

public

on(event: String, callback: Function)

Subscribes to an event fired at this Plugin.

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.

Public Members

public get control: DistanceMeasurementsControl source

Gets the DistanceMeasurementsControl, which creates DistanceMeasurements from user input.

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

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.