Tip
The Measure plugin is used to measure distances and areas within a Realsee VR space, helping users get an intuitive sense of the size of the space.
Two measure plugins are currently available:
- MeasurePlugin — measurement tool (new version)
- PanoMeasurePlugin — measurement tool (classic version)
Choosing a plugin
Data dependencies
| Comparison | MeasurePlugin (new) | PanoMeasurePlugin (classic) |
|---|---|---|
| Server-side data | Not required | Supports loading data from the /open/v3/ruler/search API |
| Data format | { points: Vector3[] }[] | MeasurePluginServerData (polyline JSON) |
| Data persistence | Must be implemented yourself | Supports load() / toJson() serialization |
Feature comparison
| Feature | MeasurePlugin (new) | PanoMeasurePlugin (classic) |
|---|---|---|
| Distance measurement | ✅ | ✅ |
| Area measurement | ✅ (requires the Util for calculation) | ✅ (built-in calculation and display) |
| Automatic polygon closing | ✅ | ✅ |
| Right-triangle helper lines | ✅ | ❌ |
| Endpoint drag-to-reposition | ✅ (long-press and drag) | ❌ |
| Magnifier | ✅ (built-in PointSelector) | ✅ (configurable parameters) |
| Built-in UI controller | ❌ | ✅ (supports desktop / mobile) |
| Guided hints | ❌ | ✅ (GuideController) |
| Keyboard shortcut support | ✅ | ✅ |
| Unit switching | ✅ (setUnit) | ✅ (changeConfigs) |
| Precision settings | ✅ (setPrecision) | Fixed at 2 decimal places |
Modes and states
| Comparison | MeasurePlugin (new) | PanoMeasurePlugin (classic) |
|---|---|---|
| Working mode | Single mode | Four modes: Watch / Edit / Mixed / View |
| Desktop default | Starts measuring directly | Watch mode (viewing existing data) |
| Mobile support | General | Mixed mode (specifically optimized) |
| Mode switching | Not required | changeMode() / edit() / save() |
Event system
| Comparison | MeasurePlugin (new) | PanoMeasurePlugin (classic) |
|---|---|---|
| Core events | measureEnd (returns the end reason + point coordinates) | A variety of fine-grained events |
| Editing events | undo | editedPolylineChange, editedDashedLineChange, revoke, complete, etc. |
| State events | ❌ | enable, disable, modeChange, measureTypeChange |
| Point-selection events | ❌ (obtained via measureEnd) | pointsChange, anchorChange, getStartPoint, getEndPoint |
| Interaction events | ❌ | selectedChange, wantsDragLine, readyComplete |
API design
MeasurePlugin (new) — streamlined API:
// Core methods
measure() // Start measuring
endMeasure() // End measuring
undo() // Undo the last step
cancel() // Cancel the current measurement
clear() // Clear all measurements
dispose() // Destroy the plugin
// Configuration methods
setUnit(unit) // Switch units
setPrecision(n) // Set precision
setLengthEnable(b) // Show / hide length labels
load(data) // Load dataPanoMeasurePlugin (classic) — full API:
// Lifecycle
enable({ mode }) // Enable the plugin
disable() // Disable the plugin
dispose() // Destroy the plugin
// Mode control
changeMode(mode) // Switch mode (Watch/Edit/Mixed/View)
edit(measureType) // Enter edit mode
save({ mode }) // Save the edit
// Data operations
load(data) // Load data
toJson() // Export data
clear() // Clear data
// Edit operations
revoke() // Undo
changeMeasureType() // Switch measurement type (line/area)
removePolyline() // Remove a polyline
removeArea() // Remove an area
// Interaction control
highlightLine() // Highlight a line segment
clearHighlightLines() // Clear highlights
setCustomText() // Set line-segment text
changeConfigs() // Change configurationUse cases
| Scenario | Recommended plugin |
|---|---|
| Quickly integrate standard measurement functionality | PanoMeasurePlugin |
| Need to load / save server-side measurement data | PanoMeasurePlugin |
| Need built-in UI and guided hints | PanoMeasurePlugin |
| Specifically optimized mobile experience | PanoMeasurePlugin |
| Need fine-grained control over the editing flow and state | PanoMeasurePlugin |
| Custom measurement UI | MeasurePlugin |
| Need to obtain measurement point coordinates for custom calculations | MeasurePlugin |
| Need to listen for the measurement-end event | MeasurePlugin |
| Need to dynamically adjust precision | MeasurePlugin |
| Endpoint drag-to-reposition functionality | MeasurePlugin |
| Right-triangle helper lines | MeasurePlugin |
| Lightweight integration with minimal dependencies | MeasurePlugin |
Recommendations
- Choose PanoMeasurePlugin if you need full measurement functionality, built-in UI, data persistence, or a specifically optimized mobile experience.
- Choose MeasurePlugin if you need a custom UI, want to listen for measurement events to obtain point coordinates, or need to perform custom area or length calculations.
