@metagl/sdk-plotting 0.0.4 → 0.0.6

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>
@@ -207,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');
+```
+
+### 创建标绘元素的两种方式
 
-// 创建点
-const marker = plotting.createPoint({
-  position: [116.397389, 39.908860],
-  style: { color: '#ff0000', size: 12 }
+#### 方式 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]
+  }
 });
-plotting.add(marker);
+
+// 示例 3：带分类 + 自定义样式
+engine.plot.createPlot({
+  properties: { color: '#00FF00' }
+}, '基本元素', '箭头', '双箭头');
 ```
 
-## 基本 API（概览）
-
-- **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)
-
-常见事件：`click`、`dblclick`、`pointermove`、`editstart`、`editend`、`create`
+**分类树结构（一级 / 二级 / 三级）：**
+
+| 一级分类 | 二级分类 | 三级分类 |
+|---|---|---|
+| 基本元素 | 点 | 图标点 |
+| | 线 | 直线、曲线、流动线、箭头线、航线 |
+| | 面 | 多边形、矩形、圆形 |
+| | 文字 | 标签文字、路径文字、贴地文字、富文本 |
+| | 箭头 | 双箭头、集结地、进攻方向、进攻方向尾、分队战斗行动、分队战斗行动尾、粗单直箭头、粗单尖头箭头、细直箭头 |
+| | 其它 | 立方体、动态波、雷达 |
+| | 粒子 | 烟特效、爆炸、喷泉 |
+| 图片 | — | 各种图片标注 |
+| 模型 | — | 各种 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` 类型列表：**
+
+| 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);
+});
+```
+
+## graphicLayer 常用 API
+
+```js
+// 删除单个对象
+engine.graphicLayer.remove(leaf);
+
+// 删除所有对象
+engine.graphicLayer.removeAll();
+
+// 导出为 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);
+});
+```
 
 ## 构建
 

package/lacdt.plotting.d.ts

@@ -3589,7 +3589,7 @@ class Tools {
 }
 
   class AnimationConfig {
-    static animationRegister: (typeof SingleAnimation | typeof CameraSetAnimation | typeof StateChangeAnimation | typeof CssPropChangeAnimation | typeof SubtitleAnimation | typeof CssNumberAnimation | 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 StateChangeAnimation | typeof CameraSetAnimation | 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 CameraSetAnimation | typeof StateChangeAnimation | typeof CssPropChangeAnimation | typeof SubtitleAnimation | typeof CssNumberAnimation | 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 StateChangeAnimation | typeof CameraSetAnimation | 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;
 }