使用Mars3D创建一个三维地球的过程记录

1,954 阅读9分钟

Mars3D 是什么?

Mars3D三维可视化平台 是火星科技 研发的一款基于 WebGL 技术实现的三维客户端开发平台,基于Cesium 优化提升与B/S架构设计,支持多行业扩展的轻量级高效能GIS开发平台,能够免安装、无插件地在浏览器中高效运行,并可快速接入与使用多种GIS数据和三维模型,呈现三维空间的可视化,完成平台在不同行业的灵活应用。

Mars3D平台可用于构建无插件、跨操作系统、 跨浏览器的三维 GIS 应用程序。平台使用 WebGL 来进行硬件加速图形化,跨平台、跨浏览器来实现真正的动态大数据三维可视化。通过 Mars3D产品可快速实现浏览器和移动端上美观、流畅的三维地图呈现与空间分析。

功能体验: 👉 Mars3D官网

开发资料: 👉 API文档 👉 开发教程 

开源代码: 👉 Github开源代码 👉 Gitee开源代码(国内)

快速上手

Mars3D 提供了多种安装方式,你可以根据项目的实际情况和技术栈选择以下任意一种方式安装。

  • 从 npm 安装
  • 从 CDN 引入
  • 从 Mars3D官网 下载

接下来我们将分别介绍这些安装方式,以及下载后的目录结构。

安装方式

1. 从 npm 获取

使用Node环境下的现代web前端技术栈时,可以使用npm或cnpm或yarn等方式来安装mars3d包

//安装mars3d主库
npm install mars3d --save   

//安装mars3d插件(按需安装)
npm install mars3d-space --save
Npm version Npm downloads Npm下载量

安装后在相关使用文件中引入使用即可

import 'mars3d/dist/mars3d.css'
import * as mars3d from 'mars3d'
 
//导入mars3d插件(按需使用,需要先npm install)
import 'mars3d-space'

详见在项目中引入 Mars3D, 您也可以参考 vue最简项目模板react最简项目模板angular最简项目模板

2. 从 CDN 获取

在html的head标签中引入Mars3D包相关CDN资源.

可以选用 unpkg.com的CDN服务

<!--引入cesium基础lib-->
<link href="https://unpkg.com/mars3d-cesium/Build/Cesium/Widgets/widgets.css" rel="stylesheet" type="text/css" />
<script src="https://unpkg.com/mars3d-cesium/Build/Cesium/Cesium.js" type="text/javascript" ></script>
<script src="https://unpkg.com/@turf/turf/turf.min.js" type="text/javascript" ></script>

<!--引入mars3d库lib-->
<link href="https://unpkg.com/mars3d/dist/mars3d.css" rel="stylesheet" type="text/css" />
<script src="https://unpkg.com/mars3d/dist/mars3d.js" type="text/javascript" ></script>  


<!--引入mars3d库插件lib(按需引入)-->  
<script src="https://unpkg.com/mars3d-space/dist/mars3d-space.js" type="text/javascript" ></script> 

可以选用 jsDelivr 的CDN服务

<!--引入cesium基础lib-->
<link href="https://cdn.jsdelivr.net/npm/mars3d-cesium/Build/Cesium/Widgets/widgets.css" rel="stylesheet" type="text/css" />
<script src="https://cdn.jsdelivr.net/npm/mars3d-cesium/Build/Cesium/Cesium.js" type="text/javascript" ></script>
<script src="https://unpkg.com/@turf/turf/turf.min.js" type="text/javascript" ></script>

<!--引入mars3d库lib-->
<link href="https://cdn.jsdelivr.net/npm/mars3d/dist/mars3d.css" rel="stylesheet" type="text/css" />
<script src="https://cdn.jsdelivr.net/npm/mars3d/dist/mars3d.js" type="text/javascript" ></script>  


<!--引入mars3d库插件lib(按需引入)-->  
<script src="https://cdn.jsdelivr.net/npm/mars3d-space/dist/mars3d-space.js" type="text/javascript" ></script> 

CDN流量 CDN流量

引入后在相关使用文件中直接使用window.mars3d对象即可 。

3. 从 Mars3D官网 下载获取

可以在Mars3D官网下载 mars3d离线包 后在本地项目中引入相对路径资源来使用。

将下载的SDK放在项目目录内,使用方式与上面2种基本相同,区别在于url路径是本地项目的相对路径。

3.1 类似CDN的head静态资源方式引入

<!--引入cesium基础lib-->
<link href="./lib/Cesium/Widgets/widgets.css" rel="stylesheet" type="text/css" />
<script src="./lib/Cesium/Cesium.js" type="text/javascript" ></script>
<script src="./lib/turf/turf.min.js" type="text/javascript" ></script>

