@bimangle/cesium-tool-measure

A CesiumJS plugin providing coordinate picking and two-point distance measurement tools.

基于 CesiumJS 的测量工具插件，提供坐标拾取和两点距离测量功能。

Features / 特性

📍 Coordinate picking — click the globe or a 3D Tiles surface to get latitude, longitude and height; clicking on 3D Tiles also shows the model-local coordinates N(Y)/E(X)/H(Z)
坐标拾取 — 点击地球或 3D Tiles 获取经纬高；点击 3D Tiles 时额外显示模型本地坐标 N(Y)/E(X)/H(Z)
📐 Two-point distance — supports measuring between points on different tilesets; live preview line follows the mouse
两点距离 — 支持跨 tileset（点 A、点 B 可属于不同数据集），鼠标预览线实时更新
🗑 Clear results — one click removes all measurement entities and associated notification cards
一键清除 — 移除全部测量实体及关联通知弹窗
🔔 Notification cards — each measurement pushes a result card to the @bimangle/cesium-ui notification stack
通知卡片 — 每次测量后向通知弹窗堆叠推送结果
🧩 Toolbar integration — the 📐 button is registered in the shared cesium-ui toolbar; no overlap with other plugins
工具条集成 — 📐 按钮注册于共享工具条，与其他插件按钮共存不重叠
⌨️ Keyboard shortcut — press Esc to cancel the active tool at any time
键盘快捷键 — 任意时刻按 Esc 取消当前工具
🌐 Bilingual UI — automatically uses Simplified Chinese or English based on navigator.language
双语界面 — 根据 navigator.language 自动切换简体中文 / 英文

Dependencies / 依赖

Dependency / 依赖	Notes / 说明
`cesium` (peer)	CesiumJS >= 1.110.0
`@bimangle/cesium-ui`	UI framework (toolbar + notifications) / UI 框架（工具条 + 通知弹窗）

Installation / 安装

NPM

npm install @bimangle/cesium-tool-measure

CDN

<!-- Cesium must be loaded first / 必须先加载 Cesium -->
<script src="https://cesium.com/downloads/cesiumjs/releases/1.120/Build/Cesium/Cesium.js"></script>
<link href="https://cesium.com/downloads/cesiumjs/releases/1.120/Build/Cesium/Widgets/widgets.css" rel="stylesheet">

<!-- Then include cesium-ui and cesium-tool-measure / 再引入 cesium-ui 和 cesium-tool-measure -->
<script src="https://unpkg.com/@bimangle/cesium-ui/dist/cesium-ui.js"></script>
<script src="https://unpkg.com/@bimangle/cesium-tool-measure/dist/cesium-tool-measure.js"></script>

Quick Start / 快速开始

Browser (CDN)

<!DOCTYPE html>
<html>
<head>
  <script src="https://cesium.com/downloads/cesiumjs/releases/1.120/Build/Cesium/Cesium.js"></script>
  <link href="https://cesium.com/downloads/cesiumjs/releases/1.120/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
  <script src="https://unpkg.com/@bimangle/cesium-ui/dist/cesium-ui.js"></script>
  <script src="https://unpkg.com/@bimangle/cesium-tool-measure/dist/cesium-tool-measure.js"></script>
  <style>
    html, body, #cesiumContainer { width: 100%; height: 100%; margin: 0; padding: 0; overflow: hidden; }
  </style>
</head>
<body>
  <div id="cesiumContainer"></div>
  <script>
    const viewer = new Cesium.Viewer('cesiumContainer');

    // One line — cesium-ui is initialized automatically.
    // 一行接入，cesium-ui 会自动初始化。
    viewer.extend(ToolMeasureMixin);

    // Access the instance / 访问实例
    // viewer.toolMeasure  → ToolMeasure instance
  </script>
</body>
</html>

NPM / ES Modules

import * as Cesium from 'cesium';
import { ToolMeasureMixin } from '@bimangle/cesium-tool-measure';

const viewer = new Cesium.Viewer('cesiumContainer');

// One line — cesium-ui is initialized automatically.
// 一行接入，cesium-ui 会自动初始化。
viewer.extend(ToolMeasureMixin);

