# cesium-mcp-bridge

> 浏览器 SDK — 嵌入到 CesiumJS 应用中，通过 WebSocket 接收命令。

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

## 安装

```bash
npm install cesium-mcp-bridge
```

**Peer 依赖**：`cesium@~1.143.0`

## 初始化

```js
import { CesiumBridge } from 'cesium-mcp-bridge'

const viewer = new Cesium.Viewer('cesiumContainer')
const bridge = new CesiumBridge(viewer)
```

## 命令（60 个）

### 视图控制

| 命令 | 描述 | 关键参数 |
|------|------|----------|
| `flyTo` | 相机飞行动画到指定位置 | `longitude`, `latitude`, `height`, `heading`, `pitch`, `roll`, `duration` |
| `setView` | 立即设置相机位置 | `longitude`, `latitude`, `height`, `heading`, `pitch`, `roll` |
| `getView` | 获取当前相机状态 | — |
| `zoomToExtent` | 缩放到地理范围 | `west`, `south`, `east`, `north` |
| `saveViewpoint` | 保存当前视角为命名书签 | `name` |
| `loadViewpoint` | 恢复已保存的视点书签 | `name`, `duration` |
| `listViewpoints` | 列出所有视点书签 | — |
| `exportScene` | 导出场景为结构化 JSON 快照 | — |

### 实体

| 命令 | 描述 | 关键参数 |
|------|------|----------|
| `addMarker` | 添加点标记 | `longitude`, `latitude`, `label`, `color`, `size` |
| `addLabel` | 添加文字标注 | `data`, `field`, `style` |
| `addPolyline` | 添加折线（路径/线段） | `coordinates`, `color`, `width`, `clampToGround` |
| `addPolygon` | 添加多边形区域 | `coordinates`, `color`, `outlineColor`, `opacity`, `extrudedHeight` |
| `addModel` | 放置 3D 模型 (glTF/GLB) | `longitude`, `latitude`, `url`, `scale`, `heading`, `pitch`, `roll` |
| `updateEntity` | 更新实体属性 | `entityId`, `position`, `color`, `label`, `scale`, `show` |
| `removeEntity` | 移除单个实体 | `entityId` |
| `batchAddEntities` | 批量添加多个实体 | `entities`（类型化定义数组） |
| `queryEntities` | 搜索/筛选场景中的实体 | `name`, `type`, `bbox` |
| `getEntityProperties` | 获取实体的所有属性 | `entityId` |

### 图层管理

| 命令 | 描述 | 关键参数 |
|------|------|----------|
| `addGeoJsonLayer` | 加载 GeoJSON 数据 | `url` 或 `data`, `name`, `style` |
| `addGeoJsonPrimitive` | 使用 Primitive 加载大规模 GeoJSON | `url` 或 `data`, `name`, `allowPicking` |
| `listLayers` | 列出所有已加载图层 | — |
| `removeLayer` | 按 ID 移除图层 | `layerId` |
| `clearAll` | 移除所有图层、实体和数据源 | — |
| `setLayerVisibility` | 显示/隐藏图层 | `layerId`, `visible` |
| `updateLayerStyle` | 修改图层样式 | `layerId`, `layerStyle`, `imageryStyle`, `primitiveStyle`, `tileStyle` |
| `getLayerSchema` | 获取图层属性字段结构 | `layerId` |
| `setBasemap` | 切换底图影像 | `provider`, `url` |

### 高级相机

| 命令 | 描述 | 关键参数 |
|------|------|----------|
| `lookAtTransform` | 环绕式相机注视 | `longitude`, `latitude`, `height`, `heading`, `pitch`, `range` |
| `startOrbit` | 开始相机环绕旋转 | `speed`, `direction` |
| `stopOrbit` | 停止环绕动画 | — |
| `setCameraOptions` | 配置相机控制器 | `enableRotate`, `enableZoom`, `enableTilt` |

### 扩展实体类型

| 命令 | 描述 | 关键参数 |
|------|------|----------|
| `addBillboard` | 添加图片图标 | `longitude`, `latitude`, `image`, `scale` |
| `addBox` | 添加 3D 盒体 | `position`, `dimensions`, `material` |
| `addCorridor` | 添加走廊 | `positions`, `width`, `material` |
| `addCylinder` | 添加圆柱体/圆锥体 | `position`, `length`, `topRadius`, `bottomRadius` |
| `addEllipse` | 添加椭圆 | `position`, `semiMajorAxis`, `semiMinorAxis` |
| `addRectangle` | 添加矩形 | `west`, `south`, `east`, `north`, `material` |
| `addWall` | 添加墙体 | `positions`, `maximumHeights`, `minimumHeights` |

### 动画

| 命令 | 描述 | 关键参数 |
|------|------|----------|
| `createAnimation` | 创建路径动画 | `entityId`, `waypoints`, `model` |
| `controlAnimation` | 播放/暂停动画 | `entityId`, `action` |
| `removeAnimation` | 删除动画实体 | `entityId` |
| `listAnimations` | 列出活跃动画 | — |
| `updateAnimationPath` | 更新路径可视属性 | `entityId`, `show`, `width`, `color` |
| `trackEntity` | 相机追踪实体 | `entityId` |
| `controlClock` | 配置时钟 | `startTime`, `stopTime`, `multiplier` |
| `setGlobeLighting` | 地球光照控制 | `enableLighting`, `enableFog` |

### 3D 场景

| 命令 | 描述 | 关键参数 |
|------|------|----------|
| `load3dTiles` | 加载 3D Tileset | `url` 或 `ionAssetId`, `name`, `maximumScreenSpaceError` |
| `load3dGaussianSplat` | 加载 3D 高斯泼溅数据集 | `url`, `name`, `maximumScreenSpaceError` |
| `loadTerrain` | 设置地形提供者 | `url`, `provider` |
| `loadImageryService` | 添加影像图层 | `url`/`serviceType` 或 `ionAssetId`, `name` |
| `loadCzml` | 加载 CZML 时间动态数据 | `data` 或 `url`, `name` |
| `loadKml` | 加载 KML/KMZ 数据 | `data` 或 `url`, `name` |
| `setEdgeDisplayMode` | 设置 3D Tiles 表面/边缘显示模式 | `tilesetId`, `mode` |

### 交互

| 命令 | 描述 | 关键参数 |
|------|------|----------|
| `screenshot` | 截取当前视图 | `width`, `height`, `format` |
| `highlight` | 高亮要素 | `layerId`, `featureId`, `color` |
| `measure` | 测量距离或面积 | `type`, `coordinates` |

### 其他

| 命令 | 描述 | 关键参数 |
|------|------|----------|
| `playTrajectory` | 沿路径播放动画 | `positions`, `duration`, `loop` |
| `addHeatmap` | 创建热力图可视化 | `points`, `name`, `radius`, `gradient` |

### 场景

| 命令 | 描述 | 关键参数 |
|------|------|----------|
| `setSceneOptions` | 配置场景环境 | `fogEnabled`, `shadowsEnabled`, `sunShow`, `backgroundColor` |
| `setPostProcess` | 配置后处理效果 | `bloom`, `ambientOcclusion`, `fxaa` |

## 两种调用方式

### 方式一：类型安全方法

```typescript
const result = await bridge.flyTo({
  longitude: 116.4,
  latitude: 39.9,
  height: 5000,
  duration: 2,
})
```

### 方式二：JSON 命令分发

```typescript
const result = await bridge.execute({
  action: 'flyTo',
  params: {
    longitude: 116.4,
    latitude: 39.9,
    height: 5000,
    duration: 2,
  },
})
```

## 事件

```typescript
bridge.on('layerAdded', (layer) => console.log('图层已添加:', layer))
bridge.on('layerRemoved', (layerId) => console.log('已移除:', layerId))
bridge.on('error', (err) => console.error('Bridge 错误:', err))
```

## TypeScript 类型

```typescript
import type {
  BridgeCommand,
  BridgeResult,
  FlyToParams,
  SetViewParams,
  AddGeoJsonLayerParams,
  AddHeatmapParams,
  Load3dTilesParams,
  PlayTrajectoryParams,
  LayerInfo,
  HighlightParams,
  // 相机
  LookAtTransformParams,
  StartOrbitParams,
  SetCameraOptionsParams,
  // 扩展实体类型
  AddBillboardParams,
  AddBoxParams,
  AddCorridorParams,
  AddCylinderParams,
  AddEllipseParams,
  AddRectangleParams,
  AddWallParams,
  MaterialSpec,
  MaterialInput,
  OrientationInput,
  PositionDegrees,
  // 动画
  CreateAnimationParams,
  ControlAnimationParams,
  RemoveAnimationParams,
  UpdateAnimationPathParams,
  TrackEntityParams,
  ControlClockParams,
  SetGlobeLightingParams,
  AnimationWaypoint,
  AnimationInfo,
  // 图层 Schema 与样式
  GetLayerSchemaParams,
  LayerSchemaResult,
  LayerSchemaField,
  UpdateLayerStyleParams,
  // 场景
  SetSceneOptionsParams,
  SetPostProcessParams,
  // 数据格式
  LoadCzmlParams,
  LoadKmlParams,
  // 交互
  MeasureParams,
} from 'cesium-mcp-bridge'
```