# CesiumJS DataLayerManager Interface for Data Sources: Orchestrating Geospatial Layers in God's Eye View

> Master CesiumJS data layer management with the DataLayerManager interface. Easily enable, disable, and monitor geospatial data sources for a unified view.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: api-reference
- Published: 2026-08-30

---

**The `DataLayerManager` class in [`src/data/manager.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/manager.js) exposes a unified programmatic interface that orchestrates CesiumJS data layer lifecycles through methods like `enable()`, `disable()`, and `getStats()`, while normalizing external API feed states into consistent statuses such as `nominal`, `loading`, `degraded`, `stale`, `fallback`, or `unavailable`.**

God's Eye View (GEV) is a web-based geospatial visualization platform built on **CesiumJS** that aggregates live and static feeds—including flights, satellites, earthquakes, and CCTV—into a unified 3D globe. The **CesiumJS DataLayerManager interface for data sources** serves as the single source of truth for layer visibility, lifecycle management, and error handling, completely decoupling the Cesium rendering pipeline from network data logic.

## The DataLayerManager Contract and Core API

### Lifecycle Methods and Feed State Normalization

The manager implements a strict contract requiring every data layer module to expose `init`, `enable`, `disable`, `update`, `destroy`, and `getStats` methods. When consuming code calls `dataManager.enable('flights')`, the manager validates the request against the current **feed state**, triggers the layer's initialization pipeline, and abstracts provider-specific errors into UI-friendly statuses.

### Primary Interface Methods

The `DataLayerManager` exposes a minimal surface area for controlling data sources:

- **`enable(layerId, options?)`**: Validates the layer request, activates the rendering pipeline, adds Cesium primitives to the viewer, and initiates data refresh cycles.
- **`disable(layerId)`**: Hides the layer, stops periodic updates, cancels pending resource restores, and records the visibility intent.
- **`getStats(layerId)`**: Returns a normalized statistics object consumed by [`src/loadingFeedback.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/loadingFeedback.js) to render colored control-chips in the UI.
- **`isEnabled(layerId)`**: Reads the authoritative boolean visibility flag used by voice actions, UI widgets, and the render governor.
- **`getLayerLifecycleState(layerId)`**: Provides a full snapshot including `enabled`, `error`, and `managerRefreshError` flags for debugging.
- **`clearSelectedLayers()`**: Removes all user-enabled layers, preserving only the *basemap* and *style* layers.

## Decoupling CesiumJS from Data Logic

### Layer Module Architecture

The manager intentionally knows nothing about Cesium primitives. Instead, concrete implementations in [`src/data/flights.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/flights.js), [`src/data/satellites.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/satellites.js), and [`src/data/radio.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/radio.js) import Cesium APIs (such as `Cesium.CustomDataSource` and `Cesium.Cesium3DTileset`) and export the lifecycle contract. This separation allows the manager to orchestrate generic data flows while individual layers handle Cesium-specific entity creation and management of `viewer.scene.primitives` or `viewer.dataSources`.

### Viewer Integration in main.js

The Cesium viewer is instantiated in [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) and injected into the manager via `new DataLayerManager(viewer)`. When a layer is enabled, the manager delegates primitive creation to the layer module, which then adds entities to `viewer.dataSources` or `viewer.scene.primitives`. The manager tracks only metadata and visibility intent, ensuring that Cesium version-specific logic remains isolated within individual layer files.

## Voice Assistant Integration and Tool Definitions

### Mapping Voice Commands to Manager Methods

The voice assistant module in [`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js) translates natural language commands into programmatic API calls. The `set_layer_visibility` tool—formally described in the OpenAPI specification within [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js) (around line 5634)—directly invokes `DataLayerManager.enable()` or `disable()` based on parsed LLM output.

### Entity Tracking Across Layers

The `track_entity` action leverages the manager to select the appropriate layer (flights, military, AIS live vessels, or satellites) before attaching the Cesium camera to a specific entity's position. This demonstrates how the manager acts as the authoritative intermediary between voice-controlled UX and Cesium camera controls.

## Error Handling and Fallback Logic

### Normalized Feed States

