# mars3d-cesium

[![npm](https://img.shields.io/npm/v/mars3d-cesium)](https://www.npmjs.com/package/mars3d-cesium)

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

本包基于 [CesiumJS](https://cesium.com/cesiumjs/)，包含 Mars3D 定制补丁。与 mars3d SDK 配合时，请采用 SDK 对应版本要求的引擎包。

## 安装与导入

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

ESM：

~~~js
// 引入依赖的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 版本列表](https://www.npmjs.com/package/mars3d-cesium?activeTab=versions) · [Mars3D 更新与仓库导航](https://github.com/marsgis/mars3d)

## 文档与示例

- [Mars3D 中使用 Cesium](http://mars3d.cn/docs/advanced/cesium/)
- [Vue 功能示例源码](https://github.com/marsgis/mars3d-vue-example) · [Vue 最简模板](https://github.com/marsgis/mars3d-vue-template)
- [CesiumJS 官方文档](https://cesium.com/learn/cesiumjs-learn/) · [官方示例](https://sandcastle.cesium.com/)
- [问题反馈](https://github.com/marsgis/mars3d/issues) · [国内问题反馈](https://gitee.com/marsgis/mars3d/issues)

## 许可证

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