@metagl/sdk-plotting

v0.0.6

Published

8 days ago

Geovis Earth SDK Plotting Module

0High
0Medium
0Low

asun01

cesium sdk plotting

@metagl/sdk-plotting

GeovisEarth SDK Plotting 模块，为 GeovisEarth Web SDK 提供矢量绘制、标注与图形交互的封装组件，支持在 Cesium 地图上创建、编辑与管理点、线、面、标注等图形要素。

两种使用方式

方式一：HTML script 标签引入（UMD 方式）

适用于传统 HTML 页面，通过 <script> 标签直接引入，通过全局变量 LACDT 访问 API。

前置依赖： 需先引入 Cesium。

<!DOCTYPE html>
<html lang="zh">
<head>
  <meta charset="utf-8" />
  <!-- 1. 引入 Cesium -->
  <link href="https://io-qos.geovisearth.com/getfile/46/brainsim-cdn/open/cesiumjs/1.136/Widgets/widgets.css" rel="stylesheet">
  <script src="https://io-qos.geovisearth.com/getfile/46/brainsim-cdn/open/cesiumjs/1.136/Cesium.js"></script>

  <!-- 2. 引入 sdk-plotting（线上 CDN 或本地文件） -->
  <script src="https://io-qos.geovisearth.com/getfile/46/brainsim-cdn/open/sdk/lacdt.plotting.js"></script>
  <!-- 本地引入：<script src="./lib/lacdt.plotting.js"></script> -->
</head>
<body>
  <div id="cesiumContainer" style="width:100%;height:100%"></div>

  <script>
    // 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>

资源文件说明： 打包产物中 resources/ 目录包含图片、纹理等静态资源，需与 JS 文件保持相对路径关系。如果自定义了部署路径，需确保 resources/ 目录可被访问。

方式二：npm import 引入（ESM 方式）

适用于 Vue/Vite/Webpack 等现代前端工程化项目，通过 ES Module 动态导入。

1. 安装

# npm 官方源
npm install @metagl/sdk-plotting

# 或本地 file 引用（开发调试阶段）
npm install @metagl/sdk-plotting@file:../../sdk-plotting/publish

2. Vite 项目配置要点

2.1 Cesium 别名映射 + 排除预打包

sdk-plotting 打包时将 Cesium 标记为 external（全局变量 Cesium）。Vite 预打包时需要做两件事：

将 Cesium 别名指向浏览器 ESM 构建（不能用 cesium 包名，否则会解析到 index.cjs Node.js 入口，导致 __dirname is not defined 错误）
将 @metagl/sdk-plotting 排除预打包（避免 Vite 重新解析已打包好的 UMD 内部依赖）

// vite.config.js
import { defineConfig } from 'vite'
import path from 'path'

