@edgex/cesium

基于 CesiumJS 的 Vue 3 组件库，将 Cesium 地图功能封装为声明式 Vue 组件，支持作为 npm 包发布使用。

技术栈

• Vue 3 + TypeScript + Vite
• CesiumJS ^1.131.0
• pnpm 包管理
• vite-plugin-wasm WASM 支持
• unplugin-auto-import / unplugin-vue-components 自动导入
• @hey-api/openapi-ts OpenAPI 客户端生成

快速开始

# 安装依赖
pnpm install

# 启动开发服务器 (端口 5175)
pnpm dev

# 构建组件库
pnpm lib

# 发布到 npm
pnpm pub

作为 npm 包使用

npm install @edgex/cesium

import { createApp } from 'vue';
import ATGCesium from '@edgex/cesium';
import 'cesium/Build/Cesium/Widgets/widgets.css';

const app = createApp(App);
app.use(ATGCesium, {
  publicPath: '/your-public-path',  // Cesium 静态资源路径
  cesiumAk: 'your-cesium-ion-token', // 可选，Cesium Ion access token
});

项目结构

src/
├── components/           # 核心组件（库的导出入口）
│   ├── index.ts          # Vue 插件入口，自动注册所有组件
│   ├── CesiumBase.vue    # 基础地图容器（初始化 Viewer）
│   ├── CesiumGlobalState.ts  # 全局 Viewer 状态管理
│   ├── enums.ts          # 瓦片类型枚举
│   ├── geo-utils.ts      # 地理计算工具
│   ├── utils.ts          # 地形高度采样等工具
│   │
│   ├── # --- 底图图层组件 ---
│   ├── CesiumCustomImg.vue          # 自定义瓦片服务（通用 URL 模板）
│   ├── CesiumCustomImgV2.vue        # 自定义瓦片服务 V2
│   ├── CesiumGoogle.vue             # Google 卫星影像
│   ├── CesiumGoogle2Dtile.vue       # Google 2D 瓦片（带 session 管理）
│   ├── CesiumGoogle3Dtile.vue       # Google 3D Tileset
│   ├── CesiumGooglePhotorealistic3DTileset.vue  # Google 真实感 3D Tileset
│   ├── CesiumEVOImg.vue             # 星图地球影像
│   ├── CesiumEVOTerrain.vue         # 星图地球地形
│   ├── CesiumEVOCia.vue             # 星图地球注记
│   ├── CesiumEVOCat.vue             # 星图地球地形注记
│   ├── CesiumEVOWhitemodel.vue      # 星图地球白模
│   ├── CesiumTDTImg.vue             # 天地图影像
│   ├── CesiumAMapImg.vue            # 高德卫星影像
│   ├── CesiumAMapCia.vue            # 高德路网注记
│   ├── CesiumMapbox.vue             # Mapbox 卫星影像
│   ├── CesiumMapboxImgOfficial.vue  # Mapbox 官方地形 V2
│   ├── CesiumMapboxImgStyle.vue     # Mapbox 样式图层
│   ├── CesiumOpenStreet.vue         # OpenStreetMap
│   ├── CesiumBmapImg.vue            # 百度卫星影像
│   ├── CesiumSingleTile.vue         # 单张图片叠加
│   │
│   ├── # --- 几何 & 渲染组件 ---
│   ├── CesiumPolygon.vue            # 多边形绘制
│   ├── CesiumCircle.vue             # 圆形标注（带 label）
│   ├── CesiumLoadGLTF.vue           # 加载 glTF/glb 模型
│   ├── CesiumGroundPrimitive.vue    # 地面贴图（GroundPrimitive）
│   ├── CesiumImageMaterial.vue      # 图片材质矩形
│   ├── CesiumGEOJSON.vue            # GeoJSON 数据加载
│   ├── CesiumSwitchScenceMode.vue   # 2D/3D 模式切换
│   │
│   └── tools/                       # UI 工具组件
│       ├── Cesium3D2DToggle.vue     # 3D/2D 视图切换按钮
│       ├── CesiumLayerSwitch.vue    # 图层切换（占位）
│       └── CesiumLeftFrameSelection.vue  # 框选工具
│
├── views/                # 开发时的演示页面（不包含在库构建中）
│   ├── HomeView.vue               # 主页（组合各组件演示）
│   ├── TranslationRotation.vue    # 坐标平移旋转演示
│   ├── TranslationRotation2.vue   # 交互式平移旋转（前进/右移/旋转控制）
│   ├── AnimateView.vue            # 动画点位移动
│   ├── TilesView.vue              # 3D Tileset 加载定位
│   ├── PlanView.vue               # 任务计划数据加载
│   ├── MappingTest.vue            # 点位映射连线可视化
│   ├── CzmlTest1.vue              # CZML 数据源加载 + 悬浮信息
│   ├── CzmlTest2.vue              # CZML 动态数据更新
│   ├── KonvaView.vue              # Konva.js 虚拟滚动渲染演示
│   ├── ProtobufjsView.vue         # Protobuf 二进制数据解码
│   ├── VueStarter.vue             # Vue 响应式基础演示
│   ├── ShellView.vue              # 终端模拟器（xterm.js + WebSocket SSH）
│   └── TempView.vue               # 临时测试页
│
├── script/
│   ├── router.ts                  # Vue Router 路由配置
│   └── FixedLevelImageryProvider.ts  # 自定义固定层级 ImageryProvider
│
├── utils/
│   ├── index.ts                   # 工具入口
│   └── graphing-calculator.ts     # 几何计算（多边形中心、坐标轴辅助线）
│
├── client/               # OpenAPI 自动生成的 API 客户端
├── data/                  # 测试瓦片数据
├── assets/data/           # 映射测试数据
├── czml/                  # CZML 测试数据
└── main.ts                # 应用入口

