Mars3D开发教程

在已有项目中集成Mars3D

6/1/2023

在阅读本节前，建议您已阅读：

再尝试将 mars3d 集成到自己的项目中。

下面三种方式任选一种，注意不要重复操作

# 1. 在html直接引入所有资源方式集成 (cdn cesium + cdn mars3d)

具体引入方式请参考上一篇获取 Mars3D SDK 类库 操作即可。

当在传统技术栈时(html/java/php/net 等)，可以在 html 的 head 标签中引入 Cesium 官方包和 Mars3D 包所有相关资源，此方法比较简单，mars3d 已经挂载在window 对象 (opens new window)下面，不会出现各类集成问题。

<!--引入cesium基础lib-->
<link href="./lib/Cesium/Widgets/widgets.css" rel="stylesheet" type="text/css" />
<script>
  // window.CESIUM_BASE_URL = "./lib/Cesium/" //非必须，如jsp、asp.net等非html框架报错时建议取消注释
</script>
<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/mars3d.css" rel="stylesheet" type="text/css" />
<script src="./lib/mars3d/mars3d.js" type="text/javascript" ></script>
1
2
3
4
5
6
7
8
9
10
11

引入 mars3d 后，在项目 js 代码中，可通过window.mars3d.* 来使用 mars3d 相关类及方法。

# 2. 在html直接引入Cesium资源和import mars3d方式集成 (cdn cesium + import mars3d)

如果在 Node 下的相关 vue/react/angular 等技术栈（下面介绍的方式3）时无法成功集成，运行项目不正常，也可以在 import 引入 mars3d 的方式下，兼容识别 head 静态引入的 Cesium 库。

主要修改项目地图呈现对应的首页index.html (opens new window)页面，在其 head 中引入 cesium 资源。

cesium 是通过在 html 的 head 中静态引入的

<!--引入cesium基础lib-->
<link href="./lib/Cesium/Widgets/widgets.css" rel="stylesheet" type="text/css" />
<script>
  // window.CESIUM_BASE_URL = "./lib/Cesium/" //非必须，如jsp、asp.net等非html框架报错时建议取消注释
</script>
<script src="./lib/Cesium/Cesium.js" type="text/javascript" ></script>
<script src="./lib/turf/turf.min.js" type="text/javascript" ></script>
1
2
3
4
5
6
7

mars3d 还是通过 import 方式引入及使用的：

import "mars3d-cesium/Build/Cesium/Widgets/widgets.css" //依赖的cesium库本身css
import "mars3d/dist/mars3d.css";
import * as mars3d from "mars3d";
1
2
3

您可以参考vue2-template (opens new window) 项目的index.html (opens new window)文件，里面已有演示。 如果您下载了该项目源码进行运行，注意下载后修改.env (opens new window)文件中配置为VUE_APP_MARS3D_SOURCE=cdn。

同时也建议在对应的技术栈配置中排除mars3d-cesium的引用和打包

configureWebpack: {
  externals: { 'mars3d-cesium': 'Cesium' }
},
1
2
3

# 3.通过 import 导入 mars3d 及所有依赖包的集成方式(import cesium + import mars3d)

使用 Node 环境下的现代 web 前端技术栈时，可以使用 npm 等来安装 mars3d 包并 import 导入后来使用。 具体引入方式请参考上一篇获取 Mars3D SDK 类库 操作即可。

因为 mars3d 所依赖的 Cesium 是一个多文件资源的 js 库，需要对其依赖的一些资源文件进行拷贝处理（这也是容易出问题的地方）， 90% 的集成问题都是出现在这对 cesium 库的拷贝处理上，项目运行没有正确识别 Cesium 主目录造成各种问题。

下面请根据你项目的技术栈，选择对应的集成方式。

# 3.1 webpack 技术栈时 的项目配置修改

修改文件：webpack.config.js

参考项目：mars3d-webpack (opens new window)

关键代码及步骤：

  • 安装依赖库（注意copy-webpack-plugin与webpack版本的依赖，可能需要按webpack对应版本的相关版本安装）
npm install copy-webpack-plugin --save-dev
1
  • 修改 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库安装目录
const cesiumRunPath = "./mars3d-cesium/"; // cesium运行时路径

