Skip to main content
Version: 4.x

Point to point measurement

The MeasurementTool is a measuring tool for point to point distance in 3D models, by clicking to- and from-points. The default measurement unit is meters, but the tool provides callbacks to allow configuring the unit. When exiting from the tool, all the measurement will be removed from the Cognite3DViewer. Note that the precision the tool can provide is limited, and the tool should only be used for approximate measurement - not high precision measurement for e.g. construction.

To effectively edit measuring line properties, tool is configurable with MeasurementOptions options to set

  • Custom label content for each measurement.
  • Size of line width in meters.
  • Color of line.
tip

CameraControlsOptions.changeCameraTargetOnClick should be set to false to avoid click event registering for camera when MeasurementTool is active. Also avoid any custom click-handler that might interfere with the measurement tool.

Point to point distance measurment​

To enter point-to-point measurement mode, use MeasurementTool.enterMeasurementMode(). This will register events for handling mouse clicks and touch events to allow placing the measurement end-points. Note that the tool is optimized for use with mouse.

To exit measurement mode, call exitMeasurementMode(). The tool will also exit measurement mode if user presses Escape key.

Live Editor

Another way to add measurements is to call the MeasurementTool.addMeasurement() method. It takes the two endpoints of the measurement line as arguments.

Events​

The tool exposes events for subscribing to measurement start, end & added. In the below example, the mouse cursor is changed to a cross-hair while measuring.

Live Editor

Mode of measurement​

To get the mode of measurement MeasurementTool.isInMeasurementMode. It returns true if the measurement is active else false.

Set width, color & label units of the measuring line​

To change width, color of the line and label units, use MeasurementTool.setLineOptions(options: MeasurementOptions). MeasurementOptions expects

  • distanceToLabelCallback : callback for custom operation on measurement labels
  • lineWidth : number - units in meters
  • color : THREE.color

The updated line width, color and label units will be applied for the next measuring distance.

Live Editor

Get all measurement​

To get all measurements added the tool provides MeasurementTool.getAllMeasurements() which will return an array of measurements of type Measurement, having below details

  • measurementId : unique id of measurement.
  • startPoint : start point of the measurement.
  • endPoint : end point of the measurement.
  • distanceInMeters : measured distance in meters.
Live Editor

Change appearance of existing measurement​

To change existing measurement line width or color, use MeasurementTool.updateLineWidth(lineWidth: number) or MeasurementTool.updateLineColor(color: THREE.Color)

Live Editor

Remove measurement​

To remove a measurement from the viewer, we have MeasurementTool.removeMeasurement(measurement: Measurement)

  • measurement : Measurement to be removed.
Live Editor

Hide and show measurements​

It may be useful to view the details of an object without measurements blocking the view. It's possible to toggle measurement visibility on and off in the viewer. To do this, use MeasurementTool.visible(enable: boolean).

//Hide all measurements in the viewer
measurementTool.visible(false);

To remove all measurement from the viewer, use MeasurementTool.removeAllMeasurement()

Label visibility​

It is also possible to hide/show only the labels of the measurement using MeasurementTool.showMeasurementLabels(enable: boolean).

// Hide all measurement lables
measurementTool.showMeasurementLabels(false);