@metagl/sdk-plotting 0.0.3 → 0.0.5

package/README.md

@@ -27,17 +27,27 @@ GeovisEarth SDK Plotting 模块，为 GeovisEarth Web SDK 提供矢量绘制、
   <div id="cesiumContainer" style="width:100%;height:100%"></div>
 
   <script>
-    // 初始化 Cesium
-    const viewer = new Cesium.Viewer('cesiumContainer');
-
-    // 3. 通过全局对象 LACDT 使用 plotting
-    const plotting = new LACDT.Plotting({ viewer });
-
-    // 使用 API 创建要素
-    const point = plotting.createPoint({
-      position: [116.397389, 39.908860]
-    });
-    plotting.add(point);
+    // 1. 初始化引擎（自动创建 Cesium Viewer 并挂载到 LACDT）
+    const engine = new LACDT.Engine('cesiumContainer');
+
+    // 2. 方式 A：createPlot 交互绘制
+    engine.plot.createPlot({}, '基本元素', '点', '图标点');
+
+    // 3. 方式 B：graphicLayer API 直接创建
+    const point = {
+      gvolObject: {
+        gvolType: 'EditorPoint',
+        properties: {
+          color: '#FF0000',
+          pixelSize: 20,
+          LabelName: '点'
+        },
+        geometry: {
+          coordinates: [116.397389, 39.908860]
+        }
+      }
+    };
+    engine.graphicLayer.add(point);
   </script>
 </body>
 </html>
@@ -63,9 +73,11 @@ npm install @metagl/sdk-plotting@file:../../sdk-plotting/publish
 
 #### 2. Vite 项目配置要点
 
-##### 2.1 Cesium 别名映射
+##### 2.1 Cesium 别名映射 + 排除预打包
 
-sdk-plotting 打包时将 Cesium 标记为 external（全局变量 `Cesium`），但 Vite 按模块名解析时需要映射：
+sdk-plotting 打包时将 Cesium 标记为 external（全局变量 `Cesium`）。Vite 预打包时需要做两件事：
+- 将 `Cesium` 别名指向**浏览器 ESM 构建**（不能用 `cesium` 包名，否则会解析到 `index.cjs` Node.js 入口，导致 `__dirname is not defined` 错误）
+- 将 `@metagl/sdk-plotting` 排除预打包（避免 Vite 重新解析已打包好的 UMD 内部依赖）
 
 ```js
 // vite.config.js
@@ -75,8 +87,8 @@ import path from 'path'
 export default defineConfig({
   resolve: {
     alias: {
-      // 关键：将 UMD external 的 'Cesium' 映射到 npm 包名 'cesium'
-      'Cesium': 'cesium',
+      // 关键：必须指向浏览器 ESM 入口，不能用 'cesium'（会解析到 Node.js 的 index.cjs）
+      'Cesium': path.resolve(__dirname, 'node_modules/cesium/Source/Cesium.js'),
     }
   },
   define: {
@@ -84,11 +96,16 @@ export default defineConfig({
     CESIUM_BASE_URL: JSON.stringify('/cesium')
   },
   optimizeDeps: {
-    include: ['cesium']
+    include: ['cesium'],
+    // 关键：排除已打包的 UMD 包，避免 Vite 重新解析其内部依赖
+    exclude: ['@metagl/sdk-plotting']
   }
 })
 ```
 
+> **为什么不能写 `'Cesium': 'cesium'`？**
+> Vite 按包名解析 `cesium` 时会读取 `package.json` 的 `main` 字段，指向 `index.cjs`——这是一个 Node.js CommonJS 入口，包含 `__dirname`、`path.join` 等浏览器不可用的 API。运行时会报 `ReferenceError: __dirname is not defined`。必须直接指向 `Source/Cesium.js` 浏览器构建。
+
 ##### 2.2 静态资源拷贝
 
 sdk-plotting 的 `resources/` 目录（图片、纹理等）需要通过 `vite-plugin-static-copy` 或其他方式复制到构建输出：