module.exports = {
  module: {
    rules: [
      { test: /\.css$/, use: ["style-loader", "css-loader"], },
      { test: /\.js$/, use: { loader: 'babel-loader', options: { plugins: ['@babel/plugin-proposal-class-properties'] } } }
    ],
  },
  plugins: [
    // CESIUM_BASE_URL是标识cesium资源所在的主目录，其内部资源加载、多线程等处理时需要用到
    new webpack.DefinePlugin({
      CESIUM_BASE_URL: JSON.stringify(cesiumRunPath),
    }),
    // Cesium相关资源目录需要拷贝到系统目录下面（部分CopyWebpackPlugin版本的语法可能没有patterns）
    new CopyWebpackPlugin({
      patterns: [
        { from: path.join(cesiumSourcePath, 'Workers'), to: path.join(cesiumRunPath, 'Workers') },
        { from: path.join(cesiumSourcePath, 'Assets'), to: path.join(cesiumRunPath, 'Assets') },
        { from: path.join(cesiumSourcePath, 'ThirdParty'), to: path.join(cesiumRunPath, 'ThirdParty') },
        { from: path.join(cesiumSourcePath, 'Widgets'), to: path.join(cesiumRunPath, 'Widgets') }
      ]  
    }),
  ],
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
  • 常见问题：集成提示错误时，可看下"@vue/cli-service"的版本，需要是v5及以上版本，可以升级为："~5.0.0",

# 3.2 vue-cli 技术栈时 的项目配置修改

修改文件：vue.config.js 参考项目：vue2-template (opens new window)

关键代码及步骤：

  • 安装依赖库（注意copy-webpack-plugin与webpack版本的依赖，可能需要按webpack对应版本的相关版本安装）
npm install copy-webpack-plugin --save-dev
1
  • 修改 vue.config.js 配置文件
const path = require('path')
const webpack = require('webpack')
const CopyWebpackPlugin = require('copy-webpack-plugin')

module.exports = {
  configureWebpack: (config) => {
    const cesiumSourcePath = 'node_modules/mars3d-cesium/Build/Cesium/' // cesium库安装目录
    const cesiumRunPath = './mars3d-cesium/' // cesium运行时路径

    const plugins = [
      // 标识cesium资源所在的主目录，cesium内部资源加载、多线程等处理时需要用到
      new webpack.DefinePlugin({
        CESIUM_BASE_URL: JSON.stringify(path.join(config.output.publicPath, cesiumRunPath))
      }),
      // Cesium相关资源目录需要拷贝到系统目录下面（部分CopyWebpackPlugin版本的语法可能没有patterns）
      new CopyWebpackPlugin({
        patterns: [
          { from: path.join(cesiumSourcePath, 'Workers'), to: path.join(config.output.path, cesiumRunPath, 'Workers') },
          { from: path.join(cesiumSourcePath, 'Assets'), to: path.join(config.output.path, cesiumRunPath, 'Assets') },
          { from: path.join(cesiumSourcePath, 'ThirdParty'), to: path.join(config.output.path, cesiumRunPath, 'ThirdParty') },
          { from: path.join(cesiumSourcePath, 'Widgets'), to: path.join(config.output.path, cesiumRunPath, 'Widgets') }
        ]
      })
    ]

    return {
      module: { unknownContextCritical: false }, // 配置加载的模块类型，cesium时必须配置
      plugins: plugins
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# 3.3 vite 技术栈时 的项目配置修改

修改文件：vite.config.ts 参考项目：vue3-vite-template (opens new window)

关键代码及步骤：

  • 安装依赖库
npm install vite-plugin-mars3d --save-dev
1
  • 修改 vite.config.ts 配置文件
import { defineConfig } from 'vite';
import { mars3dPlugin } from 'vite-plugin-mars3d';

export default defineConfig({
  plugins: [mars3dPlugin()]
});
1
2
3
4
5
6

# vite常见问题

  • 使用原生cesium时，不要安装 mars3d-cesium（不能同时存在2个cesium 包），再在vite.config.ts配置改为 mars3dPlugin({ cesiumPackageName: "cesium" })
  • 如果项目的 package.json 没有 type:"module" 或vite4及之前版本时，请使用 "vite-plugin-mars3d":"~3.1.3"
  • 如果项目的 package.json 有 type:"module" 直接用最新版本即可。
  • 如果无法排除解决问题，也可以在vite.config.ts配置改为静态引入 mars3dPlugin({ useStatic: true })

# 4. 新建DIV容器 + 创建地图

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

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

在对应技术栈的相关代码出，使用Map 地图类 (opens new window)类创建三维地图场景，加入下面代码：

var mapOptions = {
  basemaps: [{ name: "天地图", type: "tdt", layer: "img_d", show: true }],
};
var map = new mars3d.Map("mars3dContainer", mapOptions); //支持的参数请看API文档：http://mars3d.cn/api/Map.html
1
2
3
4

详细可以对应技术栈的开源最简项目模板

# 运行效果

新窗口查看
最后更新: 10/21/2024, 9:19:46 AM

SDK授权