When external APIs (OpenSky, FIRMS, OpenStreetMap) fail or timeout, [`src/data/manager.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/manager.js) normalizes the error into a `layerFeedState` enumeration. The UI layer in [`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js) renders these states as control-chips: **green** for `nominal`, **orange** for `degraded`, and **red** for `unavailable`.

### Automatic Fallback Mode

The manager automatically transitions layers to a **fallback** state—such as simulated traffic—when live feeds become stale or unreachable. This ensures continuous visualization without tearing down the underlying network connection or Cesium primitives, maintaining a smooth user experience under network instability.

## Implementation Examples

Enable the flights layer and query its operational status:

```javascript
// src/main.js initialization pattern
import { DataLayerManager } from './data/manager.js';
import { createCesiumViewer } from './renderGovernor.js';

const viewer = await createCesiumViewer('#cesiumContainer');
const dataManager = new DataLayerManager(viewer);

// Enable the layer
await dataManager.enable('flights');

// Query current state for UI feedback
const stats = dataManager.getStats('flights');
console.log('Flights layer feed state →', stats.status);

// Disable the layer
await dataManager.disable('flights');

```

Handle voice-assistant tool calls for layer visibility:

```javascript
// src/voice/gevActions.js handler pattern
async function handleSetLayerVisibility(args) {
  const { layerId, enabled } = args; // Parsed from LLM tool call
  if (enabled) {
    await dataManager.enable(layerId);
  } else {
    await dataManager.disable(layerId);
  }
  return { success: true, layerId, enabled };
}

```

Track the nearest aircraft to a geographic location:

```javascript
// Voice-controlled entity tracking
import { trackEntity } from './voice/gevActions.js';

async function trackNearestAircraft(place) {
  // Selects appropriate layer (flights → military) via manager
  await trackEntity({ place, nearest: true });
}

```

## Summary

- The `DataLayerManager` in [`src/data/manager.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/manager.js) provides a **unified interface** for enabling, disabling, and monitoring geospatial data sources without direct Cesium dependencies.
- Layer modules such as [`src/data/flights.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/flights.js) and [`src/data/satellites.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/satellites.js) implement the lifecycle contract and internally manage Cesium primitives like `Cesium.CustomDataSource`.
- The manager normalizes external API errors into discrete **feed states** (`nominal`, `degraded`, `fallback`, `unavailable`) that drive UI feedback chips.
- Voice assistant integration in [`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js) maps high-level commands like `set_layer_visibility` directly to manager methods.
- Automatic **fallback logic** ensures the visualization remains functional when live data sources fail.

## Frequently Asked Questions

### Where is the DataLayerManager class defined?

The `DataLayerManager` class is defined in [`src/data/manager.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/manager.js). This file contains the core orchestration logic, feed state definitions, and the public API surface consisting of `enable()`, `disable()`, `getStats()`, and related lifecycle methods.

### How does the manager handle CesiumJS primitives without importing Cesium?

The manager delegates all Cesium-specific operations to **layer modules** (e.g., [`src/data/flights.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/flights.js)). Each module imports Cesium APIs independently and manages its own `Cesium.CustomDataSource` or `Cesium.Cesium3DTileset` instances, adding them to the `viewer` reference passed during manager initialization. This architectural separation keeps the manager agnostic to Cesium implementation details.

### What feed states indicate layer health in the manager?

The manager uses six normalized states: `nominal` indicates healthy operation, `loading` shows initialization in progress, `degraded` signals partial data loss, `stale` indicates outdated data, `fallback` means simulated data is active, and `unavailable` represents complete failure. These states are stored in `layerFeedState` within [`src/data/manager.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/data/manager.js) and consumed by [`src/loadingFeedback.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/loadingFeedback.js) for UI rendering.

### How does the voice assistant interact with the DataLayerManager?

The voice assistant in [`src/voice/gevActions.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevActions.js) translates natural language commands into programmatic calls. Tool definitions in [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js) (around line 5634) describe available actions like `set_layer_visibility`, which the LLM uses to generate JSON payloads. The assistant then invokes `DataLayerManager.enable()` or `disable()` with the specified `layerId`, making the manager the single integration point for voice-controlled layer management.