核心架构

组件设计模式

所有组件遵循统一的 "声明式图层" 模式：

<!-- 用法示例：组件像图层一样组合 -->
<CesiumBase @ready="onMapReady" :degress="[120.17, 30.90, 1000]">
  <CesiumCustomImg url="http://tile-server/api" path="tile" :tile-type="TileType.B" />
  <CesiumLoadGLTF />
  <CesiumPolygon :degress-array="[...]" />
</CesiumBase>

• CesiumBase 是容器组件，初始化 Cesium Viewer 并通过 @ready 事件通知就绪
• 子组件在 onMounted 中通过 cesiumGlobalState.viewer 获取 Viewer 实例，添加图层/实体
• 子组件在 onUnmounted 中自动清理资源（移除图层/实体）

全局状态

import { cesiumGlobalState } from '@edgex/cesium';

// 获取当前 Viewer 实例
const viewer = cesiumGlobalState.viewer;

导出的工具函数

import { getTerrainHeight, createRectangleFromCenter } from '@edgex/cesium';

// 地形高度采样
const [cartographic] = await getTerrainHeight([
  Cartographic.fromDegrees(longitude, latitude)
]);
console.log(cartographic.height);

// 创建以某点为中心、边长 n 公里的矩形
const rect = createRectangleFromCenter([120.17, 30.90], 4);

支持的底图服务

| 组件 | 服务商 | 类型 | |------|--------|------| | CesiumGoogle / Google2Dtile / Google3Dtile | Google Maps | 影像/2D瓦片/3D Tileset | | CesiumGooglePhotorealistic3DTileset | Google | 真实感 3D | | CesiumEVOImg / EVOTerrain / EVOCia / EVOCat | 星图地球 (GeoVis) | 影像/地形/注记 | | CesiumTDTImg | 天地图 | 影像 | | CesiumAMapImg / AMapCia | 高德地图 | 卫星/路网 | | CesiumMapbox / MapboxImgOfficial / MapboxImgStyle | Mapbox | 卫星/地形/样式 | | CesiumOpenStreet | OpenStreetMap | 街道地图 | | CesiumBmapImg | 百度地图 | 卫星影像 | | CesiumCustomImg | 自定义瓦片服务 | 通用 URL 模板 |

路由页面（开发模式）

| 路径 | 页面 | 说明 | |------|------|------| | / | HomeView | Cesium 地图主页，组合各种图层与模型 | | /translation-rotation | TranslationRotation2 | 交互式坐标变换演示 | | /konva | KonvaView | Konva 虚拟滚动渲染 | | /protobufjs | ProtobufjsView | Protobuf 解码演示 | | /vue | VueStarter | Vue 基础响应式 | | /shell | ShellView | 终端模拟器 |

构建产物

库模式构建（pnpm lib）输出到 dist/：

• index.es.js — ESM 格式
• index.d.ts — TypeScript 类型声明
• 外部依赖：vue 和 cesium 不会打包进产物