mars3d-cesium

Mars3D 团队维护的 CesiumJS 修改版，用于浏览器中的三维地球和二维地图。主要扩展在 mars3d SDK 中实现，需要修改引擎内部的能力才在本包维护，并尽量通过参数控制，保留补丁说明。

本包基于 CesiumJS，包含 Mars3D 定制补丁。与 mars3d SDK 配合时，请采用 SDK 对应版本要求的引擎包。

安装与导入

//安装mars3d主库，其中mars3d-cesium  @turf/turf为依赖库
npm install mars3d mars3d-cesium  @turf/turf  --save

ESM：

// 引入依赖的CSS
import "mars3d-cesium/Build/Cesium/Widgets/widgets.css"
import "mars3d/mars3d.css"
// 引入mars3d-cesium库
import * as Cesium from "mars3d-cesium"; //也可以不写，mars3d会自动引入
// 引入mars3d主库
import * as mars3d from "mars3d"

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

页面需要有带明确宽高的 cesiumContainer 元素。底图、地形服务和访问令牌请按项目配置。

CommonJS 使用 require("mars3d-cesium")。包内提供 TypeScript 声明，ESM 与 CommonJS 入口分别使用 index.js 和 index.cjs；同一个应用应统一采用一种模块格式。

静态资源部署

打包器导入 JS 不会自动部署全部静态资源。请将以下目录从 node_modules/mars3d-cesium/Build/Cesium/ 复制到站点同一资源根目录，并保留名称及层级：

• Assets
• ThirdParty
• Widgets
• Workers

例如部署为 /lib/Cesium/Assets/、/lib/Cesium/Workers/，则资源根路径设置为 /lib/Cesium/。部署到子路径时应按实际 URL 修改；确认 Worker、WASM、图片和 CSS 请求能正常返回。

也可以部署完整 Build/Cesium 目录，通过 script 标签加载 Cesium.js，此时使用全局 Cesium；先定义 CESIUM_BASE_URL，再加载脚本，并通过 link 标签加载 Widgets/widgets.css。

包继续开放 mars3d-cesium/Build/* 深路径，供 CSS 导入及资源定位使用。

版本与升级

• npm 包版本唯一标识一次发布；同一上游版本上的后续补丁也必须使用新的包版本。
• 升级前核对 mars3d SDK 兼容要求，并回归地形、材质、裁剪、模型和 Worker 等实际使用场景。
• 源码仓库中的 mars3d修改部分/README.md 是维护入口；升级指南、补丁索引与构建脚本位于 mars3d修改部分/ 下。这些维护材料不随 npm 运行包分发。
• npm 版本列表 · Mars3D 更新与仓库导航

文档与示例

• Mars3D 中使用 Cesium
• Vue 功能示例源码 · Vue 最简模板
• CesiumJS 官方文档 · 官方示例
• 问题反馈 · 国内问题反馈

许可证

本包采用 Apache-2.0，完整许可、上游版权及第三方许可见随包分发的 LICENSE.md。CesiumJS 及第三方组件的版权归各自权利人所有。