cesiumDesign

geo-effect-kit

Framework-neutral Cesium effects for WebGIS dashboards, emergency command systems, 3D maps, and AI-assisted geospatial applications.

中文文档

Features

• Works with an existing Cesium Viewer.
• Framework-neutral TypeScript API.
• Reusable transform controls plus effects for radar scans, ripple spread, route flow, material polylines, fly lines, pipe flow, water surfaces, light walls, scan cones with optional smooth expansion, rectangular pushbroom sensor scans, shield domes, temperature fields, GIF fire billboards, scene weather, and post-processing.
• Common lifecycle API: update, show, hide, flyTo, destroy.
• Machine-readable manifests for AI agents.
• Optional MCP server for effect discovery and integration examples.

Install

pnpm add @ztgkzhaohao/geo-effect-kit cesium

Cesium is a peer dependency. The host project owns Cesium versioning, static assets, CESIUM_BASE_URL, and Viewer initialization.

Minimal Usage

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()

// Later, when the layer or page is removed:
radar.destroy()

Available Effects

Effect	Import	Use case
Transform gizmo	CesiumTransformGizmo	Configurable longitude/latitude/height movement, HPR rotation, axis and uniform scaling
Radar scan	createRadarScanEffect	Circular radar and warning scans
Ripple spread	createRippleSpreadEffect	Water, energy, and soft ripple expansion
Polyline flow	createPolylineFlowEffect	Dispatch routes, data links, migration paths
Material polyline	createMaterialPolylineEffect	Mars3D-style solid, outline, arrow, dash, texture, cross, and navigation lines with custom image materials
Fly line	createFlyLineEffect	High-altitude arcs, hub-spoke links, bidirectional routes
Pipe flow	createPipeFlowEffect	Water pipes and pressure flow
Water surface	createWaterSurfaceEffect	Rivers, lakes, flood surfaces, and directional Flow Type water
Light wall	createLightWallEffect	Security boundaries and protected areas
Scan cone	createScanConeEffect	Searchlights, sensors, cameras, and drones with optional smooth radius-and-length expansion
Pushbroom scan	createPushbroomScanEffect	Rectangular satellite, aircraft, drone, and directional-sensor swaths with line, curtain, or band scanning
Shield dome	createShieldDomeEffect	Protective domes and highlighted regions
Temperature field	createTemperatureFieldEffect	Risk surfaces and heat fields
Fire billboard	createFireBillboardEffect	GIF fire markers by longitude/latitude
Scene weather	createSceneWeatherEffect	Rain, snow, fog, lightning
Post process	createPostProcessEffect	Bloom, night vision, black-white, brightness, mosaic, depth of field

Scan cones keep their existing static behavior unless expansion is provided. The optional callback exposes live progress and dimensions:

const cone = createScanConeEffect(viewer, {
  center: { longitude: 116.391, latitude: 39.907 },
  lengthMeters: 6200,
  expansion: {
    maxRadiusMeters: 2200,
    cameraFollow: false,
    onFrame: (frame) => console.log(frame.progress, frame.radiusMeters),
  },
})

Pushbroom scans connect a sensor apex to a rectangular footprint. The scan moves in one direction and jumps back to the start without leaving a history trail:

import { createPushbroomScanEffect } from '@ztgkzhaohao/geo-effect-kit'

const pushbroom = createPushbroomScanEffect(viewer, {
  position: { longitude: 116.391, latitude: 39.907, height: 8000 },
  lengthMeters: 7600,
  swathWidthMeters: 3600,
  alongTrackDepthMeters: 1600,
  pitch: -72,
  scanMode: 'curtain',
  scanDurationMs: 2400,
  scanWidthMeters: 48,
})

pushbroom.update({ heading: 35, scanMode: 'band', scanWidthMeters: 160 })
pushbroom.pause()
pushbroom.resume()
pushbroom.destroy()

Position, orientation, dimensions, styles, and animation options update through three fixed Cesium Primitives using model matrices and uniforms. In requestRenderMode, frames are requested only while the effect is visible and running. onFrame and onCycle are lightweight observation callbacks and should not run expensive application work.

Documentation

• Transform gizmo
• Getting started
• Vite and Cesium assets
• React usage
• Vue usage
• AI agents and MCP
• Release process

Effect-level manifests and long-form effect notes live in:

• knowledge/effects
• knowledge/docs

Demo

Run locally:

pnpm install
pnpm --filter geo-effect-kit-demo dev

After GitHub Pages is enabled, the public demo will be available at:

https://tzxzhaohao.github.io/cesiumDesign/

AI Agent Usage

AI agents should prefer the structured knowledge files instead of reverse-engineering examples from the demo:

• Use knowledge/effects/*.effect.json for effect IDs, imports, options, methods, examples, and notes.
• Use knowledge/docs/*.md for effect-specific integration guidance.
• Use @ztgkzhaohao/geo-effect-kit-mcp when the agent supports MCP tools.

Start the MCP server:

npx @ztgkzhaohao/geo-effect-kit-mcp

Development

pnpm install
pnpm typecheck
pnpm test
pnpm build

License

MIT