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

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

// 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#controls-for-a-future-capture) enumerates reproducible conditions for cross‑platform benchmarking.

---

Lazy Loading Implementation Pattern

Heavy layers benefit from explicit user triggering:

// 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)	Baseline metrics, methodology, reproducibility controls
[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)	Weather effect calculations affecting render load
scripts/qa-perf.mjs	Automated regression testing
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) file documents reproducibility controls including viewport dimensions and device pixel ratio (DPR = 1) for consistent cross‑platform benchmarking.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}