<!--引入mars3d库lib-->
<link href="./lib/mars3d/dist/mars3d.css" rel="stylesheet" type="text/css" />
<script src="./lib/mars3d/dist/mars3d.js" type="text/javascript" ></script>  

<!--引入mars3d库插件lib(按需引入)-->  
<script src="./lib/mars3d/plugins/space/mars3d-space.js" type="text/javascript" ></script> 

3.2 类似npm的import方式导入

import './lib/mars3d/mars3d.css'
import * as mars3d from './lib/mars3d/mars3d.js' 

如果引入本地版本build编译很慢时,可以按下面配置修改babel.config.js

module.exports = {
  //已忽略其他配置
  ignore: [
    './src/components/Map/lib/mars3d/'  //改成自己的本地地址
  ]
}

引入 Mars3D

新建一个 index.html 文件,内容如下:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" /> 
    <!--引入cesium基础lib-->
    <link href="https://cdn.jsdelivr.net/npm/mars3d-cesium/Build/Cesium/Widgets/widgets.css" rel="stylesheet" type="text/css" />
    <script src="https://cdn.jsdelivr.net/npm/mars3d-cesium/Build/Cesium/Cesium.js" type="text/javascript" ></script>
    <!--引入mars3d库lib-->
    <link href="https://cdn.jsdelivr.net/npm/mars3d/dist/mars3d.css" rel="stylesheet" type="text/css" />
    <script src="https://cdn.jsdelivr.net/npm/mars3d/dist/mars3d.js" type="text/javascript" ></script>    
  </head>
</html>

打开这个 index.html,你会看到一片空白。但是不要担心,打开控制台确认没有报错信息,并有正确的mars3d版本等信息提示,就可以进行下一步。

绘制一个简单的三维地球

在绘三维地球前我们需要为 Mars3D 准备一个定义了高宽的 DOM 容器。在刚才的例子 </head> 之后,添加:

<body>
  <!-- 为 Mars3D 准备一个定义了宽高的 DOM -->
  <div id="mars3dContainer" class="mars3d-container"></div> 
</body>

然后就可以通过 new mars3d.Map方法初始化一个 mars3d 实例并通过传入 mapOptions 参数生成一个简单的三维地球,下面是完整代码。

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>mars3d</title> 
    <!--引入cesium基础lib-->
    <link href="https://cdn.jsdelivr.net/npm/mars3d-cesium/Build/Cesium/Widgets/widgets.css" rel="stylesheet" type="text/css" />
    <script src="https://cdn.jsdelivr.net/npm/mars3d-cesium/Build/Cesium/Cesium.js" type="text/javascript" ></script> 
    <!--引入mars3d库lib-->
    <link href="https://cdn.jsdelivr.net/npm/mars3d/dist/mars3d.css" rel="stylesheet" type="text/css" />
    <script src="https://cdn.jsdelivr.net/npm/mars3d/dist/mars3d.js" type="text/javascript" ></script>    
  </head>
  <body>
    <!-- 为 Mars3D 准备一个定义了宽高的 DOM -->
  <div id="mars3dContainer" class="mars3d-container"></div> 
    <script type="text/javascript">
     var mapOptions = {} //支持的参数请看API文档:http://mars3d.cn/api/Map.html
     var map = new mars3d.Map('mars3dContainer', mapOptions)
    </script>
  </body>
</html>

这样你的第一个三维地球就诞生了!

在已有项目中集成Mars3D

1. 引入Mars3D类库

可以根据您自己的技术栈使用情况,获取 Mars3D 进行下载或引入Mars3D库到自己的项目中去使用。

方式1:head静态资源方式引入

在html的head标签中引入Cesium官方包和Mars3D包相关资源,此方法比较简单,不会出现各类集成问题,引入资源后在代码即可通过window.mars3d来使用相关mars3d类及方法。

在线CDN版本:

<!--引入cesium基础lib-->
<link href="https://cdn.jsdelivr.net/npm/mars3d-cesium/Build/Cesium/Widgets/widgets.css" rel="stylesheet" type="text/css" />
<script src="https://cdn.jsdelivr.net/npm/mars3d-cesium/Build/Cesium/Cesium.js" type="text/javascript" ></script>
<script src="https://unpkg.com/@turf/turf/turf.min.js" type="text/javascript" ></script>

<!--引入mars3d库lib-->
<link href="https://cdn.jsdelivr.net/npm/mars3d/dist/mars3d.css" rel="stylesheet" type="text/css" />
<script src="https://cdn.jsdelivr.net/npm/mars3d/dist/mars3d.js" type="text/javascript" ></script>  

