MeasurementPlugin

Interactive 3D measurements. The plugin owns the visual layer (point sprites, lines, DOM labels with SVG leaders) while MeasurementService owns measurement state and types (distance, angle, area, multi-point, AABB, OBB, volume, circle, arc, plus user-registered descriptors).

Usage

const viewer = new ViewerCore(container, {
  plugins: [{ name: "measurement", enabled: true }],
});
await viewer.ready();

const measure = viewer.pluginManager.getPlugin("measurement") as MeasurementPlugin;
measure.enable();
measure.setMeasurementMode("distance");

Or:

await viewer.loadPlugin(new MeasurementPlugin());

Service dependencies: measurement, selection. Activating the plugin does not activate measurement input; call enable() to start capturing pointer input.

Since 4.0

• Spline measurement mode: setMeasurementMode("spline") places variable-count spline points and reports total arc length via SplineResult.
• STEP-edge measurement mode: setMeasurementMode("step-edge-length") and STEP sub-modes for coordinate / single-edge / multi-edge / linear point-to-point / linear point-to-edge / linear point-to-circle. Sub-mode is controlled from the service (setStepMeasurementMode(mode)).
• Async volume workflow: the plugin drives measureVolume / measureVolumeForObjects through computeVolumeMeasurementAsync, emitting progress hooks (VolumeMeasurementProgress) and supporting an AbortSignal. UI code can subscribe to service progress events to render a progress bar with an abort button.
• Edge snapping toggle: updateConfig({ edgeSnap: true, edgeSnapPixelThreshold: 12 }) snaps placement and drag points to loaded STEP edge overlays within a screen-pixel threshold. A parallel contourSnapPixelThreshold snaps to the active cross-section contour.
• Display-unit switcher: updateConfig({ displayUnit: { scale, lengthSuffix, areaSuffix?, volumeSuffix?, precision? } }) swaps label formatting between unit systems without changing stored measurement values.

Public API

Lifecycle and mode

Method	Description
enable()	Start capturing pointer input.
disable()	Stop capturing input.
setMeasurementMode(mode: string)	Switch to a measurement type by name (distance, angle, area, multi-point, aabb, obb, volume, circle, arc, or any registered descriptor).
getMeasurementMode()	Current mode name.
updateConfig(config: Partial<MeasurementConfig>)	Patch service config.
registerDescriptor(descriptor)	Add a custom measurement type. See MeasurementTypeDescriptor.
getDescriptor(name)	Look up a registered descriptor.
reset()	Clear in-progress points and pending state.
completeMeasurement()	Force-finalize the current measurement (for types that accumulate points).

Points

Method	Description
addPoint(point: THREE.Vector3)	Add a confirmed point.
setTemporaryPoint(point | null)	Hover-preview point.
getAllPoints()	All points across the active session.
getCurrentPoints()	Points belonging to the in-progress measurement.
getTemporaryPoint()	The current hover point or null.
updatePointer(x, y)	Forward a pointer position (NDC or screen, depending on service config).
raycast()	Run the service raycast against current scene.

Measurements

Method	Description
createMeasurement(points, type?)	Create a measurement directly from points. Default type "distance". Returns the new Measurement or null.
removeMeasurement(id)	Remove and dispose visuals.
showMeasurement(id) / hideMeasurement(id)	Toggle visibility.
getMeasurements()	All current measurements.
measureBoundingBox("aabb" | "obb")	Measure the AABB or OBB of the current selection. Returns null if no selection.
measureVolume(options?: VolumeMeasurementOptions)	Volume of the current selection (falls back to viewer.root).
measureVolumeForObjects(objects, options?)	Volume of a specific set of objects.

Label styling

Method	Description
setMeasurementLabelStyle(style: Partial<MeasurementLabelStyle>)	Global label style.
setMeasurementTypeLabelStyle(type, style | null)	Per-type override (e.g. distance vs. angle). Pass null to clear.

Types

type MeasurementLabelBackground =
  | string
  | { type: "solid"; color: string }
  | { type: "linear-gradient"; from: string; to: string; direction?: "vertical" | "horizontal" };

interface MeasurementLeaderLineStyle {
  color?: string;
  width?: number;
  opacity?: number;
  dashArray?: string;
}

interface MeasurementLabelStyle {
  background?: MeasurementLabelBackground;
  color?: string;
  accentColor?: string;
  sideColor?: string;
  typeColor?: string;
  borderColor?: string;
  borderWidth?: number;
  borderRadius?: number;
  fontFamily?: string;
  fontSize?: number;
  fontWeight?: string | number;
  sideFontSize?: number;
  typeFontSize?: number;
  paddingX?: number;
  boxShadow?: string;
  opacity?: number;
  offset?: [number, number];
  leaderLineStyle?: MeasurementLeaderLineStyle;
}

Defaults: dark gradient background, white text, cyan accent, 22 px label font, leader line #38bdf8 width 1.5, label offset [0, -34].

Events

Measurement events are emitted by MeasurementService and consumed by the plugin to drive its visuals. Useful for app code:

• measurement:created — { measurement }
• measurement:removed — { measurement }
• measurement:point-added — { point }
• measurement:temporary-point-changed — { point }
• measurement:point-updated — { measurement }
• measurement:visibility-changed — { id, visible }
• measurement:config-updated — config payload
• measurement:reset — {}
• measurement:hover-point — point data when hovering an existing point, null otherwise

Example

const measure = viewer.pluginManager.getPlugin("measurement") as MeasurementPlugin;

measure.setMeasurementLabelStyle({
  background: { type: "solid", color: "#0f172a" },
  color: "#f8fafc",
  fontSize: 18,
  offset: [0, -28],
});

measure.setMeasurementTypeLabelStyle("angle", {
  accentColor: "#f59e0b",
  leaderLineStyle: { color: "#f59e0b", width: 1.5, dashArray: "4 4" },
});

measure.enable();
measure.setMeasurementMode("distance");

viewer.eventBus.on("measurement:created", ({ measurement }) => {
  console.log(measurement.type, measurement.result);
});