编译版本:2024 年 09 月 01 日
推荐运行环境:nodeJs 18.18.0
MetaVGE-3DVis-Vue3 是一个基于 WebGL 技术实现的三维地球 BS 端开发平台。
包括基于 Cesium 的拓展核心函数库、基于 Vue3 Vite 的 UI 组件库,开发了四十多个常用的 GIS 组件,包含地图、场景、图层、工具、控件、分析、数据、模型、调试等模块。
开发者可通过简单的参数配置,进行系统配置、资源接入、组件定制等操作,快速一套搭建三维地球应用系统
官网帮助文档:http://8.146.208.114:8083/
在线演示系统:http://8.146.208.114:3000/MetaVGE-3DVis-Vue3/index.html
在线演示视频:https://webgpu.top:3016/VGEEarth-PPT/VGEEarth-演示-4k版.mp4
演示视频下载:https://webgpu.top:3016/VGEEarth-PPT/VGEEarth-演示-4k版.rar
本指南旨在介绍数字地球框架 MetaVGE-3DVis-Vue3 的内容与二次开发方法,包括 介绍、二次开发环境搭建流程、二次开发基础准则、功能类库开发规范、组件开发规范、应用系统开发运行方法等,为具有进行数字地球应用系统开发需求的用户提供参考。
本文档适用于具有三维 Web 研发基础的开发人员,须熟悉 HTML5、CSS3、JavaScript、ECMAScript6 等语言和标准,熟悉 Node.js、Cesium、Vue.js 等类库和框架。
MetaVGE-3DVis-Vue3 总体架构由基础层、类库层、组件层和应用层组成,其中,类库层和组件层是其核心内容。基础层包括基础运行环境例如浏览器环境、编程语言环境、前端架构环境等;类库层包含数字地球相关的数据解析、分析、可视化、服务等基础数据结构与算法,是纯 JavaScript 的类库、方法与接口的实现;组件层面向具体功能模块,结合前端 UI 框架和 类库进行实现,为应用系统提供封装好的、模块化的组件;应用层是基于类库和组件实现的数字地球应用系统,例如应用示例、专题应用系统等。
SDK 类库层目前包括三类功能类库:
Core(Config、DrawShape、Earth、EventMana、ExpandEntity、ExpandLayer、HandlerMana、Impl、KeyboardDominate、MeasureTool、PathPlanning、PlotTool、RunEntityController、TreeMana、WorkSpace)
Plus(ParticleSystem、SceneHelper、SpatialAnalysis、TileSetPlugin、VideoPlugin)
Utils(CameraUtils、CoordinateTool、GISMathUtils、MarkTool、SceneUtils、TileSetUtils、YaoDo)
组件层是基于以上的类库进行 WebUI 组件封装,包含 52 个 Web组件(图层管理、测量、空间分析、卷帘对比、时序数据可视化等)。
MetaVGE-3DVis-Vue3 的技术栈包括:
- Vue3、Element UI:开源前端框架
- Cesium:开源三维 JS 库
- turf、proj4:空间地理算法库
- Echarts、D3、MapV: 开源图表库 系统基于 webpack 打包工具进行构建,提供了打包组件为插件并运行插件的 功能。
系统基于 Vite 打包工具进行构建,提供了打包组件为插件并运行插件的功能。
运行本系统前,必须安装的软件有:
- Node.js(大于 16.20.0 版本):请前往 https://nodejs.org/en/ 下载最新版本的软件并安装。
- Chrome 浏览器(大于 119.0.6045.160 版本):请下载最新版本的 Chrome 浏览器以便系统能够正常运行。
拉取项目的工程文件后,在根文件夹中打开终端窗口,在命令行中输入以下命令以安装系统运行所需要的依赖并启动项目
# 安装依赖包
npm install
# 服务启动/平台启动
npm run dev
系统目录结构介绍
- public
- app // 与应用项目
- config
- baseConfig.js // 地理资源配置文件,可配置影像、地形、模型等
- UIConfig.js // 组件的配置文件,控制加载、默认状态等行为
- VGEEarth
- Config
- ImageLayerTimeLine // 卷帘对比组件的配置文件
- pathPlanning // 路径规划组件的配置文件
- plotTool // 标绘工具组件的配置文件
- skybox // 天空盒组件的配置文件
- Ext // 其他第三方依赖库的路径
- Src // VGEEearhSDK 的路径
- favicon.ico
- src
- assets
- components // 开发者编写的第二次开发组件路径
- plugin
- router
- store
- VGEUtils // GIS 相关组件
- App.vue
- main.js
- index.html
- package.json
为确保您编写的二次开发库与组件能够正确的运行并集成,以下规则请您务必知晓并遵守
-
模块化。采用模块化开发思想,高内聚、低耦合;功能类库(纯 js 类库)、组件、应用系统分离;JavaScript、CSS、HTML 代码相互分离;将配置数据从代码中分离。
-
遵循 ES6 标准。提升内部代码的可复用性,可扩展性和可读性,提供的源码需要遵循 ES6编码语法、面向对象的编程开发方式和编码规范,例如:
- 使用 ES6 的模块机制,使用 import、export 来获取、输出变量;
- 全局不使用 var 定义变量,用 let,const 代替;
- 变量定义采用驼峰式;
- 函数名和方法名需要有意义;
- 建议使用 ES6 语法来优化代码。
-
避免自定义全局变量。为防止全局变量覆盖和污染,在二次开发库与组件的编写过程中禁止将变量赋值到全局作用域(例如 window,top)下。
-
禁止修改全局对象。请谨慎使用对 JS 全局对象进行修改的第三方插件,同时禁止编写代码对全局对象进行修改,例如:不允许向 String.Prototype 或Array.prototype 添加新的方法或修改已有方法。
-
VGEEearth.js 的使用:系统的运行环境中已默认引入并被设置为了全局变量
- 所有 Cesium 的 API 调用不受影响
- 本库主要是关于对 Cesium 的功能拓展,可通过 VGEEearth.* 来调用
-
第三方类库的使用:代码开发中如遇到需要引入第三方类库(如 lodash.js)的情形,推荐从 index.html 进行引入静态脚本文件,而不是 npm import 方式。因为在部署阶段可通过 CDN 进行对项目进行加速,并减少项目体积。
以下内容是项目二次开发的基础配置,包括了项目的基本运行信息、虚拟地球的图层管理、项目的UI样式、项目的组件状态控制。
本配置文件可对系统的如 项目标题名称、初始视角、资源根目录、地图资源、开场动画 等重要参数进行配置。实现工程项目打包后部署上线后,仍可以进行快捷修改。
具体完整示例可参见 MetaVGE-3DVis-Vue3\public\config\baseConfig.js ,使用记事本或代码编辑器都可以进行修改编辑,关键代码如下:
const baseConfig = {
/** SDK 的版本号,可由开发者去自定义 */
Version: string,
/** SDK 的 Token,用于与后台服务进行通信 */
Token: string,
/** 业务系统的名称 */
appName: string,
/** 显示在浏览器上 Tab 栏上的系统名称 */
appTitle: string,
/** 业务系统的图标 */
appIcon: string,
/** 数字地球的默认启动视角 */
homeView: {
longitude: number,
latitude: number,
height: number,
/** 弧度制 **/
headingRadians?: number,
pitchRadians?: number,
rollRadians?: number
},
/** 是否显示从全球旋转然后推进到默认视角的加载动画 */
startAnimation: boolean,
/** 演示服务器 基础路径 */
demoServerUrl: string,
/** 系统后台服务 基础路径 */
AppBaseUrl: string,
/** 静态资源服务器 基础路径 */
GISResourcesUrl: string,
/** GIS资源配置:图层、地形、gltf模型、倾斜模型、矢量、兴趣点 */
layerList: ResourceItem [],
terrainList: ResourceItem [],
modelList: ResourceItem [],
cesium3DTileSetList: ResourceItem [],
geoJsonList: ResourceItem [],
poiList: ResourceItem []
};
VGEEarth.ConfigTool.loadConfig(baseConfig);
图层、地形、gltf 模型、倾斜模型、矢量、兴趣点,在配置文件里都是以 ResourceItem []
对象数组的方式进行配置。
更多示例可参考 SDK 源码工程的 ```VGEEarth-SDK\Src\ts\Core\Config\Resource`` 目录
enum DataTypeEnum {
layer = 'layer',
terrain = 'terrain',
gltf = 'gltf',
Cesium3DTile = 'Cesium3DTile',
geoJson = 'geoJson',
water = 'water',
poi = 'poi'
}
interface ResourceItem {
pid: string, // 资源项的 pid,如果不指定,将默认自动生成一个
name: string, // 资源项的名称
catalog: string, // 资源项所属的目录
dataType: DataTypeEnum, // 资源项的类型
showInTree: boolean, // 资源项是否会出现在资源数中
defaultLoad: boolean, // 资源是否默认加载
/** 资源项的网络根路径 **/
netRootPaths?: string[],
/** 资源项是否开启 IndexedDB 缓存,如为 ture 则 netRootPaths 为必填项 **/
offlineCache: boolean,
/** 资源项的解码字符串 **/
decryptionKey?: string,
/** 为 Cesium 的默认参数。例如:
1、当资源类型为 layer 时,properties 对应填写 new Cesium.ImageryLayer(imageryProvider, options)的 options 参数
2、当资源类型为 terrain 时,properties 对应填写 new Cesium.Cesium3DTileset(options) 的 options 参数
**/
properties: any; // 为 Cesium 的默认参数。例如
}
layerList
图层类型的资源项
影像图层,或者加载任何可用的影像资源服务,默认加载一个 基础影像,全球影像底图
properties 内的 必填 参数:
属性名 | 类型 | 描述 |
---|---|---|
scheme | layerSchemeEnum | 图层的瓦片规则 |
url | string | 地形服务地址 |
enum layerSchemeEnum {
'layer-wms' = 'layer-wms',
'layer-tms' = 'layer-tms',
'layer-wmts' = 'layer-wmts',
'layer-singleTileImagery' = 'layer-singleTileImagery',
'layer-xyz-3857' = 'layer-xyz-3857',
'layer-xyz-4326' = 'layer-xyz-4326',
'layer-arcgisMapServer' = 'layer-arcgisMapServer',
'layer-geoserver' = 'layer-geoserver',
'IonImageryProvider' = 'IonImageryProvider'
}
下边是一个配置实例供用户参考
{
pid: 'f859bb06-68b3-aed9-f7c5-e85c0c544516',
name: '高德电子地图',
catalog: '基础数据',
dataType: 'layer',
showInTree: true,
defaultLoad: true,
properties: {
scheme: 'layer-xyz-3857',
url: 'http://webst04.is.autonavi.com/appmaptile?style=7&x={x}&y={y}&z={z}'
}
}
layerList
图层类型 的资源项配置参考实例:
地形图层,仅能加载一个地形数据。从上到下遍历数组,将第一个 defaultLoad
为 true
的地形图层设置为默认显示。
properties 内的 必填 参数:
属性名 | 类型 | 描述 |
---|---|---|
scheme | string | "CesiumTerrainProvider"||"VRTheWorldTerrainProvider" |
url | string | 地形服务地址 |
下边是一个配置实例供用户参考:
{
pid: '5b1f7a60-3195-4b95-1916-6e87558145f2',
name: '区域地形',
catalog: '经典场景',
dataType: 'terrain',
default: false,
properties: {
scheme: 'CesiumTerrainProvider',
url: 'https://127.0.0.1:3560/yuncs/dem'
},
}
cesium3DTileSetList
倾斜模型的资源项配置参考实例:
properties 内的 必填 参数:
属性名 | 类型 | 描述 |
---|---|---|
url | string | 3DTileSet 服务地址 |
offset | Offset | 可以设置模型相对于原位置的偏移量 |
interface Offset {
lon: number,
lat: number,
height: number
}
下边是一个配置实例供用户参考:
{
name: '大雁塔',
catalog: '三维模型',
dataType: '3DTiles',
properties: {
url: 'https://127.0.0.1:3560/3DTIles/tileset.json',
maximumScreenSpaceError: 2,
offset: {
height: 180
}
}
},
VGEEarth.ConfigTool
对象还有以下的方法:
/** 为 false 时,只将资源项显示在资源树中;为 true 时,直接加载上球,并显示在资源树中 **/
VGEEarth.ConfigTool.addOSMOnLine(false);
VGEEarth.ConfigTool.addMapBoxOnAliYun(false);
VGEEarth.ConfigTool.addBingMapOnIon(false);
VGEEarth.ConfigTool.addTerrainOnIon(false);
VGEEarth.ConfigTool.addTerrainOnAliYun(false);
工具箱中的工具UI
属性名 | 类型 | 默认值 | 描述 |
---|---|---|---|
demoModel | boolean | 无 | 当时组件的状态,是用于 Demo 演示,还是用在正真的生产环境下。 |
themeColor | 'green'|'yellow' | 无 | 应用主题颜色 |
comActions | Array | 无 | UI组件,分为三类,即UI 挂件、工具箱内模块、工具类挂件,见下 |
- UI 挂件
属性名 | 类型 | 默认值 | 描述 |
---|---|---|---|
name | string | 无 | 名字 |
type | 'UIPendant' | 无 | UI所属类型 |
open | boolean | 无 | 是否显示该组件 |
comName | string | 无 | 组件名称,该名称关联组件显隐控制 |
- 工具箱内模块
属性名 | 类型 | 默认值 | 描述 |
---|---|---|---|
name | string | 无 | 在工具箱中显示的名字 |
type | 'ToolBoxItem' | 无 | UI所属类型 |
open | boolean | 无 | 是否显示该组件 |
comName | string | 无 | 组件名称,该名称关联组件显隐控制 |
config | object | 无 | 配置工具控制按钮的显隐和icon,如 inToolBox: true, iconClass: 'dingwei' |
- 工具类挂件
属性名 | 类型 | 默认值 | 描述 |
---|---|---|---|
name | string | 无 | 名字 |
type | 'Pendant' | 无 | UI所属类型 |
open | boolean | 无 | 是否显示该组件 |
comName | string | 无 | 组件名称,该名称关联组件显隐控制 |
该方法控制组件的显隐状态,基础平台是根据vuex控制组件的,所以需要把改变状态时需要执行setVGEEarthComAction函数,对相应的组件显隐属性进行修改。
- mutations setVGEEarthComAction({comActions}, {name, on_off})
参数 | 类型 | 描述 |
---|---|---|
comActions | array | 所有组件的集合 |
name | string | 需要改变状态的组件名 |
on_off | number | 1:显示,2:隐藏,3:切换 |
this.$store.commit('setVGEEarthComAction', { name: 'areaNavigation', on_off: 2 });
该行代码修改了组件 areaNavigation 的状态为隐藏
- getters comStatus: (state) => (comName)
参数 | 类型 | 描述 |
---|---|---|
comName | string | 需要获取显隐状态的组件 |
this.$store.getters.comStatus("areaNavigation")
该行代码获取了组件 areaNavigation 的显隐状态
例如想创建一个名为 floodSimulation Vue 的组件,并且在工具箱中该工具的名字为 “洪水模拟”
在 UICongif 文件的对应位置添加下示代码
{name: '洪水模拟', type: 'ToolBoxItem', open: false, comName: 'floodSimulation', config: {inToolBox: true, iconClass: 'fenxi'}},
文件一般有两个,像图上这一对组件,content中是组建的内容,另外一个文件是控制组件显隐的组件。
- fs-content.vue 组件
该组件需要引入两个样式模板组件,来控制工具窗口的样式一致,即 TabPane、DarkGreenTabs,引入组件时,@是src 路径的简略写法。模板上的内容组织方式基本不需要改。
<template>
<dark-green-tabs style="left: 400px; width: 280px" @close="close">
<tabPane label="洪水模拟">
<div>这里写工具的内容</div>
</tabPane>
</dark-green-tabs>
</template>
<script>
import TabPane from '@/VGEUtils/views/window/src/tab-pane.vue';
import DarkGreenTabs from "../../../../views/window/darkGreenTabs.vue";
export default {
name: "fs-content",
components: {
DarkGreenTabs,
TabPane
},
methods: {
close() {
this.$store.commit('setVGEEarthComAction', { name: 'floodSimulation', on_off: 2 });
},
},
}
</script>
<style scoped></style>
- floodSimulation.vue 组件
该组件将fs-content组件引入并挂载,transition 是控制窗口显示隐藏的过渡效果
<template>
<transition name="fade">
<fsContent v-if="show"></fsContent>
</transition>
</template>
<script>
import fsContent from './fs-content.vue';
export default {
name: "floodSimulation",
components: { fsContent },
computed: {
show() {
return this.$store.getters.comStatus("floodSimulation")
}
}
}
</script>
<style scoped></style>
在工具箱的 index.vue 文件中,将 floodSimulation 引入并挂载。
<template>
<div>
...省略其他组件...
<floodSimulation></floodSimulation>
</div>
</template>
<script>
...省略其他组件...
import floodSimulation from "./lib/floodSimulation/floodSimulation.vue";
export default {
components: {
...省略其他组件...
floodSimulation
}
}
</script>
<style scoped>
</style>
至此新功能添加完毕,需要在对应的content组件中写具体的工具实现的功能(上边例子中的是 fs-content.vue 文件)。
基础平台的视窗如下。
平台的视窗挂载了工具、数据、可视化、标题、标题工具等多个组件,同时允许用户自定义设计。
用户可以自定义视窗主题UI,要想修改视窗的主题UI,需要找到视窗的css文件修改后引入。
该组件控制工程项目头中的左右两侧的工具按钮。
该组件控制工程项目左侧的工具,底图,可视化按钮。