@metagl/sdk-plotting 0.0.2 → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +275 -86
  2. package/lacdt.plotting.d.ts +2 -2
  3. package/lacdt.plotting.js +1 -1
  4. package/package.json +1 -1
  5. package/types/Models/AnimationConfig.d.ts +1 -1
package/README.md CHANGED
@@ -1,86 +1,275 @@
1
- # geovisearthsdk_web - plotting 模块 README
2
-
3
- ## 简介
4
- plotting 模块为 GeovisEarth Web SDK 提供矢量绘制、标注与图形交互的封装组件，便于在地图上创建、编辑与管理点、线、面、标注等图形要素。
5
-
6
- ## 主要功能
7
- - 创建点、线、面、文本标注、图标等要素
8
- - 支持要素样式配置（颜色、宽度、图标、透明度等）
9
- - 要素编辑（拖拽、顶点编辑、删除）
10
- - 支持要素分组与图层管理
11
- - 事件绑定（点击、悬停、编辑开始/结束等）
12
- - 批量导入/导出 GeoJSON
13
-
14
- ## 快速开始
15
-
16
- 安装（npm）
17
- ```bash
18
- npm install @metagl/sdk-plotting
19
- ```
20
-
21
- 浏览器引入（UMD）
22
- ```html
23
- <script src="path/to/sdk-plotting.js"></script>
24
- ```
25
-
26
- 初始化并创建一个点
27
- ```js
28
- import { Plotting } from '@metagl/sdk-plotting';
29
-
30
- const map = new GeoMap({ container: 'map' });
31
- const plotting = new Plotting({ map });
32
-
33
- const marker = plotting.createPoint({
34
- position: [116.397389, 39.908860],
35
- style: { color: '#ff0000', size: 12 }
36
- });
37
- plotting.add(marker);
38
- ```
39
-
40
- ## 基本 API（概览）
41
- - Plotting(options)
42
- - map: 地图实例
43
- - zIndex, defaultStyle 等
44
- - createPoint({ position, style })
45
- - createLine({ positions, style })
46
- - createPolygon({ positions, style })
47
- - createLabel({ position, text, style })
48
- - add(feature) / remove(feature) / clear()
49
- - edit(feature) / stopEdit()
50
- - toGeoJSON() / fromGeoJSON(geojson)
51
- - on(event, handler) / off(event, handler)
52
-
53
- 常见事件：'click'、'dblclick'、'pointermove'、'editstart'、'editend'、'create'
54
-
55
- ## 配置示例
56
- ```js
57
- const plotting = new Plotting({
58
- map,
59
- defaultStyle: {
60
- point: { color: '#3388ff', size: 8 },
61
- line: { color: '#33aa33', width: 3 },
62
- polygon: { fillColor: 'rgba(51,136,255,0.2)', strokeColor: '#3388ff' }
63
- }
64
- });
65
- ```
66
-
67
- ## 编辑与交互
68
- - 通过 plotting.edit(feature) 启动编辑模式
69
- - 支持拖动顶点、添加/删除顶点
70
- - 编辑完成触发 'editend' 事件，可获取最新 GeoJSON
71
-
72
- ## 导入/导出
73
- ```js
74
- const geojson = plotting.toGeoJSON();
75
- plotting.fromGeoJSON(geojson);
76
- ```
77
-
78
- ## 常见问题
79
- - 要素不可见：检查图层可见性及样式透明度、地图投影设置
80
- - 编辑失败：确保 feature 已添加到 plotting 管理器并传入正确坐标格式
81
-
82
- ## 贡献
83
- 欢迎提交 issue 与 PR。请遵守项目代码风格并补充单元测试。
84
-
85
- ## 许可证
86
- ISC
1
+ # @metagl/sdk-plotting
2
+
3
+ GeovisEarth SDK Plotting 模块，为 GeovisEarth Web SDK 提供矢量绘制、标注与图形交互的封装组件，支持在 Cesium 地图上创建、编辑与管理点、线、面、标注等图形要素。
4
+
5
+ ## 两种使用方式
6
+
7
+ ### 方式一：HTML script 标签引入（UMD 方式）
8
+
9
+ 适用于传统 HTML 页面，通过 `<script>` 标签直接引入，通过全局变量 `LACDT` 访问 API。
10
+
11
+ **前置依赖：** 需先引入 Cesium。
12
+
13
+ ```html
14
+ <!DOCTYPE html>
15
+ <html lang="zh">
16
+ <head>
17
+ <meta charset="utf-8" />
18
+ <!-- 1. 引入 Cesium -->
19
+ <link href="https://io-qos.geovisearth.com/getfile/46/brainsim-cdn/open/cesiumjs/1.136/Widgets/widgets.css" rel="stylesheet">
20
+ <script src="https://io-qos.geovisearth.com/getfile/46/brainsim-cdn/open/cesiumjs/1.136/Cesium.js"></script>
21
+
22
+ <!-- 2. 引入 sdk-plotting（线上 CDN 或本地文件） -->
23
+ <script src="https://io-qos.geovisearth.com/getfile/46/brainsim-cdn/open/sdk/lacdt.plotting.js"></script>
24
+ <!-- 本地引入：<script src="./lib/lacdt.plotting.js"></script> -->
25
+ </head>
26
+ <body>
27
+ <div id="cesiumContainer" style="width:100%;height:100%"></div>
28
+
29
+ <script>
30
+ // 初始化 Cesium
31
+ const viewer = new Cesium.Viewer('cesiumContainer');
32
+
33
+ // 3. 通过全局对象 LACDT 使用 plotting
34
+ const plotting = new LACDT.Plotting({ viewer });
35
+
36
+ // 使用 API 创建要素
37
+ const point = plotting.createPoint({
38
+ position: [116.397389, 39.908860]
39
+ });
40
+ plotting.add(point);
41
+ </script>
42
+ </body>
43
+ </html>
44
+ ```
45
+
46
+ **资源文件说明：** 打包产物中 `resources/` 目录包含图片、纹理等静态资源，需与 JS 文件保持相对路径关系。如果自定义了部署路径，需确保 `resources/` 目录可被访问。
47
+
48
+ ---
49
+
50
+ ### 方式二：npm import 引入（ESM 方式）
51
+
52
+ 适用于 Vue/Vite/Webpack 等现代前端工程化项目，通过 ES Module 动态导入。
53
+
54
+ #### 1. 安装
55
+
56
+ ```bash
57
+ # npm 官方源
58
+ npm install @metagl/sdk-plotting
59
+
60
+ # 或本地 file 引用（开发调试阶段）
61
+ npm install @metagl/sdk-plotting@file:../../sdk-plotting/publish
62
+ ```
63
+
64
+ #### 2. Vite 项目配置要点
65
+
66
+ ##### 2.1 Cesium 别名映射 + 排除预打包
67
+
68
+ sdk-plotting 打包时将 Cesium 标记为 external（全局变量 `Cesium`）。Vite 预打包时需要做两件事：
69
+ - 将 `Cesium` 别名指向**浏览器 ESM 构建**（不能用 `cesium` 包名，否则会解析到 `index.cjs` Node.js 入口，导致 `__dirname is not defined` 错误）
70
+ - 将 `@metagl/sdk-plotting` 排除预打包（避免 Vite 重新解析已打包好的 UMD 内部依赖）
71
+
72
+ ```js
73
+ // vite.config.js
74
+ import { defineConfig } from 'vite'
75
+ import path from 'path'
76
+
77
+ export default defineConfig({
78
+ resolve: {
79
+ alias: {
80
+ // 关键：必须指向浏览器 ESM 入口，不能用 'cesium'（会解析到 Node.js 的 index.cjs）
81
+ 'Cesium': path.resolve(__dirname, 'node_modules/cesium/Source/Cesium.js'),
82
+ }
83
+ },
84
+ define: {
85
+ // Cesium 静态资源路径
86
+ CESIUM_BASE_URL: JSON.stringify('/cesium')
87
+ },
88
+ optimizeDeps: {
89
+ include: ['cesium'],
90
+ // 关键：排除已打包的 UMD 包，避免 Vite 重新解析其内部依赖
91
+ exclude: ['@metagl/sdk-plotting']
92
+ }
93
+ })
94
+ ```
95
+
96
+ > **为什么不能写 `'Cesium': 'cesium'`？**
97
+ > Vite 按包名解析 `cesium` 时会读取 `package.json` 的 `main` 字段，指向 `index.cjs`——这是一个 Node.js CommonJS 入口，包含 `__dirname`、`path.join` 等浏览器不可用的 API。运行时会报 `ReferenceError: __dirname is not defined`。必须直接指向 `Source/Cesium.js` 浏览器构建。
98
+
99
+ ##### 2.2 静态资源拷贝
100
+
101
+ sdk-plotting 的 `resources/` 目录（图片、纹理等）需要通过 `vite-plugin-static-copy` 或其他方式复制到构建输出：
102
+
103
+ ```js
104
+ // vite.config.js
105
+ import { viteStaticCopy } from 'vite-plugin-static-copy'
106
+
107
+ export default defineConfig({
108
+ plugins: [
109
+ viteStaticCopy({
110
+ targets: [
111
+ // Cesium 静态资源
112
+ {
113
+ src: 'node_modules/cesium/Build/Cesium/*',
114
+ dest: 'cesium'
115
+ },
116
+ // sdk-plotting 资源
117
+ {
118
+ src: 'node_modules/@metagl/sdk-plotting/resources',
119
+ dest: 'resources'
120
+ }
121
+ ]
122
+ })
123
+ ],
124
+ // 如果代码中通过 /lib/resources 路径请求资源，配置代理
125
+ server: {
126
+ proxy: {
127
+ '/lib/resources': {
128
+ target: 'http://localhost:9521',
129
+ changeOrigin: true,
130
+ rewrite: (path) => path.replace('/lib/resources', '/resources')
131
+ }
132
+ }
133
+ }
134
+ })
135
+ ```
136
+
137
+ ##### 2.3 入口文件加载
138
+
139
+ UMD 格式需要通过动态 import 加载，并在加载后将全局变量 `LACDT` 和 `window.Cesium` 暴露出来：
140
+
141
+ ```js
142
+ // main.js
143
+ import { createApp } from 'vue'
144
+ import App from './App.vue'
145
+
146
+ // 解冻 Cesium（使 sdk-plotting 能扩展 Cesium 对象）
147
+ function makeExtensible(obj) {
148
+ const newObj = Object.create(Object.getPrototypeOf(obj))
149
+ Object.getOwnPropertyNames(obj).forEach(key => {
150
+ const descriptor = Object.getOwnPropertyDescriptor(obj, key)
151
+ if (descriptor) {
152
+ Object.defineProperty(newObj, key, {
153
+ ...descriptor,
154
+ configurable: true,
155
+ writable: true
156
+ })
157
+ }
158
+ })
159
+ return newObj
160
+ }
161
+
162
+ async function bootstrap() {
163
+ // 1. 加载 Cesium
164
+ const CesiumModule = await import('cesium')
165
+ let cesium = CesiumModule.default || CesiumModule
166
+ cesium = makeExtensible(cesium)
167
+ window.Cesium = cesium
168
+
169
+ // 2. 加载 sdk-plotting（动态 import）
170
+ await import('@metagl/sdk-plotting')
171
+
172
+ // 3. 此时 LACDT 全局对象已就绪
173
+ const app = createApp(App)
174
+ app.config.globalProperties.$metaGL = window.LACDT
175
+ app.config.globalProperties.$cesium = window.Cesium
176
+ app.mount('#app')
177
+ }
178
+
179
+ bootstrap()
180
+ ```
181
+
182
+ #### 3. Webpack 项目配置要点
183
+
184
+ Webpack 项目需配置 Cesium 为 external：
185
+
186
+ ```js
187
+ // webpack.config.js
188
+ module.exports = {
189
+ externals: {
190
+ cesium: 'Cesium'
191
+ }
192
+ }
193
+ ```
194
+
195
+ ---
196
+
197
+ ## 主要功能
198
+
199
+ - 创建点、线、面、文本标注、图标等要素
200
+ - 支持要素样式配置（颜色、宽度、图标、透明度等）
201
+ - 要素编辑（拖拽、顶点编辑、删除）
202
+ - 支持要素分组与图层管理
203
+ - 事件绑定（点击、悬停、编辑开始/结束等）
204
+ - 批量导入/导出 GeoJSON
205
+ - 军事标会、箭头、扇形、椭圆等多种军事图形
206
+ - 热力图、OD 线、三维体（立方体、圆柱体）等分析效果
207
+
208
+ ## 快速开始
209
+
210
+ 初始化并创建一个点：
211
+
212
+ ```js
213
+ // UMD 方式
214
+ const plotting = new LACDT.Plotting({ viewer });
215
+
216
+ // npm import 方式
217
+ import { Plotting } from '@metagl/sdk-plotting';
218
+ const plotting = new Plotting({ viewer });
219
+
220
+ // 创建点
221
+ const marker = plotting.createPoint({
222
+ position: [116.397389, 39.908860],
223
+ style: { color: '#ff0000', size: 12 }
224
+ });
225
+ plotting.add(marker);
226
+ ```
227
+
228
+ ## 基本 API（概览）
229
+
230
+ - **Plotting(options)**
231
+ - `viewer`: Cesium Viewer 实例
232
+ - `zIndex`, `defaultStyle` 等
233
+ - **createPoint**({ position, style })
234
+ - **createLine**({ positions, style })
235
+ - **createPolygon**({ positions, style })
236
+ - **createLabel**({ position, text, style })
237
+ - **add**(feature) / **remove**(feature) / **clear**()
238
+ - **edit**(feature) / **stopEdit**()
239
+ - **toGeoJSON**() / **fromGeoJSON**(geojson)
240
+ - **on**(event, handler) / **off**(event, handler)
241
+
242
+ 常见事件：`click`、`dblclick`、`pointermove`、`editstart`、`editend`、`create`
243
+
244
+ ## 构建
245
+
246
+ ```bash
247
+ npm run build # webpack 生产构建
248
+ npm run build:rollup # rollup 构建
249
+ npm run build:dts # 生成类型声明文件
250
+ ```
251
+
252
+ 构建产物输出到 `lib/` 目录，`npm run build` 会自动将产物复制到 `publish/` 目录。
253
+
254
+ ## 发布
255
+
256
+ ```bash
257
+ npm run login # 登录 npm
258
+ cd publish && npm publish --access public # 发布
259
+ ```
260
+
261
+ ## 常见问题
262
+
263
+ ### UMD 方式
264
+ - **资源 404**：确保 `resources/` 目录与 `lacdt.plotting.js` 保持正确的相对路径
265
+ - **LACDT 未定义**：确保 `lacdt.plotting.js` 在 Cesium 之后加载
266
+
267
+ ### npm import 方式
268
+ - **`__dirname is not defined`**：Cesium 别名不能写 `'cesium'`（会解析到 Node.js `index.cjs`），必须指向 `Source/Cesium.js` 浏览器入口
269
+ - **白屏无报错**：Vite 缓存了旧依赖路径，需删除 `node_modules/.vite/` 后重启（从 `file:` 引用切换到 npm 版本时必做）
270
+ - **Cannot assign to "e" because it is a constant**：构建产物问题，需重新 `npm run build`
271
+ - **SDK 无法扩展 Cesium**：UMD 格式的 SDK 会扩展 `window.Cesium`，需在 import 之前确保 Cesium 已挂载到 `window`，且对象未被 `Object.freeze()`
272
+
273
+ ## 许可证
274
+
275
+ ISC
package/lacdt.plotting.d.ts CHANGED
@@ -3589,7 +3589,7 @@ class Tools {
3589
3589
  }
3590
3590
 
3591
3591
  class AnimationConfig {
3592
- 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)[];
3592
+ 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)[];
3593
3593
  static animationList: Array<AnimationItem>;
3594
3594
  static init(): void;
3595
3595
  }
@@ -18705,7 +18705,7 @@ class Tools {
18705
18705
  }
18706
18706
 
18707
18707
  class AnimationConfig {
18708
- 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)[];
18708
+ 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)[];
18709
18709
  static animationList: Array<AnimationItem>;
18710
18710
  static init(): void;
18711
18711
  }