export default defineConfig({
  resolve: {
    alias: {
      // 关键：必须指向浏览器 ESM 入口，不能用 'cesium'（会解析到 Node.js 的 index.cjs）
      'Cesium': path.resolve(__dirname, 'node_modules/cesium/Source/Cesium.js'),
    }
  },
  define: {
    // Cesium 静态资源路径
    CESIUM_BASE_URL: JSON.stringify('/cesium')
  },
  optimizeDeps: {
    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 或其他方式复制到构建输出：

// vite.config.js
import { viteStaticCopy } from 'vite-plugin-static-copy'

export default defineConfig({
  plugins: [
    viteStaticCopy({
      targets: [
        // Cesium 静态资源
        {
          src: 'node_modules/cesium/Build/Cesium/*',
          dest: 'cesium'
        },
        // sdk-plotting 资源
        {
          src: 'node_modules/@metagl/sdk-plotting/resources',
          dest: 'resources'
        }
      ]
    })
  ],
  // 如果代码中通过 /lib/resources 路径请求资源，配置代理
  server: {
    proxy: {
      '/lib/resources': {
        target: 'http://localhost:9521',
        changeOrigin: true,
        rewrite: (path) => path.replace('/lib/resources', '/resources')
      }
    }
  }
})

2.3 入口文件加载

UMD 格式需要通过动态 import 加载，并在加载后将全局变量 LACDT 和 window.Cesium 暴露出来：

// main.js
import { createApp } from 'vue'
import App from './App.vue'

// 解冻 Cesium（使 sdk-plotting 能扩展 Cesium 对象）
function makeExtensible(obj) {
  const newObj = Object.create(Object.getPrototypeOf(obj))
  Object.getOwnPropertyNames(obj).forEach(key => {
    const descriptor = Object.getOwnPropertyDescriptor(obj, key)
    if (descriptor) {
      Object.defineProperty(newObj, key, {
        ...descriptor,
        configurable: true,
        writable: true
      })
    }
  })
  return newObj
}

async function bootstrap() {
  // 1. 加载 Cesium
  const CesiumModule = await import('cesium')
  let cesium = CesiumModule.default || CesiumModule
  cesium = makeExtensible(cesium)
  window.Cesium = cesium

  // 2. 加载 sdk-plotting（动态 import）
  await import('@metagl/sdk-plotting')

  // 3. 此时 LACDT 全局对象已就绪
  const app = createApp(App)
  app.config.globalProperties.$metaGL = window.LACDT
  app.config.globalProperties.$cesium = window.Cesium
  app.mount('#app')
}

bootstrap()

3. Webpack 项目配置要点

Webpack 项目需配置 Cesium 为 external：

// webpack.config.js
module.exports = {
  externals: {
    cesium: 'Cesium'
  }
}

主要功能

创建点、线、面、文本标注、图标等要素
支持要素样式配置（颜色、宽度、图标、透明度等）
要素编辑（拖拽、顶点编辑、删除）
支持要素分组与图层管理
事件绑定（点击、悬停、编辑开始/结束等）
批量导入/导出 GeoJSON
军事标会、箭头、扇形、椭圆等多种军事图形
热力图、OD 线、三维体（立方体、圆柱体）等分析效果

快速开始

初始化引擎

// UMD 方式
const engine = new LACDT.Engine('cesiumContainer');

// npm import 方式
import { Engine } from '@metagl/sdk-plotting';
const engine = new Engine('cesiumContainer');

创建标绘元素的两种方式

方式 A：`createPlot` 交互绘制（按分类选择）

通过 engine.plot.createPlot() 按分类树选择图形类型，支持鼠标在地图上交互绘制。

// 示例 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 参数直接创建标绘元素，代码精确控制样式和位置，无需交互。

// 示例 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 | 立方体 | [经度, 纬度, 高度] |

编辑与交互

// 开启编辑模式
engine.plot.open();

// 关闭编辑模式
engine.plot.close();

// 编辑完成后回调
engine.plot.onPick((data) => {
  console.log('编辑变更:', data);
});

graphicLayer 常用 API

// 删除单个对象
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);

事件监听

// 监听添加事件（通过 engine.plot）
engine.plot.on('add', (sceneObject) => {
  console.log('新对象已添加:', sceneObject);
});

// 监听删除事件
engine.plot.on('remove', (gvolObject) => {
  console.log('对象已删除:', gvolObject);
});

构建

npm run build         # webpack 生产构建
npm run build:rollup  # rollup 构建
npm run build:dts     # 生成类型声明文件

构建产物输出到 lib/ 目录，npm run build 会自动将产物复制到 publish/ 目录。

发布

npm run login        # 登录 npm
cd publish && npm publish --access public  # 发布

常见问题

UMD 方式

资源 404：确保 resources/ 目录与 lacdt.plotting.js 保持正确的相对路径
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
SDK 无法扩展 Cesium：UMD 格式的 SDK 会扩展 window.Cesium，需在 import 之前确保 Cesium 已挂载到 window，且对象未被 Object.freeze()

许可证

ISC

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@metagl/sdk-plotting

两种使用方式

方式一：HTML script 标签引入（UMD 方式）

方式二：npm import 引入（ESM 方式）

1. 安装

2. Vite 项目配置要点

2.1 Cesium 别名映射 + 排除预打包

2.2 静态资源拷贝

2.3 入口文件加载

3. Webpack 项目配置要点

主要功能

快速开始

初始化引擎

创建标绘元素的两种方式

方式 A：createPlot 交互绘制（按分类选择）

方式 B：engine.graphicLayer.add() API 直接创建

编辑与交互

graphicLayer 常用 API

事件监听

构建

发布

常见问题

UMD 方式

npm import 方式

许可证

方式 A：`createPlot` 交互绘制（按分类选择）

方式 B：`engine.graphicLayer.add()` API 直接创建