# Mapbox + Cesium 集成研究

> 3D 地理信息系统最佳组合方案
>
> 归档：2026-04-23

---

## 📊 项目概览

| 组件 | Stars | 定位 |
|------|-------|------|
| **Cesium** | ⭐ 13.8k | 3D 地球/地图 WebGL 库 |
| **Mapbox GL JS** | ⭐ 11.2k | 矢量地图 WebGL 渲染 |

---

## 🎯 为什么组合？

### Cesium 优势
- ✅ 真正的 3D 地球（WGS84 球体）
- ✅ 3D Tiles 支持（BIM/CAD/点云）
- ✅ 地形高程数据
- ✅ 时间动态数据可视化
- ✅ 大规模数据集支持

### Mapbox 优势
- ✅ 精美的矢量地图样式
- ✅ 丰富的地图风格选择
- ✅ 高性能 2D 渲染
- ✅ 完善的样式规范

### 组合价值
- 🌍 Cesium 提供 3D 地球框架
- 🗺️ Mapbox 提供高质量底图样式
- 🏗️ 3D 建筑 + 精美地图 = 完美组合

---

## 🔗 集成方案

### 方案 1: MVTImageryProvider ⭐ 推荐

**项目**：[hongfaqiu/MVTImageryProvider](https://github.com/hongfaqiu/MVTImageryProvider) ⭐ 89

**原理**：在 Cesium 中渲染 Mapbox 矢量瓦片

**安装**：
```bash
npm install --save mvt-imagery-provider
```

**使用**：
```javascript
import * as Cesium from "cesium";
import MVTImageryProvider from 'mvt-imagery-provider';

const viewer = new Cesium.Viewer("cesiumContainer");

const provider = await MVTImageryProvider.fromUrl(
  'https://demotiles.maplibre.org/style.json',
  { accessToken: MAPBOX_TOKEN }
);

viewer.imageryLayers.addImageryProvider(provider);
```

**特性**：
- 支持 Mapbox 样式 JSON
- 支持 accessToken 认证
- 支持 pickFeatures 点击拾取
- 支持 256/512 瓦片尺寸
- 支持 WebMercator / Geographic 投影

---

### 方案 2: cesium-vector-provider

**项目**：[davenquinn/cesium-vector-provider](https://github.com/davenquinn/cesium-vector-provider) ⭐ 85

**特点**：将 Mapbox 矢量地图引入 Cesium 地球

---

### 方案 3: MapboxVectorTileImageryProvider

**项目**：[robbo1975/MapboxVectorTileImageryProvider](https://github.com/robbo1975/MapboxVectorTileImageryProvider) ⭐ 74

**特点**：实时渲染 Mapbox 样式矢量瓦片

---

### 方案 4: 相机同步

**项目**：[limzgiser/cesium-mapboxgl-syncamera](https://github.com/limzgiser/cesium-mapboxgl-syncamera) ⭐ 40

**特点**：MapboxGL 和 Cesium 相机同步

---

## 📦 核心 API

### MVTImageryProvider 选项

```typescript
type MVTImageryProviderOptions = {
  style: string | Resource | StyleSpecification;  // Mapbox 样式 URL
  accessToken?: string;                           // Mapbox Token
  transformRequest?: RequestTransformFunction;    // 请求转换
  tileSize?: number;                              // 瓦片尺寸 (256/512)
  maximumLevel?: number;                          // 最大层级 (默认 18)
  minimumLevel?: number;                          // 最小层级 (默认 0)
  showCanvas?: boolean;                           // 调试用
  enablePickFeatures?: boolean;                   // 启用点击拾取
  tilingScheme?: WebMercatorTilingScheme | GeographicTilingScheme;
};
```

---

## 💻 完整示例

### 基础 3D 地球 + Mapbox 底图

```javascript
import * as Cesium from 'cesium';
import MVTImageryProvider from 'mvt-imagery-provider';

// 创建 Cesium Viewer
const viewer = new Cesium.Viewer('cesiumContainer', {
  baseLayerPicker: false,
  geocoder: false,
  homeButton: false,
  sceneModePicker: false,
  selectionIndicator: false,
  timeline: false,
  navigationHelpButton: false
});

// 添加 Mapbox 样式图层
const provider = await MVTImageryProvider.fromUrl(
  'https://api.mapbox.com/styles/v1/mapbox/streets-v11/style.json',
  {
    accessToken: 'YOUR_MAPBOX_TOKEN',
    tileSize: 512,
    maximumLevel: 18
  }
);

viewer.imageryLayers.addImageryProvider(provider);

// 添加 3D 建筑
viewer.scene.primitives.add(Cesium.createOsmBuildings());
```

### 添加 3D Tiles

```javascript
// 加载 3D Tiles 数据集
const tileset = await Cesium.Cesium3DTileset.fromUrl(
  'https://example.com/tileset.json'
);
viewer.scene.primitives.add(tileset);

// 自动缩放到数据集
viewer.zoomTo(tileset);
```

### 添加地形

```javascript
// 添加全球地形
viewer.terrainProvider = await Cesium.CesiumTerrainProvider.fromIonAssetId(1);
```

---

## 🎨 常用 Mapbox 样式

| 样式 | URL 模板 |
|------|---------|
| **Streets** | `mapbox://styles/mapbox/streets-v11` |
| **Satellite** | `mapbox://styles/mapbox/satellite-v9` |
| **Satellite Streets** | `mapbox://styles/mapbox/satellite-streets-v11` |
| **Dark** | `mapbox://styles/mapbox/dark-v10` |
| **Light** | `mapbox://styles/mapbox/light-v10` |
| **Outdoors** | `mapbox://styles/mapbox/outdoors-v11` |

---

## 🔧 环境配置

```bash
# 创建项目
npm init -y

# 安装依赖
npm install cesium mvt-imagery-provider

# 或使用 Vite
npm create vite@latest my-map -- --template vanilla
cd my-map
npm install cesium mvt-imagery-provider
```

**Vite 配置** (vite.config.js)：
```javascript
import { defineConfig } from 'vite';
import cesium from 'vite-plugin-cesium';

export default defineConfig({
  plugins: [cesium()]
});
```

---

## 📊 性能对比

| 方案 | 渲染质量 | 性能 | 易用性 |
|------|---------|------|--------|
| MVTImageryProvider | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| cesium-vector-provider | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| MapboxVectorTileImageryProvider | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |

---

## 💡 使用场景

| 场景 | 说明 |
|------|------|
| **智慧城市** | 3D 建筑 + 精美底图 |
| **数字孪生** | BIM/CAD + 地理上下文 |
| **气象可视化** | 风场/温度 + 3D 地球 |
| **轨迹追踪** | GPS 轨迹 + 地形高程 |
| **城市规划** | 规划方案 + 现状地图 |

---

## 🌐 相关项目

| 项目 | Stars | 说明 |
|------|-------|------|
| wind-layer | ⭐ 693 | 风场可视化（支持 Mapbox） |
| mapwidget | ⭐ 252 | Jupyter 地图组件 |
| simple-gis-web | ⭐ 36 | Vue + Leaflet/Mapbox/Cesium |
| Cesium_Mapboxgl | ⭐ 5 | Vue + Cesium + ECharts + Mapbox |

---

## 🔗 资源

| 资源 | 链接 |
|------|------|
| CesiumJS | https://github.com/CesiumGS/cesium |
| Mapbox GL JS | https://github.com/mapbox/mapbox-gl-js |
| MVTImageryProvider | https://github.com/hongfaqiu/MVTImageryProvider |
| Cesium 文档 | https://cesium.com/learn/ |
| Mapbox 文档 | https://docs.mapbox.com/ |

---

## AI工程索引

相关笔记：
- [[INDEX_AI工程]] - AI工程知识索引
- [[YOLO+ByteTrack水流速度检测]] - CV 项目

---

*整理：知识库管理员 | 归档：2026-04-23*