// Access the instance / 访问实例
// viewer.toolMeasure  → ToolMeasure instance

To customize the toolbar position / 自定义工具条位置：

viewer.extend(ToolMeasureMixin, {
    uiOptions: {
        position:              'top-left',
        direction:             'vertical',
        notificationPosition:  'bottom-right',
        panelCascadeDirection: 'right',  // shift overlapping panels right / 面板重叠时向右错开
    }
});

Usage / 使用方式

After initialization, a 📐 button appears on the toolbar. Click it to open the measure sub-panel.
初始化后，工具条中会出现 📐 按钮，点击展开测量子面板：

┌──────────────────┐
│ 📐 Measure     × │  ← title bar (drag to move / 标题栏可拖拽移动)
├──────────────────┤
│ 📍 Pick Coord    │  ← click to activate; click again or press Esc to cancel
│ 📐 Distance      │    点击激活，再次点击或按 Esc 取消
├──────────────────┤
│ 🗑 Clear Results │
└──────────────────┘

Coordinate Picking / 坐标拾取

Click 📍 Pick Coord (button highlights, cursor changes to crosshair).
点击 📍 拾取坐标（按钮高亮，鼠标变为十字）
Click anywhere on the globe or a 3D Tiles surface.
在地球或 3D Tiles 上单击
A pin marker and coordinate label are drawn at the click point; a notification card shows the full result.
拾取点处绘制图钉标记和坐标标注，通知卡片显示详细坐标
The tool returns to idle automatically; the sub-panel stays open.
工具自动回到空闲状态，子面板保持打开

Notification content — plain globe surface / 通知内容（纯地球表面）：

World Coordinate / 世界坐标
  Latitude:     30.12345678°
  Longitude:   120.12345678°
  Height:          45.2341 m

Notification content — 3D Tiles surface / 通知内容（3D Tiles 表面）：

World Coordinate / 世界坐标
  Latitude:     30.12345678°
  Longitude:   120.12345678°
  Height:          45.2341 m
──────────────────────────────
Local Coordinate / 本地坐标
  N(Y):   1234.5678 m
  E(X):    567.8901 m
  H(Z):     45.2341 m

Two-Point Distance / 两点距离

Click 📐 Distance.
点击 📐 两点距离
Click point A (blue pin); a preview dashed line and live distance label follow the mouse.
单击点 A（蓝色图钉），鼠标移动时显示预览虚线和实时距离
Click point B (green pin) to complete the measurement:
单击点 B（绿色图钉）完成测量：
- A solid polyline is drawn between A and B / 绘制 A→B 实线折线
- A distance label appears at the midpoint / 中点显示距离标注
- A notification card shows the distance and coordinates of both points / 通知卡片显示距离及两点坐标

Clear Results / 清除结果

Click 🗑 Clear Results to remove all measurement entities and close all associated notification cards.
点击 🗑 清除结果 移除全部测量实体并关闭关联通知弹窗。

Keyboard Shortcut / 键盘快捷键

Key / 按键	Behavior / 行为
`Esc`	Cancel the active tool, clear unfinished preview entities, return to idle / 取消当前工具，清除未完成预览实体，回到空闲状态

API Reference

`ToolMeasureMixin(viewer, options?)`

Initializes the measure tool and attaches a ToolMeasure instance to viewer.toolMeasure.
Idempotent — safe to call multiple times.

初始化测量工具并将 ToolMeasure 实例挂载到 viewer.toolMeasure。幂等，多次调用安全。

Calls CesiumUIMixin(viewer, options.uiOptions) internally to ensure the UI framework is ready.
内部自动调用 CesiumUIMixin(viewer, options.uiOptions) 确保 UI 框架就绪。

Parameter / 参数	Type / 类型	Description / 说明
`viewer`	`Cesium.Viewer`	Target viewer / 目标 Viewer 实例
`options.uiOptions`	`object`	Passed to `CesiumUIMixin` (effective only on first init). Supports all `CesiumUIMixin` options including `panelCascadeDirection`. / 透传给 `CesiumUIMixin`（仅首次初始化有效），支持包含 `panelCascadeDirection` 在内的所有选项

