# Performance Considerations for Gods‑Eye‑View: Optimization Guide for Cesium 3D Rendering

> Optimize Gods-Eye-View Cesium 3D rendering with our guide. Explore startup latency, layer activation, JS heap, frame rates, live data, and camera focus for peak performance.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: performance
- Published: 2026-09-05

---

**Gods‑Eye‑View (GEV) performance depends on six key factors: startup latency, cold layer activation costs, JavaScript heap pressure, frame‑rate stability under visual effects, live data source handling, and camera focus policies.**

Gods‑Eye‑View is a Cesium‑based web application that renders multiple live data layers—CCTV feeds, flight tracking, radio transmissions, submarine cables, and more—in a single 3D scene. Heavy data visualization creates specific bottlenecks that developers must address. This guide examines the performance considerations for Gods‑Eye‑View drawn from the formal baseline documented in [[`docs/PERFORMANCE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/PERFORMANCE.md)](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/PERFORMANCE.md), captured on an Apple M5 GPU with Chrome 150 using the ANGLE Metal rendering path.

---

## Startup Latency and Initial Data Settlement

GEV's time-to-interactive splits into two phases. **App ready** occurs at approximately **605 ms** median. **Initial data settlement**—when all default layers finish loading—takes roughly **1.86 seconds**.

The gap between these metrics reveals a critical optimization point. The rendering pipeline initializes quickly, but blocking data fetches extend perceived startup time.

To reduce startup latency:

- **Defer non‑essential layers** until after the first frame renders
- **Enable HTTP caching** for static assets (the baseline measurement assumes cache‑disabled conditions)
- **Lazy‑load heavy datasets** such as CCTV city networks or submarine cable geometries

---

## Cold Layer Activation Costs

Each layer incurs a one‑time **activation cost** when first enabled. These costs vary dramatically by data density:

| Layer | Activation Time | Heap Impact |
|-------|-----------------|-------------|
| CCTV city | ~19 s | High object count |
| Space Missions | ~3.6 s | Moderate |
| Submarine cables | Significant | Up to ~412 MiB peak |

The JavaScript heap spikes during activation of dense layers. The worst‑case observed heap reaches **~412 MiB**, which risks garbage‑collection pauses that manifest as frame‑rate stutters.

Implementation strategies from the source code:

- **Chunked loading**: Split layer data into batches with progress indication
- **Worker offloading**: Move parsing and geometry construction to Web Workers
- **Post‑activation pruning**: Release temporary buffers once entities are instantiated

---

## JavaScript Heap Pressure and GC Stability

Persistent heap growth threatens smooth rendering. The `window.performance.memory` API provides runtime monitoring. When heap approaches device limits, **entity pooling** and **aggressive culling** of off‑screen objects prevent catastrophic collection pauses.

Key file reference: [[`src/worldFocus.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/worldFocus.js)](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/worldFocus.js) manages entity lifecycle around focus operations, offering hooks for memory‑conscious cleanup.

---

## Frame‑Rate Stability Under Visual Load

Most static layers sustain **60 FPS**. Stress conditions reveal performance cliffs:

- **Detection layers at 100% density**: ~34 FPS
- **Visual post‑processing styles** (FLIR, Noir, Snow): high‑40s FPS
- **Normal style**: Full 60 FPS maintained

The performance considerations for Gods‑Eye‑View deployments targeting low‑end hardware converge on one recommendation: **default to the "Normal" visual style** and expose FLIR, Noir, and Snow as optional toggles. Detection layers should implement density caps based on `viewer.scene.frameState` metrics.

---

## Live Source Handling and Streaming Costs

Continuous data feeds create sustained overhead:

| Source | Activation | Frame‑Rate Impact | Coverage |
|--------|-----------|-------------------|----------|
| NASA FIRMS | 30 s | ~32 FPS | Thermal anomalies |
| AISStream | 6.4 s | Variable | Vessel tracking |
| TomTom | 70% condition | — | Traffic flow |

These live sources update dynamic objects every frame. Without intervention, accumulated entities degrade performance over session duration.

Effective throttling strategies:

- **Rate‑limit updates** to ≤1 Hz for non‑critical feeds
- **Spatial culling**: Remove entities outside the camera frustum
- **Temporal decay**: Fade and remove stale data points

---

## Camera Focus Policy and Validation

The [[`src/worldFocus.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/worldFocus.js)](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/worldFocus.js) module implements critical safeguards through `isValidWorldFocusTarget`. This validation prevents the camera system from pursuing invalid or excessively distant positions that would trigger long‑duration `flyTo` operations and unnecessary redraws.

### Using the Focus API Correctly

```javascript
// Request a focus on a vessel, respecting validation and camera policy
import {
  requestWorldFocus,
  registerWorldFocusRequestListener,
  routeWorldFocusRequest,
  flyToWorldTarget,
} from './src/worldFocus.js';

// Set up a listener that will execute an explicit focus routine
const dispose = registerWorldFocusRequestListener(window, event => {
  routeWorldFocusRequest(event, (detail, fly) => {
    // Custom UI logic can be added here (e.g., show a loading spinner)
    return fly(); // delegate to the default fly implementation
  }, (detail) => flyToWorldTarget(viewer, detail));
});

// When the user clicks a vessel icon:
const vesselDetail = {
  kind: 'vessel',
  id: 'flight‑1234',
  position: new Cesium.Cartesian3(1e6, 2e6, 3e6),
  durationSec: 2.0,
};
requestWorldFocus(vesselDetail); // dispatches the focus event

```

Always route focus requests through `requestWorldFocus` rather than calling Cesium's `flyTo` directly. The validation layer in `isValidWorldFocusTarget` screens for:

- Finite, valid Cartesian coordinates
- Reasonable distance bounds from current camera position
- Existence of target entity in scene graph

---

## Hardware and Browser Dependencies

The published baseline assumes:

- **GPU**: Apple M5 (Metal via ANGLE)
- **Browser**: Chrome 150
- **Viewport**: Matched DPI (`DPR = 1`)

Performance varies significantly across Windows, different GPU architectures, and high‑DPI displays. The **Controls for a future capture** section in [[`docs/PERFORMANCE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/PERFORMANCE.md)](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/PERFORMANCE.md#controls-for-a-future-capture) enumerates reproducible conditions for cross‑platform benchmarking.

---

## Lazy Loading Implementation Pattern

Heavy layers benefit from explicit user triggering:

```javascript
// Lazy‑load a heavy layer after user interaction
import { loadCCTVLayer } from './tools/streetview-panorama.mjs';

document.getElementById('load-cctv').addEventListener('click', async () => {
  const start = performance.now();
  await loadCCTVLayer(); // heavy activation (≈ 19 s in baseline)
  console.log('CCTV layer loaded in', (performance.now() - start) / 1000, 's');
});

```

This pattern converts mandatory startup cost into optional latency, keeping the initial interactive window under one second.

---

## Key Files for Performance Optimization

| File | Purpose |
|------|---------|
| [[`docs/PERFORMANCE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/PERFORMANCE.md)](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/PERFORMANCE.md) | Baseline metrics, methodology, reproducibility controls |
| [[`src/worldFocus.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/worldFocus.js)](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/worldFocus.js) | Focus validation, camera routing, entity lifecycle |
| [[`src/weatherEffectsMath.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/weatherEffectsMath.js)](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/weatherEffectsMath.js) | Weather effect calculations affecting render load |
| [`scripts/qa-perf.mjs`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/scripts/qa-perf.mjs) | Automated regression testing |
| [`tools/cesium-render.mjs`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/tools/cesium-render.mjs) | Cesium initialization with ANGLE Metal path |

---

## Summary

- **Startup latency**: ~605 ms app‑ready, ~1.86 s settlement; reduce by lazy‑loading layers
- **Cold activation**: CCTV city costs ~19 s; chunk data and show progress
- **Heap ceiling**: ~412 MiB observed; monitor `window.performance.memory` and prune aggressively
- **Frame‑rate floor**: Detection layers hit ~34 FPS; prefer "Normal" style for hardware limits
- **Live sources**: NASA FIRMS sustains ~32 FPS; throttle to ≤1 Hz and cull off‑screen
- **Camera policy**: Always validate targets through `isValidWorldFocusTarget` before flying

---

## Frequently Asked Questions

### What is the typical startup time for Gods‑Eye‑View?

Median startup time is approximately **605 milliseconds** until the application becomes interactive, with full initial data settlement requiring roughly **1.86 seconds**. These metrics assume cache‑disabled conditions; enabling HTTP caching and deferring heavy layer loads can significantly improve perceived performance.

### Which layers have the highest activation cost?

The **CCTV city layer** incurs the steepest cold activation cost at approximately **19 seconds**, followed by Space Missions at **3.6 seconds**. Layers with dense geometry like submarine cables also spike JavaScript heap usage to **~412 MiB**, risking garbage‑collection pauses.

### How do visual styles affect frame rate?

The **Normal** style maintains **60 FPS** on baseline hardware. **FLIR, Noir, and Snow** post‑processing styles reduce frame rates to the high‑40s FPS. Detection layers at full density drop performance to approximately **34 FPS**, making style selection critical for low‑end deployments.

### What hardware was used for the performance baseline?

The published baseline was captured on an **Apple M5 GPU** running **Chrome 150** with the **ANGLE Metal** rendering path. The [[`docs/PERFORMANCE.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/PERFORMANCE.md)](https://github.com/bilawalsidhu/gods-eye-view/blob/main/docs/PERFORMANCE.md) file documents reproducibility controls including viewport dimensions and device pixel ratio (`DPR = 1`) for consistent cross‑platform benchmarking.