@@ -200,39 +217,203 @@ module.exports = {
 
 ## 快速开始
 
-初始化并创建一个点：
+### 初始化引擎
 
 ```js
 // UMD 方式
-const plotting = new LACDT.Plotting({ viewer });
+const engine = new LACDT.Engine('cesiumContainer');
 
 // npm import 方式
-import { Plotting } from '@metagl/sdk-plotting';
-const plotting = new Plotting({ viewer });
+import { Engine } from '@metagl/sdk-plotting';
+const engine = new Engine('cesiumContainer');
+```
+
+### 创建标绘元素的两种方式
+
+#### 方式 A：`createPlot` 交互绘制（按分类选择）
+
+通过 `engine.plot.createPlot()` 按分类树选择图形类型，支持鼠标在地图上交互绘制。
+
+```js
+// 示例 1：按分类选择类型，鼠标交互绘制
+engine.plot.createPlot({}, '基本元素', '点', '图标点');
+engine.plot.createPlot({}, '基本元素', '线', '直线');
+engine.plot.createPlot({}, '基本元素', '面', '多边形');
+
+// 示例 2：带自定义样式参数
+engine.plot.createPlot({
+  gvolType: 'Ellipsoid',
+  properties: {
+    color: '#FF0000',
+    radius: 100
+  },
+  geometry: {
+    coordinates: [86, 30]
+  }
+});
+
+// 示例 3：带分类 + 自定义样式
+engine.plot.createPlot({
+  properties: { color: '#00FF00' }
+}, '基本元素', '箭头', '双箭头');
+```
+
+**分类树结构（一级 / 二级 / 三级）：**
+
+| 一级分类 | 二级分类 | 三级分类 |
+|---|---|---|
+| 基本元素 | 点 | 图标点 |
+| | 线 | 直线、曲线、流动线、箭头线、航线 |
+| | 面 | 多边形、矩形、圆形 |
+| | 文字 | 标签文字、路径文字、贴地文字、富文本 |
+| | 箭头 | 双箭头、集结地、进攻方向、进攻方向尾、分队战斗行动、分队战斗行动尾、粗单直箭头、粗单尖头箭头、细直箭头 |
+| | 其它 | 立方体、动态波、雷达 |
+| | 粒子 | 烟特效、爆炸、喷泉 |
+| 图片 | — | 各种图片标注 |
+| 模型 | — | 各种 3D 模型 |
+
+#### 方式 B：`engine.graphicLayer.add()` API 直接创建
+
+通过 JSON 参数直接创建标绘元素，代码精确控制样式和位置，无需交互。
+
+```js
+// 示例 1：创建点
+const point = {
+  gvolObject: {
+    gvolType: 'EditorPoint',
+    properties: {
+      color: '#FF0000',
+      pixelSize: 20,
+      outlineShow: true,
+      outlineWidth: 2,
+      outlineColor: '#FFFFFF',
+      LabelName: '点'
+    },
+    geometry: {
+      coordinates: [86, 30]  // [经度, 纬度]
+    }
+  }
+};
+const result = engine.graphicLayer.add(point);
+
+// 示例 2：创建线
+const line = {
+  gvolObject: {
+    gvolType: 'EditorPolyline',
+    properties: {
+      color: '#3388ff',
+      width: 3,
+      LabelName: '线'
+    },
+    geometry: {
+      coordinates: [
+        [116.39, 39.90],
+        [116.40, 39.91],
+        [116.41, 39.90]
+      ]
+    }
+  }
+};
+engine.graphicLayer.add(line);
+
+// 示例 3：创建多边形
+const polygon = {
+  gvolObject: {
+    gvolType: 'EditorPolygon',
+    properties: {
+      color: '#00FF00',
+      materialType: 'Color',
+      LabelName: '多边形'
+    },
+    geometry: {
+      coordinates: [
+        [116.39, 39.90],
+        [116.40, 39.90],
+        [116.40, 39.91],
+        [116.39, 39.91],
+        [116.39, 39.90]  // 首尾闭合
+      ]
+    }
+  }
+};
+engine.graphicLayer.add(polygon);
+
+// 示例 4：批量创建
+const batchData = [pointData, lineData, polygonData];
+engine.graphicLayer.add(batchData);
+```
+
+**常用 `gvolType` 类型列表：**
 
-// 创建点
-const marker = plotting.createPoint({
-  position: [116.397389, 39.908860],
-  style: { color: '#ff0000', size: 12 }
+| gvolType | 说明 | coordinates 格式 |
+|---|---|---|
+| `EditorPoint` | 图标点 | `[经度, 纬度]` |
+| `EditorText` | 贴地文字 | `[经度, 纬度]` |
+| `EditorPolyline` | 折线 | `[[经度, 纬度], ...]` |
+| `EditorPolygon` | 多边形 | `[[经度, 纬度], ...]` |
+| `EditorCircle` | 圆形 | `[经度, 纬度]` + 半径 |
+| `EditorRectangle` | 矩形 | 对角两点坐标 |
+| `EditorEllipse` | 椭圆 | `[经度, 纬度]` |
+| `EditorSector` | 扇形 | `[经度, 纬度]` |
+| `EditorArrow` | 箭头 | `[[经度, 纬度], ...]` |
+| `EditorCube` | 立方体 | `[经度, 纬度, 高度]` |
+
+## 编辑与交互
+
+```js
+// 开启编辑模式
+engine.plot.open();
+
+// 关闭编辑模式
+engine.plot.close();
+
+// 编辑完成后回调
+engine.plot.onPick((data) => {
+  console.log('编辑变更:', data);
 });
-plotting.add(marker);
 ```
 
-## 基本 API（概览）
+## graphicLayer 常用 API
+
+```js
+// 删除单个对象
+engine.graphicLayer.remove(leaf);
 
-- **Plotting(options)**
-  - `viewer`: Cesium Viewer 实例
-  - `zIndex`, `defaultStyle` 等
-- **createPoint**({ position, style })
-- **createLine**({ positions, style })
-- **createPolygon**({ positions, style })
-- **createLabel**({ position, text, style })
-- **add**(feature) / **remove**(feature) / **clear**()
-- **edit**(feature) / **stopEdit**()
-- **toGeoJSON**() / **fromGeoJSON**(geojson)
-- **on**(event, handler) / **off**(event, handler)
+// 删除所有对象
+engine.graphicLayer.removeAll();
 
-常见事件：`click`、`dblclick`、`pointermove`、`editstart`、`editend`、`create`
+// 导出为 JSON（可用于保存和反序列化）
+const json = engine.graphicLayer.toJson();
+
+// 从 JSON 导入
+engine.graphicLayer.fromJson(json);
+
+// 按 ID 查找
+const obj = engine.graphicLayer.getById('some-guid');
+
+// 按名称查找
+const obj = engine.graphicLayer.getNodeByName('点');
+
+// 屏幕坐标拾取对象
+const obj = engine.graphicLayer.pickByCoordinate(screenX, screenY);
+
+// 获取多边形内的对象
+const items = engine.graphicLayer.getItemsInPolygon(positions);
+```
+
+## 事件监听
+
+```js
+// 监听添加事件（通过 engine.plot）
+engine.plot.on('add', (sceneObject) => {
+  console.log('新对象已添加:', sceneObject);
+});
+
+// 监听删除事件
+engine.plot.on('remove', (gvolObject) => {
+  console.log('对象已删除:', gvolObject);
+});
+```
 
 ## 构建
 
@@ -258,8 +439,9 @@ cd publish && npm publish --access public  # 发布
 - **LACDT 未定义**：确保 `lacdt.plotting.js` 在 Cesium 之后加载
 
 ### npm import 方式
+- **`__dirname is not defined`**：Cesium 别名不能写 `'cesium'`（会解析到 Node.js `index.cjs`），必须指向 `Source/Cesium.js` 浏览器入口
+- **白屏无报错**：Vite 缓存了旧依赖路径，需删除 `node_modules/.vite/` 后重启（从 `file:` 引用切换到 npm 版本时必做）
 - **Cannot assign to "e" because it is a constant**：构建产物问题，需重新 `npm run build`
-- **Cesium could not be resolved**：在 `vite.config.js` 中添加 `'Cesium': 'cesium'` 别名
 - **SDK 无法扩展 Cesium**：UMD 格式的 SDK 会扩展 `window.Cesium`，需在 import 之前确保 Cesium 已挂载到 `window`，且对象未被 `Object.freeze()`
 
 ## 许可证

package/lacdt.plotting.d.ts

@@ -3589,7 +3589,7 @@ class Tools {
 }
 
   class AnimationConfig {
-    static animationRegister: (typeof SingleAnimation | typeof StateChangeAnimation | typeof CssNumberAnimation | typeof CssPropChangeAnimation | typeof SubtitleAnimation | typeof CameraSetAnimation | typeof GeojsonVisibleAnimation | typeof PopulationTimeAnimation | typeof CssMaskAnimation | typeof PathAnimation | typeof CameraRoamAnimation | typeof PageShowAnimation | typeof GxModelAnimation | typeof PathShowAnimation | typeof FollowAnimation | typeof SurroundAnimation | typeof SpiralAnimation | typeof ArrowDirectAnimation | typeof VideoAnimation | typeof AudioAnimation | typeof AutoRotationAnimation | typeof ZoomToFlyAnimation | typeof PolygonMaskAnimation)[];
+    static animationRegister: (typeof SingleAnimation | typeof CameraSetAnimation | typeof StateChangeAnimation | typeof CssNumberAnimation | typeof CssPropChangeAnimation | typeof SubtitleAnimation | typeof GeojsonVisibleAnimation | typeof PopulationTimeAnimation | typeof CssMaskAnimation | typeof PathAnimation | typeof CameraRoamAnimation | typeof PageShowAnimation | typeof GxModelAnimation | typeof PathShowAnimation | typeof FollowAnimation | typeof SurroundAnimation | typeof SpiralAnimation | typeof ArrowDirectAnimation | typeof VideoAnimation | typeof AudioAnimation | typeof AutoRotationAnimation | typeof ZoomToFlyAnimation | typeof PolygonMaskAnimation)[];
     static animationList: Array<AnimationItem>;
     static init(): void;
 }
@@ -18705,7 +18705,7 @@ class Tools {
 }
 
   class AnimationConfig {
-    static animationRegister: (typeof SingleAnimation | typeof StateChangeAnimation | typeof CssNumberAnimation | typeof CssPropChangeAnimation | typeof SubtitleAnimation | typeof CameraSetAnimation | typeof GeojsonVisibleAnimation | typeof PopulationTimeAnimation | typeof CssMaskAnimation | typeof PathAnimation | typeof CameraRoamAnimation | typeof PageShowAnimation | typeof GxModelAnimation | typeof PathShowAnimation | typeof FollowAnimation | typeof SurroundAnimation | typeof SpiralAnimation | typeof ArrowDirectAnimation | typeof VideoAnimation | typeof AudioAnimation | typeof AutoRotationAnimation | typeof ZoomToFlyAnimation | typeof PolygonMaskAnimation)[];
+    static animationRegister: (typeof SingleAnimation | typeof CameraSetAnimation | typeof StateChangeAnimation | typeof CssNumberAnimation | typeof CssPropChangeAnimation | typeof SubtitleAnimation | typeof GeojsonVisibleAnimation | typeof PopulationTimeAnimation | typeof CssMaskAnimation | typeof PathAnimation | typeof CameraRoamAnimation | typeof PageShowAnimation | typeof GxModelAnimation | typeof PathShowAnimation | typeof FollowAnimation | typeof SurroundAnimation | typeof SpiralAnimation | typeof ArrowDirectAnimation | typeof VideoAnimation | typeof AudioAnimation | typeof AutoRotationAnimation | typeof ZoomToFlyAnimation | typeof PolygonMaskAnimation)[];
     static animationList: Array<AnimationItem>;
     static init(): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metagl/sdk-plotting",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Geovis Earth SDK Plotting Module",
   "main": "./lacdt.plotting.js",
   "module": "./lacdt.plotting.js",

package/types/Models/AnimationConfig.d.ts

@@ -23,7 +23,7 @@ import { AutoRotationAnimation } from '../PlottingTool/Animation/Items/AutoRotat
 import { ZoomToFlyAnimation } from '../PlottingTool/Animation/Items/ZoomToFlyAnimation';
 import { PolygonMaskAnimation } from '../PlottingTool/Animation/Items/PolygonMaskAnimation';
 export declare class AnimationConfig {
-    static animationRegister: (typeof SingleAnimation | typeof StateChangeAnimation | typeof CssNumberAnimation | typeof CssPropChangeAnimation | typeof SubtitleAnimation | typeof CameraSetAnimation | typeof GeojsonVisibleAnimation | typeof PopulationTimeAnimation | typeof CssMaskAnimation | typeof PathAnimation | typeof CameraRoamAnimation | typeof PageShowAnimation | typeof GxModelAnimation | typeof PathShowAnimation | typeof FollowAnimation | typeof SurroundAnimation | typeof SpiralAnimation | typeof ArrowDirectAnimation | typeof VideoAnimation | typeof AudioAnimation | typeof AutoRotationAnimation | typeof ZoomToFlyAnimation | typeof PolygonMaskAnimation)[];
+    static animationRegister: (typeof SingleAnimation | typeof CameraSetAnimation | typeof StateChangeAnimation | typeof CssNumberAnimation | typeof CssPropChangeAnimation | typeof SubtitleAnimation | typeof GeojsonVisibleAnimation | typeof PopulationTimeAnimation | typeof CssMaskAnimation | typeof PathAnimation | typeof CameraRoamAnimation | typeof PageShowAnimation | typeof GxModelAnimation | typeof PathShowAnimation | typeof FollowAnimation | typeof SurroundAnimation | typeof SpiralAnimation | typeof ArrowDirectAnimation | typeof VideoAnimation | typeof AudioAnimation | typeof AutoRotationAnimation | typeof ZoomToFlyAnimation | typeof PolygonMaskAnimation)[];
     static animationList: Array<AnimationItem>;
     static init(): void;
 }