CesiumJS + Resium Map Skeleton

Extensible map foundation built with CesiumJS + Resium, supporting inspection/fleet scenarios with layers, track replay, picking, and plugin-based tools.

Tech Stack

• Vite + React 18 + TypeScript
• CesiumJS + Resium for 3D globe rendering
• Zustand for state management
• Tailwind CSS for styling
• React Router v6 for routing
• Vitest for unit testing

Library Installation

When consuming as an npm package, install peer dependencies alongside:

pnpm add cesium-map-skeleton cesium react react-dom

Peer dependencies:

• cesium >= 1.100.0
• react >= 18.0.0
• react-dom >= 18.0.0

Basic Usage

import { createMapApp } from "cesium-map-skeleton";

const app = createMapApp();

// Initialize in a React component
await app.runtime.init(containerElement);
app.pickService.start();

// Add a layer
await app.layerService.addLayer({
  id: "satellite",
  type: "imagery",
  visible: true,
  status: "idle",
  options: { url: "https://..." },
});

// Listen to events
app.eventBus.on("pick.hit", (payload) => {
  console.log("Picked entity:", payload.id);
});

// Clean up
app.destroy();

Available Services

Service	Description
layerService	Layer lifecycle management (add, remove, reorder, retry)
cameraService	Camera flyTo queue with enqueue/replace/drop policies
pickService	Screen-space pick/hover event handling
interactionBroker	Priority-based pick event routing to plugins
trackService	GPS track replay with play/pause/seek/speed
coordinateTransformer	WGS84 / Cartesian3 coordinate conversion
sceneService	Scene mode (2D/3D/Columbus) and atmosphere control
exportService	Screenshot capture and GeoJSON export
clusterService	Entity clustering on data sources

SearchService is provided as an interface (ISearchService) with a TiandituGeocoder adapter.

Quick Start (Development)

# Install dependencies
pnpm install

# Copy environment variables
cp .env.example .env
# Edit .env with your tokens:
# - VITE_CESIUM_ION_TOKEN: Cesium Ion access token
# - VITE_TIANDITU_TOKEN: Tianditu API token

# Start development server
pnpm dev

# Run tests
pnpm test

# Type check
pnpm typecheck

# Build for production
pnpm build

Environment Variables

Variable	Description	Required
VITE_CESIUM_ION_TOKEN	Cesium Ion access token for terrain/imagery	Optional
VITE_TIANDITU_TOKEN	Tianditu API token	Required for Tianditu layers

Project Structure

src/
├── app/                    # Application bootstrap & routing
│   ├── bootstrap/          # createMapApp() factory
│   └── routes/             # Route definitions
├── core/map/               # Core map abstractions
│   ├── contracts/          # MapRuntime, LayerContract, PluginContract, EventContract,
│   │                       # StoreContract, ServiceContracts
│   ├── runtime/            # CesiumRuntime implementation & React lifecycle hook
│   ├── services/           # LayerService, CameraService, PickService, TrackService,
│   │                       # SceneService, ExportService, ClusterService, SearchService
│   ├── store/              # Zustand mapStore
│   └── utils/              # DisposeBag, MapEventBus, Logger
├── adapters/               # Platform-specific implementations
│   ├── cesium/layers/      # Imagery, Terrain, GeoJSON, 3DTiles, CZML controllers
│   ├── cesium/datasource/  # GeoJSON & CZML data source adapters
│   └── geocode/            # TiandituGeocoder
├── plugins/                # Plugin system
│   ├── measure/            # Distance & area measurement
│   ├── draw/               # Point/polyline/polygon drawing
│   └── replay/             # Track replay wrapper
├── features/               # Business pages
│   ├── inspection/         # Inspection map page
│   └── fleet/              # Fleet map page
└── shared/                 # Shared types & components
    ├── types/              # geo.ts, map.ts
    └── components/         # MapShell container

Routes

Path	Page	Description
/	Redirect	Redirects to /inspection
/inspection	InspectionMapPage	Tianditu satellite imagery
/fleet	FleetMapPage	Tianditu vector tiles

Documentation

• Architecture Overview
• API Reference
• Layer Guide
• Plugin Guide
• Research Report: UAV/Mobile Map Component (2026-02-22)
• Technical Spec: Map Core
• Sprint Backlog: Map Core AI Development Plan (10 Weeks)