<!--引入mars3d库插件lib(按需引入)-->  
<script src="https://cdn.jsdelivr.net/npm/mars3d-space/dist/mars3d-space.js" type="text/javascript" ></script> 

本地版本(下载链接):

<!--引入cesium基础lib-->
<link href="./lib/Cesium/Widgets/widgets.css" rel="stylesheet" type="text/css" />
<script src="./lib/Cesium/Cesium.js" type="text/javascript" ></script>
<script src="./lib/turf/turf.min.js" type="text/javascript" ></script>

<!--引入mars3d库lib-->
<link href="./lib/mars3d/dist/mars3d.css" rel="stylesheet" type="text/css" />
<script src="./lib/mars3d/dist/mars3d.js" type="text/javascript" ></script>  

<!--引入mars3d库插件lib(按需引入)-->  
<script src="./lib/mars3d/plugins/space/mars3d-space.js" type="text/javascript" ></script> 

方式2: import方式导入

使用Node环境下的现代web前端技术栈时,可以使用npm等来安装mars3d包并import导入后来使用。

//引入npm版本时
import 'mars3d/dist/mars3d.css'
import * as mars3d from 'mars3d'

//引入下载的本地版本时
// import './lib/mars3d/mars3d.css'
// import * as mars3d from './lib/mars3d/mars3d.js' 
 
//导入mars3d插件(按需使用,需要先npm install)
import 'mars3d-space'

//可以绑定下vue原型链,可以全局使用
Vue.prototype.mars3d = mars3d;

//在具体使用的vue等文件中
//直接使用 this.mars3d 进行相关调用。

修改项目配置

因为mars3d所依赖的Cesium是一个多文件资源的js库,需要对其依赖的一些资源文件进行拷贝处理(这也是容易出问题的地方), 下面已Webpack技术栈为例,vue等其他技术栈类似(可以参考开源项目清单内下载后的项目模板对应README说明处理)。

npm install copy-webpack-plugin -save --dev
// webpack.config.js  
const path = require('path')
const webpack = require('webpack')
const CopyWebpackPlugin = require('copy-webpack-plugin')

const cesiumSourcePath = 'node_modules/mars3d-cesium/Build/Cesium/' //cesium库目录
let cesiumRunPath = './cesium/'//cesium运行时主目录

module.exports = {
  plugins: [
      //标识cesium资源所在的主目录,cesium内部资源加载、多线程等处理时需要用到
      new webpack.DefinePlugin({
        CESIUM_BASE_URL: JSON.stringify(cesiumRunPath)
      }),
      //cesium相关资源目录需要拷贝到系统目录下面
      new CopyWebpackPlugin([{ from: path.join(cesiumSourcePath, 'Workers'), to: path.join(cesiumRunPath, 'Workers') }]),
      new CopyWebpackPlugin([{ from: path.join(cesiumSourcePath, 'Assets'), to: path.join(cesiumRunPath, 'Assets') }]),
      new CopyWebpackPlugin([{ from: path.join(cesiumSourcePath, 'ThirdParty'), to: path.join(cesiumRunPath, 'ThirdParty') }]),
      new CopyWebpackPlugin([{ from: path.join(cesiumSourcePath, 'Widgets'), to: path.join(cesiumRunPath, 'Widgets') }])
  ],
}

// vue.config.js
const path = require('path')
const webpack = require('webpack')
const CopyWebpackPlugin = require('copy-webpack-plugin')
 

module.exports = {
  configureWebpack: (config) => {
    let cesiumSourcePath = 'node_modules/mars3d-cesium/Build/Cesium/' //cesium库目录
    let cesiumRunPath = config.output.publicPath || './cesium/' //cesium运行时主目录
    let plugins = [
      //标识cesium资源所在的主目录,cesium内部资源加载、多线程等处理时需要用到
      new webpack.DefinePlugin({
        CESIUM_BASE_URL: JSON.stringify(cesiumRunPath)
      }),
      //cesium相关资源目录需要拷贝到系统目录下面
      new CopyWebpackPlugin([{ from: path.join(cesiumSourcePath, 'Workers'), to: path.join(config.output.path, cesiumRunPath, 'Workers') }]),
      new CopyWebpackPlugin([{ from: path.join(cesiumSourcePath, 'Assets'), to: path.join(config.output.path, cesiumRunPath, 'Assets') }]),
      new CopyWebpackPlugin([{ from: path.join(cesiumSourcePath, 'ThirdParty'), to: path.join(config.output.path, cesiumRunPath, 'ThirdParty') }]),
      new CopyWebpackPlugin([{ from: path.join(cesiumSourcePath, 'Widgets'), to: path.join(config.output.path, cesiumRunPath, 'Widgets') }])
    ]

    config.plugins = [
      ...config.plugins,
      ...plugins
    ]
  }, 
  //已省略其他配置
}

::: danger
90% 的集成问题都是出现在这对cesium库的拷贝处理上,项目运行没有正确识别Cesium主目录造成各种问题。 :::

修改项目配置-CDN方式

如果上一步无法正常运行项目,也可以通过CDN方式引入Cesium,并还原上一步骤“修改项目配置”的所有配置。

mars3d库可以在import引入的方式下,兼容识别CDN引入的Cesium库。

<!--引入cesium基础lib-->
<link href="https://unpkg.com/mars3d-cesium/Build/Cesium/Widgets/widgets.css" rel="stylesheet" type="text/css" />
<script src="https://unpkg.com/mars3d-cesium/Build/Cesium/Cesium.js" type="text/javascript" ></script>

2. 新建div容器

在需要呈现地图的页面或相关组件中,加上div容器,并注意设置div的css高宽样式。

<div id="mars3dContainer" class="mars3d-container"></div> 

3. 使用mars3d.Map方法创建地球

使用Map地图类类创建三维地图场景。

 var mapOptions = {} //支持的参数请看API文档:http://mars3d.cn/api/Map.html
 var map = new mars3d.Map('mars3dContainer', mapOptions)

image.png

开源仓库清单

Mars3D所有资料和代码都均是免费开源的公开发布方式,下面是Mars3D平台所有开源仓库的清单:

导航

包含最新SDK下载包、离线API文档和其他仓库导航。

Github:github.com/marsgis/mar…

国内Gitee:gitee.com/marsgis/mar…

功能示例

对平台每个功能编写的案例代码,可以阅读每个示例代码来学习各功能,与官网功能示例一致效果。

技术栈Github国内Gitee说明
Vue3mars3d-vue-examplemars3d-vue-example功能示例Vue3源码
原生JSmars3d-es5-examplemars3d-es5-example功能示例原生JS源码

最简项目模板

提供了面向不同技术栈的最简项目模板,您可以直接使用或参考这些项目模板,了解SDK类库在不同技术栈项目中如何引入使用,快速搭建开发自己的项目。

技术栈Github国内Gitee说明
Vue3mars3d-vue-templatemars3d-vue-templateVue3最简的项目模板
Vue2mars3d-vue2-templatemars3d-vue2-templateVue2最简的项目模板
Reactmars3d-react-templatemars3d-react-templateReact最简的项目模板
Angularmars3d-angular-templatemars3d-angular-templateAngular最简的项目模板
原生JSmars3d-es5-templatemars3d-es5-template原生JS最简的项目模板

基础项目

基础项目是具备一个GIS项目常见功能的项目模板,只用更换数据及叠加业务即可完成项目交付。 如果需要更多功能可以考虑购买付费项目模板

技术栈Github国内Gitee说明
Vue3mars3d-vue-projectmars3d-vue-projectVue3开发的基础项目
原生JSmars3d-widget-projectmars3d-widget-project原生JS开发的(widget模式)基础项目

第3方平台融合

Mars3D支持结合Cesium相关的各类平台来兼容使用,方便结合不同平台的优点来达到完成各种项目需求。

技术栈Github国内Gitee说明
supermapmars3d-link-supermapmars3d-link-supermap与超图公司平台融合示例
earthsdkmars3d-link-earthsdkmars3d-link-earthsdk与earthsdk平台融合示例

其他

技术栈Github国内Gitee说明
ES6mars3d-pluginmars3d-plugin部分开源插件

讲解视频

我们对一些知识也录制了讲解视频,大家可以按需浏览,建议大家都看一遍。

1. 基础知识篇

内容视频地址对应代码
GIS基础知识讲解查看视频下载文档
Vue3+TypeScript前端基础讲解查看视频下载源码

2.Mars3D基础讲解

章节视频地址说明
入门及上手查看视频入门概念、开始上手
基础知识点查看视频开发基础、常见问题

3. 项目讲解

内容视频地址对应代码
功能示例Vue版项目查看视频下载源码
功能示例Vue版项目查看视频下载源码

Mars3D开发基础教程

下一步我们可以学习mars3d的一些基础知识,将三维可视化应用到自己项目中

  1. 三维场景 Map

  2. 地图控件

  3. 地图图层 Layer

  4. 加载DEM地形

  5. 栅格瓦片图层

  6. 坐标系及坐标变换

  7. 相机Camera及视角控制

  8. 时钟Clock及时序控制

  9. 事件机制

  10. 矢量图层Layer

  11. 矢量数据Graphic

  12. Property属性机制

  13. Material材质

  14. glTF小模型

  15. 3DTiles三维模型

  16. 场景特效

  17. 管理及分析功能