`ToolMeasure` — via `viewer.toolMeasure`

Properties / 属性

Property / 属性	Type / 类型	Description / 说明
`activeTool`	`null \| 'coord' \| 'distance'`	Currently active tool; `null` when idle / 当前激活工具，空闲时为 `null`

Methods / 方法

`activateCoordPick()`

Activates the coordinate-picking tool. If already active, cancels it (toggle).
激活坐标拾取工具。若当前已激活则取消（toggle 行为）。

viewer.toolMeasure.activateCoordPick();

`activateDistance()`

Activates the two-point distance tool. If already active, cancels it (toggle).
激活两点距离工具。若当前已激活则取消（toggle 行为）。

viewer.toolMeasure.activateDistance();

`deactivate()`

Cancels the active tool and returns to idle.
取消当前激活的工具，回到空闲状态。

viewer.toolMeasure.deactivate();

`clearAll()`

Removes all measurement result entities and closes associated notification cards.
移除全部测量结果实体并关闭关联通知弹窗。

viewer.toolMeasure.clearAll();

`destroy()`

Destroys the plugin: deactivates tools, clears results, removes DOM, unbinds event listeners, unregisters the toolbar button.
销毁插件：取消工具、清除结果、移除 DOM、解绑事件监听、从工具条移除按钮。

viewer.toolMeasure.destroy();

Integration with other BimAngle plugins / 与其他插件联用

<!-- Load order is flexible — Mixin functions guarantee idempotent init internally. -->
<!-- 引入顺序无强制要求，Mixin 函数内部保证幂等初始化。 -->
<script src="https://cesium.com/downloads/cesiumjs/releases/1.120/Build/Cesium/Cesium.js"></script>
<link href="https://cesium.com/downloads/cesiumjs/releases/1.120/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
<script src="https://unpkg.com/@bimangle/cesium-ui/dist/cesium-ui.js"></script>
<script src="https://unpkg.com/@bimangle/cesium-info-accessor/dist/cesium-info-accessor.js"></script>
<script src="https://unpkg.com/@bimangle/cesium-scene-tree/dist/cesium-scene-tree.js"></script>
<script src="https://unpkg.com/@bimangle/cesium-tool-measure/dist/cesium-tool-measure.js"></script>

<script>
  const viewer = new Cesium.Viewer('cesiumContainer');

  // Optionally configure cesium-ui upfront; plugins fall back to defaults otherwise.
  // 可选：提前配置 cesium-ui，否则各插件以默认参数自动初始化。
  viewer.extend(CesiumUIMixin, {
      position:             'top-left',
      direction:            'vertical',
      notificationPosition: 'bottom-right',
  });

  viewer.extend(InfoAccessorMixin, { autoAttach: true });
  viewer.extend(SceneTreeMixin);
  viewer.extend(ToolMeasureMixin);
</script>

Resulting toolbar layout / 工具条按钮排列效果：

┌──┐  ← top-left
│🌲│  ← scene-tree (cesium-scene-tree)
├──┤
│📐│  ← measure (cesium-tool-measure)
└──┘

Technical Notes / 技术说明

Coordinate picking strategy / 坐标拾取策略

Each click attempts, in order / 每次点击依次尝试：

viewer.scene.pickPosition(windowPos) — works on 3D Tiles and globe / 适用于 3D Tiles 表面和地球
Fallback: viewer.scene.globe.pick(ray, scene) — pure globe surface when no depth info / 无深度信息时降级到纯地球表面

3D Tiles local coordinate conversion / 3D Tiles 本地坐标换算

const inv = Cesium.Matrix4.inverse(tileset.root.transform, new Cesium.Matrix4());
const localPos = Cesium.Matrix4.multiplyByPoint(inv, worldPos, new Cesium.Cartesian3());

Axis convention / 轴约定：

Label / 显示标签	Source / 来源	Meaning / 含义
N(Y)	`localPos.y`	North / 北向
E(X)	`localPos.x`	East / 东向
H(Z)	`localPos.z`	Height / 高度

Measurement record management / 测量结果管理

Each completed measurement creates one MeasureRecord holding:
每次完整测量产生一个 MeasureRecord，包含：

