内容
# 地理效果工具包
适用于WebGIS仪表盘、应急指挥系统、三维地图和AI辅助地理空间应用的框架无关的Cesium效果。
[中文文档](./README.zh-CN.md)
## 特性
- 与现有的Cesium `Viewer`配合使用。
- 框架无关的TypeScript API。
- 可重用的效果，包括雷达扫描、涟漪扩散、飞行线路、管道流动、水面、灯光墙、扫描锥、盾牌穹顶、温度场、GIF火灾广告牌、场景天气、后期处理和路线流动。
- 通用的生命周期API：`update`、`show`、`hide`、`flyTo`、`destroy`。
- 机器可读的清单，适用于AI代理。
- 可选的MCP服务器，用于效果发现和集成示例。
## 安装
```bash
pnpm add @ztgkzhaohao/geo-effect-kit cesium
```
Cesium是一个对等依赖。宿主项目拥有Cesium的版本控制、静态资源、`CESIUM_BASE_URL`和`Viewer`初始化。
## 最简用法
```ts
import 'cesium/Build/Cesium/Widgets/widgets.css'
import { Viewer } from 'cesium'
import { createRadarScanEffect } from '@ztgkzhaohao/geo-effect-kit'
const viewer = new Viewer('cesiumContainer')
const radar = createRadarScanEffect(viewer, {
center: { longitude: 116.391, latitude: 39.907 },
radiusMeters: 22000,
color: '#36d6ff',
scanDurationMs: 3600,
})
radar.flyTo()
// 稍后，当图层或页面被移除时：
radar.destroy()
```
## 可用效果
| 效果 | 导入 | 用例 |
| --- | --- | --- |
| 雷达扫描 | `createRadarScanEffect` | 圆形雷达和警告扫描 |
| 涟漪扩散 | `createRippleSpreadEffect` | 水、能量和软涟漪扩张 |
| 线条流动 | `createPolylineFlowEffect` | 调度路线、数据链接、迁移路径 |
| 飞行线路 | `createFlyLineEffect` | 高空弧线、中心-辐射式链接、双向路线 |
| 管道流动 | `createPipeFlowEffect` | 水管和压力流动 |
| 水面 | `createWaterSurfaceEffect` | 河流、湖泊、洪水表面和定向流动类型的水 |
| 灯光墙 | `createLightWallEffect` | 安全边界和保护区域 |
| 扫描锥 | `createScanConeEffect` | 探照灯、传感器、相机、无人机 |
| 盾牌穹顶 | `createShieldDomeEffect` | 保护穹顶和突出区域 |
| 温度场 | `createTemperatureFieldEffect` | 风险表面和热场 |
| 火灾广告牌 | `createFireBillboardEffect` | 经纬度GIF火灾标记 |
| 场景天气 | `createSceneWeatherEffect` | 雨、雪、雾、闪电 |
| 后期处理 | `createPostProcessEffect` | 光晕、夜视、黑白、亮度、马赛克、景深 |
## 文档
- [快速入门](./docs/getting-started.md)
- [Vite和Cesium资源](./docs/vite-cesium.md)
- [React用法](./docs/react.md)
- [Vue用法](./docs/vue.md)
- [AI代理和MCP](./docs/ai-agents.md)
- [发布流程](./docs/release.md)
效果级别的清单和长格式效果说明位于：
- [`knowledge/effects`](./knowledge/effects)
- [`knowledge/docs`](./knowledge/docs)
## 演示
在本地运行：
```bash
pnpm install
pnpm --filter geo-effect-kit-demo dev
```
GitHub Pages启用后，公共演示将在以下地址可用：
```text
https://tzxzhaohao.github.io/cesiumDesign/
```
## AI代理用法
AI代理应优先使用结构化知识文件，而不是从演示中反向工程示例：
- 使用`knowledge/effects/*.effect.json`获取效果ID、导入、选项、方法、示例和说明。
- 使用`knowledge/docs/*.md`获取特定于效果的集成指南。
- 当代理支持MCP工具时，使用`@ztgkzhaohao/geo-effect-kit-mcp`。
启动MCP服务器：
```bash
npx @ztgkzhaohao/geo-effect-kit-mcp
```
## 开发
```bash
pnpm install
pnpm typecheck
pnpm test
pnpm build
```
## 许可证
MIT
