Earth — Orbital Observatory

A cinematic WebGL2 Earth viewer using React 19, strict TypeScript, Three.js, React Three Fiber, Zustand, and custom GLSL surface and atmosphere shaders.

Run

pnpm install
pnpm dev

Production validation:

pnpm check

The viewer uses locally bundled NASA Blue Marble geography, NASA Black Marble night lights, NOAA ETOPO 2022 signed global elevation, and selective Copernicus GLO-30 mountain detail. Terrain is real displaced geometry with multi-scale elevation-derived normals. Its heroic RPG-scale presentation holds relief at 36× during close inspection and rises smoothly to 72× from orbit, making mountain systems and valleys central visual features while retaining their source-derived shapes. Selectable modes include 2K Ultra Low, 4K Low, 6K Medium, 8K High, 12K Ultra, and balanced Auto selection; selected mountain regions resolve to approximately 90 m without runtime network access.

The globe includes twelve fictional, faction-ready city icons distributed across the current geographic anchor points. Selecting an icon and entering city view opens a distinct, angled bird's-eye 3D city with terrain, streets, sidewalks, varied-height buildings, rooftops, parks, trees, water, traffic markings, and civic landmarks. Each city uses a different non-circular urban structure; no faction ownership or city-management mechanics are implemented yet.

Rebuilding terrain assets

Terrain textures are reproducible from a global EPSG:4326 GeoTIFF containing elevations in meters. The source file is deliberately not committed.

pnpm assets:terrain -- C:/path/to/global-elevation.tif
pnpm assets:earth
pnpm assets:terrain:regions
pnpm assets:cities
pnpm assets:validate

The generator accepts GEBCO, Copernicus, or ETOPO GeoTIFF inputs, packs signed height into two lossless channels, retains the local ocean classification in the third channel, and enforces the 75 MB shipped terrain budget during validation.

Drag to orbit, scroll or pinch to zoom, and click the surface to inspect coordinates. Space pauses time, R resets time, F enters fullscreen, and Escape closes panels. Search uses a bundled offline location index.

WebGL2 and hardware acceleration are required. The 8K texture set consumes substantially more GPU memory after decompression than its on-disk JPEG/PNG size; Auto selection uses device memory, CPU cores, mobile state, and WebGL texture limits, and may adjust pixel density to protect frame rate.