All related Cesium.Entity objects (pins, polyline, label) / 所有相关实体（图钉、折线、标注）
The associated NotificationHandle / 关联的通知卡片句柄

clearAll() calls viewer.entities.remove() for each entity and notification.close() for each card.
clearAll() 逐条调用 viewer.entities.remove() 并 notification.close()。

Event handling / 事件处理

Uses a dedicated Cesium.ScreenSpaceEventHandler instance — does not interfere with cesium-info-accessor or any other plugin's click logic. Both plugins can coexist.
使用独立的 ScreenSpaceEventHandler 实例，不干扰 cesium-info-accessor 或其他插件的点击逻辑，可同时共存。

CSS Class Reference / CSS 命名规范

All CSS classes use the ba-ctm- prefix (ba = BimAngle, ctm = cesium-tool-measure).
所有 CSS 类名采用 ba-ctm- 前缀（ba = BimAngle，ctm = cesium-tool-measure）。

Class / 类名	Purpose / 用途
`.ba-ctm-panel`	Measure sub-panel container / 测量子面板容器
`.ba-ctm-panel--visible`	Sub-panel visible state / 子面板可见态
`.ba-ctm-panel-header`	Title bar (draggable) / 标题栏（可拖拽）
`.ba-ctm-panel-title`	Title text / 标题文字
`.ba-ctm-panel-close`	Close button / 关闭按钮
`.ba-ctm-panel-tools`	Tool button area / 工具按钮区
`.ba-ctm-tool-btn`	Tool button / 工具按钮
`.ba-ctm-tool-btn--active`	Active tool button / 工具按钮激活态
`.ba-ctm-panel-actions`	Action button area (bottom) / 操作按钮区（底部）
`.ba-ctm-action-btn`	Action button (e.g. Clear) / 操作按钮（如清除）
`.ba-ctm-notify-content`	Notification content wrapper / 通知内容容器
`.ba-ctm-notify-section-title`	Notification section title / 通知分区标题
`.ba-ctm-notify-row`	Notification data row / 通知数据行
`.ba-ctm-notify-label`	Data row label / 数据行标签
`.ba-ctm-notify-value`	Data row value / 数据行数值
`.ba-ctm-notify-divider`	In-notification divider line / 通知内分割线

Compatibility / 兼容性

CesiumJS >= 1.110.0
Chrome 90+, Firefox 88+, Edge 90+

Build / 构建

npm install
npm run build
# Output: dist/cesium-tool-measure.js

Changelog / 变更记录

See CHANGELOG.md for the full history.
完整变更历史请参阅 CHANGELOG.md。

v1.0.1

Fix 两点距离工具：点击第一个点后按 Esc 取消，遗留的点 A 标记现在会被正确清除 / Distance tool: orphaned point-A pin is now correctly removed when cancelling via Esc or switching tools

v1.0.0

Initial release / 初始发布

License / 许可证

MIT © BimAngle

Name		Name	Last commit message	Last commit date
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
rollup.config.js		rollup.config.js

Latest commit

History

Folders and files

Repository files navigation

@bimangle/cesium-tool-measure

Features / 特性

Dependencies / 依赖

Installation / 安装

NPM

CDN

Quick Start / 快速开始

Browser (CDN)

NPM / ES Modules

Usage / 使用方式

Coordinate Picking / 坐标拾取

Two-Point Distance / 两点距离

Clear Results / 清除结果

Keyboard Shortcut / 键盘快捷键

API Reference

ToolMeasureMixin(viewer, options?)

ToolMeasure — via viewer.toolMeasure

Properties / 属性

Methods / 方法

activateCoordPick()

activateDistance()

deactivate()

clearAll()

destroy()

Integration with other BimAngle plugins / 与其他插件联用

Technical Notes / 技术说明

Coordinate picking strategy / 坐标拾取策略

3D Tiles local coordinate conversion / 3D Tiles 本地坐标换算

Measurement record management / 测量结果管理

Event handling / 事件处理

CSS Class Reference / CSS 命名规范

Compatibility / 兼容性

Build / 构建

Changelog / 变更记录

v1.0.1

v1.0.0

License / 许可证

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages