{"_id":"@bimangle/cesium-tool-measure","_rev":"2-0edf1b89986a2480c02df9d76af9d4d4","name":"@bimangle/cesium-tool-measure","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@bimangle/cesium-tool-measure","version":"1.0.0","keywords":["cesium","measure","distance","coordinate","3dtiles","bimangle"],"author":{"name":"BimAngle"},"license":"MIT","_id":"@bimangle/cesium-tool-measure@1.0.0","maintainers":[{"name":"bimangle.liu","email":"liuyongsheng@msn.com"}],"dist":{"shasum":"ab800daacad874a9c787af36cd367c18b3131146","tarball":"https://registry.npmjs.org/@bimangle/cesium-tool-measure/-/cesium-tool-measure-1.0.0.tgz","fileCount":5,"integrity":"sha512-NUy/TGy5CsOqr0QfuqcNuwUUj8/sfn3ADV7LlZjdl5erZqkcIfClvw1P4GFzMYEM1L9gVIMKGi5QUG4ArsdA+g==","signatures":[{"sig":"MEYCIQD/Bqa+9abtixXM2fjyJ3ytYupOwVrU6svLrx4s6Wt7AwIhALVf3cDLbhfJotQqSjFjKejUzqZL2U9KKv7UqZgKakex","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":78290},"main":"dist/cesium-tool-measure.js","module":"src/cesium-tool-measure.js","scripts":{"build":"rollup -c","prepare":"npm run build"},"_npmUser":{"name":"bimangle.liu","email":"liuyongsheng@msn.com"},"_npmVersion":"11.6.1","description":"A Cesium plugin providing coordinate picking and distance measurement tools.","directories":{},"_nodeVersion":"24.11.0","dependencies":{"@bimangle/cesium-ui":"file:../cesium-ui"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"rollup":"^2.79.2","@rollup/plugin-commonjs":"^22.0.2","@rollup/plugin-node-resolve":"^13.3.0"},"peerDependencies":{"cesium":"^1.110.0"},"_npmOperationalInternal":{"tmp":"tmp/cesium-tool-measure_1.0.0_1783759974702_0.9633416590800841","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@bimangle/cesium-tool-measure","version":"1.0.1","description":"A Cesium plugin providing coordinate picking and distance measurement tools.","main":"dist/cesium-tool-measure.js","module":"src/cesium-tool-measure.js","scripts":{"build":"rollup -c","prepare":"npm run build"},"keywords":["cesium","measure","distance","coordinate","3dtiles","bimangle"],"author":{"name":"BimAngle"},"license":"MIT","publishConfig":{"access":"public"},"dependencies":{"@bimangle/cesium-ui":"file:../cesium-ui"},"peerDependencies":{"cesium":"^1.110.0"},"devDependencies":{"@rollup/plugin-commonjs":"^22.0.2","@rollup/plugin-node-resolve":"^13.3.0","rollup":"^2.79.2"},"gitHead":"98dbd50f44841f03747dc5fd8bd53adce6173b93","_id":"@bimangle/cesium-tool-measure@1.0.1","_nodeVersion":"24.11.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-SXH6r2hSG1F4qVB1FMzTUM7LYHvk42kDqSgChAZ4MFId8iR3jpoq6VaMWNzbVmQH+NKhyk5UKMC4Y35dwEbHWw==","shasum":"1d1a0d4c3fcfd6fefd43cf37ff9b2d7a4fdfbe90","tarball":"https://registry.npmjs.org/@bimangle/cesium-tool-measure/-/cesium-tool-measure-1.0.1.tgz","fileCount":6,"unpackedSize":80546,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCMrObu+qoWcdAzxsFzleOa1Czvzji7iZKdjh3Dgm6lTwIgE/z/D2xbzrlbmrbO0uegUqlxcgOKs8WtjZCEsGQgd0c="}]},"_npmUser":{"name":"bimangle.liu","email":"liuyongsheng@msn.com"},"directories":{},"maintainers":[{"name":"bimangle.liu","email":"liuyongsheng@msn.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cesium-tool-measure_1.0.1_1786677319890_0.5289431009202892"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-11T08:52:54.576Z","modified":"2026-08-14T03:15:20.214Z","1.0.0":"2026-07-11T08:52:54.870Z","1.0.1":"2026-08-14T03:15:20.032Z"},"author":{"name":"BimAngle"},"license":"MIT","keywords":["cesium","measure","distance","coordinate","3dtiles","bimangle"],"description":"A Cesium plugin providing coordinate picking and distance measurement tools.","maintainers":[{"name":"bimangle.liu","email":"liuyongsheng@msn.com"}],"readme":"# @bimangle/cesium-tool-measure\n\nA CesiumJS plugin providing **coordinate picking** and **two-point distance** measurement tools.\n\n基于 CesiumJS 的测量工具插件，提供**坐标拾取**和**两点距离**测量功能。\n\n---\n\n## Features / 特性\n\n- 📍 **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) \n **坐标拾取** — 点击地球或 3D Tiles 获取经纬高；点击 3D Tiles 时额外显示模型本地坐标 N(Y)/E(X)/H(Z)\n- 📐 **Two-point distance** — supports measuring between points on different tilesets; live preview line follows the mouse \n **两点距离** — 支持跨 tileset（点 A、点 B 可属于不同数据集），鼠标预览线实时更新\n- 🗑 **Clear results** — one click removes all measurement entities and associated notification cards \n **一键清除** — 移除全部测量实体及关联通知弹窗\n- 🔔 **Notification cards** — each measurement pushes a result card to the `@bimangle/cesium-ui` notification stack \n **通知卡片** — 每次测量后向通知弹窗堆叠推送结果\n- 🧩 **Toolbar integration** — the 📐 button is registered in the shared `cesium-ui` toolbar; no overlap with other plugins \n **工具条集成** — 📐 按钮注册于共享工具条，与其他插件按钮共存不重叠\n- ⌨️ **Keyboard shortcut** — press `Esc` to cancel the active tool at any time \n **键盘快捷键** — 任意时刻按 `Esc` 取消当前工具\n- 🌐 **Bilingual UI** — automatically uses Simplified Chinese or English based on `navigator.language` \n **双语界面** — 根据 `navigator.language` 自动切换简体中文 / 英文\n\n---\n\n## Dependencies / 依赖\n\n| Dependency / 依赖 | Notes / 说明 |\n|-------------------|-------------|\n| `cesium` (peer) | CesiumJS >= 1.110.0 |\n| `@bimangle/cesium-ui` | UI framework (toolbar + notifications) / UI 框架（工具条 + 通知弹窗） |\n\n---\n\n## Installation / 安装\n\n### NPM\n\n```bash\nnpm install @bimangle/cesium-tool-measure\n```\n\n### CDN\n\n```html\n\n\n\n\n\n\n\n```\n\n---\n\n## Quick Start / 快速开始\n\n### Browser (CDN)\n\n```html\n\n\n\n \n \n \n \n \n\n\n \n \n\n\n```\n\n### NPM / ES Modules\n\n```javascript\nimport * as Cesium from 'cesium';\nimport { ToolMeasureMixin } from '@bimangle/cesium-tool-measure';\n\nconst viewer = new Cesium.Viewer('cesiumContainer');\n\n// One line — cesium-ui is initialized automatically.\n// 一行接入，cesium-ui 会自动初始化。\nviewer.extend(ToolMeasureMixin);\n\n// Access the instance / 访问实例\n// viewer.toolMeasure → ToolMeasure instance\n```\n\nTo customize the toolbar position / 自定义工具条位置：\n\n```javascript\nviewer.extend(ToolMeasureMixin, {\n uiOptions: {\n position: 'top-left',\n direction: 'vertical',\n notificationPosition: 'bottom-right',\n panelCascadeDirection: 'right', // shift overlapping panels right / 面板重叠时向右错开\n }\n});\n```\n\n---\n\n## Usage / 使用方式\n\nAfter initialization, a 📐 button appears on the toolbar. Click it to open the measure sub-panel. \n初始化后，工具条中会出现 📐 按钮，点击展开测量子面板：\n\n```\n┌──────────────────┐\n│ 📐 Measure × │ ← title bar (drag to move / 标题栏可拖拽移动)\n├──────────────────┤\n│ 📍 Pick Coord │ ← click to activate; click again or press Esc to cancel\n│ 📐 Distance │ 点击激活，再次点击或按 Esc 取消\n├──────────────────┤\n│ 🗑 Clear Results │\n└──────────────────┘\n```\n\n### Coordinate Picking / 坐标拾取\n\n1. Click **📍 Pick Coord** (button highlights, cursor changes to crosshair). \n 点击 **📍 拾取坐标**（按钮高亮，鼠标变为十字）\n2. Click anywhere on the globe or a 3D Tiles surface. \n 在地球或 3D Tiles 上单击\n3. A pin marker and coordinate label are drawn at the click point; a notification card shows the full result. \n 拾取点处绘制图钉标记和坐标标注，通知卡片显示详细坐标\n4. The tool returns to idle automatically; the sub-panel stays open. \n 工具自动回到空闲状态，子面板保持打开\n\nNotification content — plain globe surface / 通知内容（纯地球表面）：\n```\nWorld Coordinate / 世界坐标\n Latitude: 30.12345678°\n Longitude: 120.12345678°\n Height: 45.2341 m\n```\n\nNotification content — 3D Tiles surface / 通知内容（3D Tiles 表面）：\n```\nWorld Coordinate / 世界坐标\n Latitude: 30.12345678°\n Longitude: 120.12345678°\n Height: 45.2341 m\n──────────────────────────────\nLocal Coordinate / 本地坐标\n N(Y): 1234.5678 m\n E(X): 567.8901 m\n H(Z): 45.2341 m\n```\n\n### Two-Point Distance / 两点距离\n\n1. Click **📐 Distance**. \n 点击 **📐 两点距离**\n2. Click point A (blue pin); a preview dashed line and live distance label follow the mouse. \n 单击点 A（蓝色图钉），鼠标移动时显示预览虚线和实时距离\n3. Click point B (green pin) to complete the measurement: \n 单击点 B（绿色图钉）完成测量：\n - A solid polyline is drawn between A and B / 绘制 A→B 实线折线\n - A distance label appears at the midpoint / 中点显示距离标注\n - A notification card shows the distance and coordinates of both points / 通知卡片显示距离及两点坐标\n\n### Clear Results / 清除结果\n\nClick **🗑 Clear Results** to remove all measurement entities and close all associated notification cards. \n点击 **🗑 清除结果** 移除全部测量实体并关闭关联通知弹窗。\n\n### Keyboard Shortcut / 键盘快捷键\n\n| Key / 按键 | Behavior / 行为 |\n|-----------|----------------|\n| `Esc` | Cancel the active tool, clear unfinished preview entities, return to idle / 取消当前工具，清除未完成预览实体，回到空闲状态 |\n\n---\n\n## API Reference\n\n### `ToolMeasureMixin(viewer, options?)`\n\nInitializes the measure tool and attaches a `ToolMeasure` instance to `viewer.toolMeasure`. \n**Idempotent** — safe to call multiple times.\n\n初始化测量工具并将 `ToolMeasure` 实例挂载到 `viewer.toolMeasure`。**幂等**，多次调用安全。\n\nCalls `CesiumUIMixin(viewer, options.uiOptions)` internally to ensure the UI framework is ready. \n内部自动调用 `CesiumUIMixin(viewer, options.uiOptions)` 确保 UI 框架就绪。\n\n| Parameter / 参数 | Type / 类型 | Description / 说明 |\n|-----------------|-------------|-------------------|\n| `viewer` | `Cesium.Viewer` | Target viewer / 目标 Viewer 实例 |\n| `options.uiOptions` | `object` | Passed to `CesiumUIMixin` (effective only on first init). Supports all `CesiumUIMixin` options including `panelCascadeDirection`. / 透传给 `CesiumUIMixin`（仅首次初始化有效），支持包含 `panelCascadeDirection` 在内的所有选项 |\n\n---\n\n### `ToolMeasure` — via `viewer.toolMeasure`\n\n#### Properties / 属性\n\n| Property / 属性 | Type / 类型 | Description / 说明 |\n|----------------|-------------|-------------------|\n| `activeTool` | `null \\| 'coord' \\| 'distance'` | Currently active tool; `null` when idle / 当前激活工具，空闲时为 `null` |\n\n#### Methods / 方法\n\n##### `activateCoordPick()`\n\nActivates the coordinate-picking tool. If already active, cancels it (toggle). \n激活坐标拾取工具。若当前已激活则取消（toggle 行为）。\n\n```javascript\nviewer.toolMeasure.activateCoordPick();\n```\n\n##### `activateDistance()`\n\nActivates the two-point distance tool. If already active, cancels it (toggle). \n激活两点距离工具。若当前已激活则取消（toggle 行为）。\n\n```javascript\nviewer.toolMeasure.activateDistance();\n```\n\n##### `deactivate()`\n\nCancels the active tool and returns to idle. \n取消当前激活的工具，回到空闲状态。\n\n```javascript\nviewer.toolMeasure.deactivate();\n```\n\n##### `clearAll()`\n\nRemoves all measurement result entities and closes associated notification cards. \n移除全部测量结果实体并关闭关联通知弹窗。\n\n```javascript\nviewer.toolMeasure.clearAll();\n```\n\n##### `destroy()`\n\nDestroys the plugin: deactivates tools, clears results, removes DOM, unbinds event listeners, unregisters the toolbar button. \n销毁插件：取消工具、清除结果、移除 DOM、解绑事件监听、从工具条移除按钮。\n\n```javascript\nviewer.toolMeasure.destroy();\n```\n\n---\n\n## Integration with other BimAngle plugins / 与其他插件联用\n\n```html\n\n\n\n\n\n\n\n\n\n\n```\n\nResulting toolbar layout / 工具条按钮排列效果：\n\n```\n┌──┐ ← top-left\n│🌲│ ← scene-tree (cesium-scene-tree)\n├──┤\n│📐│ ← measure (cesium-tool-measure)\n└──┘\n```\n\n---\n\n## Technical Notes / 技术说明\n\n### Coordinate picking strategy / 坐标拾取策略\n\nEach click attempts, in order / 每次点击依次尝试：\n\n1. `viewer.scene.pickPosition(windowPos)` — works on 3D Tiles and globe / 适用于 3D Tiles 表面和地球\n2. Fallback: `viewer.scene.globe.pick(ray, scene)` — pure globe surface when no depth info / 无深度信息时降级到纯地球表面\n\n### 3D Tiles local coordinate conversion / 3D Tiles 本地坐标换算\n\n```javascript\nconst inv = Cesium.Matrix4.inverse(tileset.root.transform, new Cesium.Matrix4());\nconst localPos = Cesium.Matrix4.multiplyByPoint(inv, worldPos, new Cesium.Cartesian3());\n```\n\nAxis convention / 轴约定：\n\n| Label / 显示标签 | Source / 来源 | Meaning / 含义 |\n|-----------------|---------------|---------------|\n| N(Y) | `localPos.y` | North / 北向 |\n| E(X) | `localPos.x` | East / 东向 |\n| H(Z) | `localPos.z` | Height / 高度 |\n\n### Measurement record management / 测量结果管理\n\nEach completed measurement creates one `MeasureRecord` holding: \n每次完整测量产生一个 `MeasureRecord`，包含：\n\n- All related `Cesium.Entity` objects (pins, polyline, label) / 所有相关实体（图钉、折线、标注）\n- The associated `NotificationHandle` / 关联的通知卡片句柄\n\n`clearAll()` calls `viewer.entities.remove()` for each entity and `notification.close()` for each card. \n`clearAll()` 逐条调用 `viewer.entities.remove()` 并 `notification.close()`。\n\n### Event handling / 事件处理\n\nUses a dedicated `Cesium.ScreenSpaceEventHandler` instance — does not interfere with `cesium-info-accessor` or any other plugin's click logic. Both plugins can coexist. \n使用独立的 `ScreenSpaceEventHandler` 实例，不干扰 `cesium-info-accessor` 或其他插件的点击逻辑，可同时共存。\n\n---\n\n## CSS Class Reference / CSS 命名规范\n\nAll CSS classes use the `ba-ctm-` prefix (`ba` = BimAngle, `ctm` = cesium-tool-measure). \n所有 CSS 类名采用 `ba-ctm-` 前缀（`ba` = BimAngle，`ctm` = cesium-tool-measure）。\n\n| Class / 类名 | Purpose / 用途 |\n|-------------|---------------|\n| `.ba-ctm-panel` | Measure sub-panel container / 测量子面板容器 |\n| `.ba-ctm-panel--visible` | Sub-panel visible state / 子面板可见态 |\n| `.ba-ctm-panel-header` | Title bar (draggable) / 标题栏（可拖拽） |\n| `.ba-ctm-panel-title` | Title text / 标题文字 |\n| `.ba-ctm-panel-close` | Close button / 关闭按钮 |\n| `.ba-ctm-panel-tools` | Tool button area / 工具按钮区 |\n| `.ba-ctm-tool-btn` | Tool button / 工具按钮 |\n| `.ba-ctm-tool-btn--active` | Active tool button / 工具按钮激活态 |\n| `.ba-ctm-panel-actions` | Action button area (bottom) / 操作按钮区（底部） |\n| `.ba-ctm-action-btn` | Action button (e.g. Clear) / 操作按钮（如清除） |\n| `.ba-ctm-notify-content` | Notification content wrapper / 通知内容容器 |\n| `.ba-ctm-notify-section-title` | Notification section title / 通知分区标题 |\n| `.ba-ctm-notify-row` | Notification data row / 通知数据行 |\n| `.ba-ctm-notify-label` | Data row label / 数据行标签 |\n| `.ba-ctm-notify-value` | Data row value / 数据行数值 |\n| `.ba-ctm-notify-divider` | In-notification divider line / 通知内分割线 |\n\n---\n\n## Compatibility / 兼容性\n\n- CesiumJS >= 1.110.0\n- Chrome 90+, Firefox 88+, Edge 90+\n\n---\n\n## Build / 构建\n\n```bash\nnpm install\nnpm run build\n# Output: dist/cesium-tool-measure.js\n```\n\n---\n\n## Changelog / 变更记录\n\nSee [CHANGELOG.md](./CHANGELOG.md) for the full history. \n完整变更历史请参阅 [CHANGELOG.md](./CHANGELOG.md)。\n\n### v1.0.1\n- **Fix** 两点距离工具：点击第一个点后按 `Esc` 取消，遗留的点 A 标记现在会被正确清除 / Distance tool: orphaned point-A pin is now correctly removed when cancelling via `Esc` or switching tools\n\n### v1.0.0\n- Initial release / 初始发布\n\n---\n\n## License / 许可证\n\nMIT © BimAngle\n","readmeFilename":"README.md"}