{"_id":"@bimangle/cesium-tool-excavate","_rev":"2-04b571a029022e069cdda9e1224562ee","name":"@bimangle/cesium-tool-excavate","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@bimangle/cesium-tool-excavate","version":"1.0.0","keywords":["cesium","terrain","excavate","clipping","polygon","bimangle"],"author":{"name":"BimAngle"},"license":"MIT","_id":"@bimangle/cesium-tool-excavate@1.0.0","maintainers":[{"name":"bimangle.liu","email":"liuyongsheng@msn.com"}],"dist":{"shasum":"3b0037f17cecd83faad57953fccf473773ea31bd","tarball":"https://registry.npmjs.org/@bimangle/cesium-tool-excavate/-/cesium-tool-excavate-1.0.0.tgz","fileCount":5,"integrity":"sha512-y2V1KbJbmImqeF0m2WhB0prex70FwogKkJkCFzC3UYM+k4BxnZKUVGNyq6pHsHI4VZP1OdeL9nUNuINzqrXiOA==","signatures":[{"sig":"MEQCIBD6t3TQQxdC1dx5k12OfnkzliH+slrTT5/x/pDmZ4+YAiAVfV53Cs3MyUdc/WcFK9q9Fbw1qSexpKxOmd7eoqkGXQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":105909},"main":"dist/cesium-tool-excavate.js","module":"src/cesium-tool-excavate.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 multi-mode terrain excavation tools (rectangle drag and precise polygon).","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.111.0"},"_npmOperationalInternal":{"tmp":"tmp/cesium-tool-excavate_1.0.0_1785139972154_0.3232620990246273","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@bimangle/cesium-tool-excavate","version":"1.1.0","description":"A Cesium plugin providing multi-mode terrain excavation tools (rectangle drag and precise polygon).","main":"dist/cesium-tool-excavate.js","module":"src/cesium-tool-excavate.js","scripts":{"build":"rollup -c","prepare":"npm run build"},"keywords":["cesium","terrain","excavate","clipping","polygon","bimangle"],"author":{"name":"BimAngle"},"license":"MIT","publishConfig":{"access":"public"},"dependencies":{"@bimangle/cesium-ui":"file:../cesium-ui"},"peerDependencies":{"cesium":"^1.111.0"},"devDependencies":{"@rollup/plugin-commonjs":"^22.0.2","@rollup/plugin-node-resolve":"^13.3.0","rollup":"^2.79.2"},"_id":"@bimangle/cesium-tool-excavate@1.1.0","_nodeVersion":"24.11.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-+ABAzl6FY2yGWKD12kniHgm6kfYwZzzbMVZIioeDYeprPu9bVo02EhOYslMJF/X0V1nQ8QKjrom/PLcVHkXRTA==","shasum":"ac7904eb8b3dc2dd62abf4fb5013252d064f9523","tarball":"https://registry.npmjs.org/@bimangle/cesium-tool-excavate/-/cesium-tool-excavate-1.1.0.tgz","fileCount":5,"unpackedSize":109157,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCJmGo+GKlaMvYN4VY+jVkUxV+jmmXt34jaVeQ0u4KdvAIhAKkaT+idKaKVoZfXwsMQDTkf3QFEYV4lAy7gZHq6RcCS"}]},"_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-excavate_1.1.0_1785480778679_0.0614875468105196"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-27T08:12:52.001Z","modified":"2026-07-31T06:52:58.992Z","1.0.0":"2026-07-27T08:12:52.279Z","1.1.0":"2026-07-31T06:52:58.828Z"},"author":{"name":"BimAngle"},"license":"MIT","keywords":["cesium","terrain","excavate","clipping","polygon","bimangle"],"description":"A Cesium plugin providing multi-mode terrain excavation tools (rectangle drag and precise polygon).","maintainers":[{"name":"bimangle.liu","email":"liuyongsheng@msn.com"}],"readme":"# @bimangle/cesium-tool-excavate\n\nA Cesium plugin providing multi-mode terrain excavation (pit-digging) tools.\n\n一款 Cesium 地形挖坑插件，支持矩形拉框与精确多点两种绘制模式。\n\n---\n\n## Features / 特性\n\n- 🟥 **Rectangle mode** — click the first corner, preview the rectangle in real time, click the opposite corner to confirm.  \n  **矩形拉框模式** — 单击第一个角点后移动鼠标实时预览矩形，再次单击对角点完成挖坑。\n\n- 🔷 **Polygon mode** — click to place vertices one by one; double-click or right-click to close the polygon.  \n  **精确多点模式** — 逐点单击添加顶点，双击或右键完成任意形状多边形挖坑。\n\n- 🌍 **Terrain clipping** — uses `Globe.clippingPolygons` (Cesium ≥ 1.111) with automatic fallback to `Globe.clippingPlanes` for older versions.  \n  **地形裁剪** — 优先使用 `Globe.clippingPolygons`（Cesium ≥ 1.111），低版本自动降级至 `Globe.clippingPlanes`。\n\n- 🟫 **Pit visualization** — opaque dark-brown floor plane and terrain-hugging wall rendered via `PolygonGraphics` + `WallGraphics`.  \n  **坑体可视化** — 不透明深棕色坑底平面（`PolygonGraphics`）+ 贴地坑壁（`WallGraphics`）。\n\n- 📏 **Depth presets** — one-click 5 / 10 / 20 / 50 m presets plus a custom numeric input.  \n  **深度预设** — 面板提供 5 / 10 / 20 / 50 m 快速按钮及自定义输入框。\n\n- 👁 **See-through toggle** — enable `Globe.translucency` to look through the terrain and locate underground models before drawing.  \n  **地面透视开关** — 启用 `Globe.translucency`，在绘制前透过地面查看地下管线/基坑等模型。\n\n- 🗑 **Clear all** — remove every pit and restore the terrain in one click.  \n  **一键清除** — 单击清除所有挖坑并还原地形裁剪。\n\n- 🌐 **Multilingual UI** — automatically selects the display language based on `navigator.language`; defaults to English when the language is not recognized.  \n  **多语言界面** — 根据 `navigator.language` 自动选择显示语言，未识别时降级为英文。\n\n---\n\n## Installation / 安装\n\n```bash\nnpm install @bimangle/cesium-tool-excavate\n```\n\nOr reference the IIFE build directly:  \n或直接引用 IIFE 构建产物：\n\n```html\n<script src=\"dist/cesium-tool-excavate.js\"></script>\n```\n\n---\n\n## Quick Start / 快速开始\n\n```js\n// One line — CesiumUIMixin is initialised automatically.\n// 一行接入，CesiumUIMixin 会自动初始化。\nviewer.extend(ToolExcavateMixin);\n```\n\nOr with options:  \n或带配置项：\n\n```js\nToolExcavateMixin(viewer, {\n  mode:  'rect',   // Initial drawing mode / 初始绘制模式: 'rect' | 'precise'\n  depth: 10,       // Initial depth in metres / 初始坑深（米）\n  onExcavated:  (id, positions, bottomHeight) => { /* ... */ },\n  onClearedAll: () => { /* ... */ },\n});\n```\n\n---\n\n## Usage / 使用方式\n\n1. Click **Rectangle** or **Polygon** in the panel to activate a drawing mode.  \n   在面板中点击 **矩形拉框** 或 **精确多点** 激活绘制模式。\n\n2. Click on the terrain to start drawing.  \n   在地形上单击开始绘制。\n\n3. For rectangle: click the first corner, move the mouse to preview, click the opposite corner to finish.  \n   矩形模式：单击第一个角点，移动鼠标预览，单击对角点完成。\n\n4. For polygon: click to add vertices (≥ 3), then double-click or right-click to close.  \n   多点模式：逐点单击添加顶点（≥ 3 个），双击或右键完成。\n\n5. Set the desired depth via the preset buttons or the custom input.  \n   通过预设按钮或自定义输入框设定坑深。\n\n6. Optionally toggle **See-Through** before drawing to locate underground objects.  \n   可在绘制前开启 **地面透视** 查看地下对象。\n\n7. Click **Clear All Pits** to remove all excavations.  \n   单击 **清除所有挖坑** 移除全部挖坑。\n\n### Keyboard Shortcuts / 键盘快捷键\n\n| Key / 按键 | Effect / 效果 |\n|-----------|--------------|\n| `Esc` | Cancel current drawing / 取消当前绘制 |\n| Right-click / 右键 | Finish polygon (≥ 3 pts) or cancel / 完成多边形（≥ 3 点）或取消 |\n\n---\n\n## API Reference\n\n### `ToolExcavateMixin(viewer, options?)`\n\nMounts the excavation tool on the viewer.  \n将挖坑工具挂载到 viewer。\n\n| Property / 属性 | Type / 类型 | Default / 默认 | Description / 说明 |\n|----------------|------------|---------------|-------------------|\n| `mode` | `string` | `'rect'` | Initial drawing mode: `'rect'` or `'precise'` / 初始绘制模式 |\n| `depth` | `number` | `10` | Initial pit depth in metres / 初始坑深（米） |\n| `onExcavated` | `Function` | `null` | `(pitId, positions, bottomHeight)` callback / 挖坑完成回调 |\n| `onClearedAll` | `Function` | `null` | Called when all pits are cleared / 清除全部回调 |\n| `uiOptions` | `object` | `undefined` | Options forwarded to `CesiumUIMixin` / 传给 CesiumUIMixin 的配置 |\n\n### `ToolExcavateUnmount(viewer)`\n\nUnmounts and destroys the tool, restoring globe state.  \n卸载并销毁工具，还原 Globe 状态。\n\n### `viewer.toolExcavate`\n\nThe bound `ExcavateTool` instance.  \n绑定到 viewer 的 `ExcavateTool` 实例。\n\n#### `ExcavateTool` Methods / 方法\n\n| Method / 方法 | Description / 说明 |\n|--------------|-------------------|\n| `toggleTranslucency()` | Toggle globe see-through mode / 切换地面透视 |\n| `removeAll()` | Remove all pits and clipping / 清除所有挖坑 |\n| `destroy()` | Fully unmount the tool / 完整卸载工具 |\n\n---\n\n## Technical Notes / 技术说明\n\n- The tool uses `Globe.clippingPolygons` (Cesium ≥ 1.111) for the primary clipping path.  \n  工具优先使用 `Globe.clippingPolygons`（Cesium ≥ 1.111）进行裁剪。\n\n- For Cesium < 1.111, it automatically falls back to `Globe.clippingPlanes` (4-plane mode).  \n  低版本 Cesium 自动降级为 `Globe.clippingPlanes`（4 平面模式），精确多点模式仅支持凸多边形。\n\n- Floor height is computed by sampling the terrain at a 5×5 grid; the minimum point minus `depth` is used.  \n  坑底高程通过 5×5 网格采样地形取最低点减 `depth` 计算，离线时降级为顶点平均高程。\n\n- Maximum concurrent pits: 20. Exceeding this limit is silently ignored until some are cleared.  \n  最大并发坑数为 20，超限后静默忽略新挖坑请求，直到用户清除部分坑。\n\n- Globe translucency is restored automatically when `destroy()` is called.  \n  调用 `destroy()` 时会自动还原 Globe 透明度，避免副作用遗留。\n\n---\n\n## Changelog / 更新记录\n\n### v1.1.0\n- Rectangle mode now aligns with the camera viewport axes instead of geographic axes.  \n  矩形拉框模式改为沿当前视角水平/垂直方向对齐，而非地理坐标轴方向。\n\n### v1.0.0\n- Rectangle drag mode and precise polygon mode.  \n  矩形拉框模式与精确多点模式。\n- `ClippingPolygon` / `ClippingPlanes` dual-track support.  \n  `ClippingPolygon` / `ClippingPlanes` 双轨兼容。\n- Pit floor + wall visualization, depth presets, see-through toggle, clear-all.  \n  坑底坑壁可视化、深度预设、地面透视、一键清除。\n- Bilingual UI (Simplified Chinese / English).  \n  简体中文 / 英文双语界面。\n","readmeFilename":"README.md"}