Distance Measurement
DMap3D provides three distance measurement tools: Spatial Distance, Horizontal Distance, and Surface Distance.
Import
import DMap3D from 'dmap3d'
import * as Cesium from 'cesium'
Spatial Distance Measurement
DMap3D.measurement.spaceDistance measures the straight-line distance between multiple points in 3D space.
Basic Usage
const viewer = new Cesium.Viewer('cesiumContainer')
// Create spatial distance measurement tool
const spaceDistance = new DMap3D.measurement.spaceDistance(viewer)
// Listen for measurement complete event
spaceDistance.onMeasureEnd((totalDistance) => {
console.log('Total spatial distance:', totalDistance.toFixed(2), 'meters')
})
// Activate measurement (left-click to add points, right-click to finish)
spaceDistance.activate()
Constructor
new DMap3D.measurement.spaceDistance(viewer, options?)
Parameters:
viewer- Cesium.Viewer instanceoptions?- Optional configuration
Options:
interface MeasurementOptions {
colors?: {
line?: string // Measurement line color, default '#00FF00'
point?: string // Measurement point color, default '#FF0000'
font?: string // Label text color, default '#FFFFFF'
fontOutline?: string // Text outline color, default '#000000'
}
fontSize?: number // Font size, default 14
}
Methods
| Method | Description |
|---|---|
activate() | Activate measurement (left-click to add points, right-click to finish) |
deactivate() | Deactivate measurement, keeping drawn results |
clear() | Clear all measurement results |
destroy() | Destroy the tool and release resources |
onMeasureEnd(callback) | Register measurement complete callback, parameter is total distance (meters) |
getTotalDistance() | Get the total distance of the current measurement (meters) |
Horizontal Distance Measurement
DMap3D.measurement.horizontalDistance measures the projected horizontal distance between two points, ignoring height difference.
Basic Usage
const viewer = new Cesium.Viewer('cesiumContainer')
// Create horizontal distance measurement tool
const horizontalDistance = new DMap3D.measurement.horizontalDistance(viewer)
// Listen for measurement complete event
horizontalDistance.onMeasureEnd((distance) => {
console.log('Horizontal distance:', distance.toFixed(2), 'meters')
})
// Activate measurement (left-click twice to complete)
horizontalDistance.activate()
Constructor
new DMap3D.measurement.horizontalDistance(viewer, options?)
Parameters:
viewer- Cesium.Viewer instanceoptions?- Optional configuration
Options:
interface HorizontalDistanceOptions {
colors?: {
line?: string // Connection line color, default '#00FF00'
horizontalLine?: string // Horizontal reference line color, default '#00FF00'
verticalLine?: string // Vertical reference line color, default '#FF0000'
point?: string // Measurement point color, default '#FF0000'
font?: string // Label text color, default '#FFFFFF'
fontOutline?: string // Text outline color, default '#000000'
}
fontSize?: number // Font size, default 14
}
Methods
| Method | Description |
|---|---|
activate() | Activate measurement (left-click twice to complete) |
deactivate() | Deactivate measurement, keeping drawn results |
clear() | Clear all measurement results |
destroy() | Destroy the tool and release resources |
onMeasureEnd(callback) | Register measurement complete callback, parameter is horizontal distance (meters) |
getHorizontalDistance() | Get the current horizontal distance measurement (meters) |
Surface Distance Measurement
DMap3D.measurement.surfaceDistance measures the actual path distance along the terrain surface.
Basic Usage
const viewer = new Cesium.Viewer('cesiumContainer')
// Create surface distance measurement tool
const surfaceDistance = new DMap3D.measurement.surfaceDistance(viewer)
// Listen for measurement complete event
surfaceDistance.onMeasureEnd((totalDistance) => {
console.log('Total surface distance:', totalDistance.toFixed(2), 'meters')
})
// Activate measurement (left-click to add points, right-click to finish)
surfaceDistance.activate()
Constructor
new DMap3D.measurement.surfaceDistance(viewer, options?)
Parameters:
viewer- Cesium.Viewer instanceoptions?- Optional configuration
Options:
interface SurfaceDistanceOptions {
colors?: {
line?: string // Measurement line color, default '#FBFB00'
point?: string // Measurement point color, default '#0008FF'
font?: string // Label text color, default '#FFFFFF'
fontOutline?: string // Text outline color, default '#000000'
}
fontSize?: number // Font size, default 14
includeModels?: boolean // Whether to include model heights, default false
}
Methods
| Method | Description |
|---|---|
activate() | Activate measurement (left-click to add points, right-click to finish) |
deactivate() | Deactivate measurement, keeping drawn results |
clear() | Clear all measurement results |
destroy() | Destroy the tool and release resources |
onMeasureEnd(callback) | Register measurement complete callback, parameter is total surface distance (meters) |
getTotalDistance() | Get the total surface distance of the current measurement (meters) |
Comparison of Three Distance Types
| Type | Description | Use Cases |
|---|---|---|
| Spatial Distance | Straight-line distance between two points (3D) | Aviation distance, line-of-sight distance |
| Horizontal Distance | Projected distance ignoring height difference | Land planning, planar measurement |
| Surface Distance | Actual path along the terrain surface | Road planning, hiking distance |
Complete Example
// Create three distance measurement tools
const spaceDistance = new DMap3D.measurement.spaceDistance(viewer, {
colors: { line: '#00FFFF', point: '#FFFF00' }
})
const horizontalDistance = new DMap3D.measurement.horizontalDistance(viewer, {
colors: { line: '#FF00FF', horizontalLine: '#FF00FF' }
})
const surfaceDistance = new DMap3D.measurement.surfaceDistance(viewer, {
includeModels: true
})
// Listen for measurement complete events
spaceDistance.onMeasureEnd((d) => console.log('Spatial distance:', d.toFixed(2), 'meters'))
horizontalDistance.onMeasureEnd((d) => console.log('Horizontal distance:', d.toFixed(2), 'meters'))
surfaceDistance.onMeasureEnd((d) => console.log('Surface distance:', d.toFixed(2), 'meters'))
// Activate one of them
spaceDistance.activate()
// Clear
spaceDistance.clear()
// Destroy
spaceDistance.destroy()
horizontalDistance.destroy()
surfaceDistance.destroy()