Earth Visualization

Fully packaged real-time Earth visualization for the browser. Ships with the Three.js renderer, high-resolution textures, atmospheric shaders, and a complete Walker Delta satellite constellation - everything bundled so you can drop it into any project with a single dependency.

Features

• High-quality Earth shading with day/night transition, specular oceans, and bump-mapped terrain
• Animated cloud layer and additive atmosphere glow
• A configurable satellite shell (or several) rendered as sun-glinting points, with eclipse, scintillation and panel flares
• Animated laser routes hopping between satellites, with packets travelling along them
• Adaptive level of detail for smooth performance
• Bundled textures and Three.js runtime (no external asset hosting required)

Installation

npm install earth-visualization

or

yarn add earth-visualization

Usage

import initEarthVisualization from 'earth-visualization';

const container = document.getElementById('earth');

const { renderer, dispose } = initEarthVisualization(container, {
  autoResize: true,
  rendererOptions: {
    antialias: true
  }
});

// Call dispose() when you no longer need the visualization
// dispose();

Options

• autoResize (boolean, default true): Update the renderer when the window resizes.
• rendererOptions (object): Extra options forwarded to new THREE.WebGLRenderer().
• textures (object): Override URLs for any bundled texture (day, night, clouds, topography, specular, landOcean). Use this to swap in custom imagery.
• textureBaseUrl (string): Serve the bundled texture files from your own location (for example /earth-textures/). Only needed if the automatic resolution below does not suit your setup.
• shells (array): Satellite shells. Each entry is { altitudeKm, inclinationDeg, planes, satsPerPlane, phasing }. Default: one 55° shell at 800 km with 24 planes × 40 satellites. Add a second, higher entry to get long-haul routes that climb to it.
• lasers (object or false): Laser route settings, or false to disable. Keys: routes (simultaneous routes, default 3), maxHops (9), maxRange and maxRangeCrossShell (link reach in Earth radii, 0.42 / 0.6), lifetime ([min, max] seconds, [14, 24]), packetSpeed (hops per second, 2.2), widthPx (8), color ([r, g, b]).
• nightLightsIntensity (number, default 0): Strength of city lights on the night side. Off by default because they are far below a daylight exposure; 0.3 gives a subtle composite look.
• onTextureError (function): Called with the failing URL if a texture cannot be loaded.

The initializer returns { scene, camera, renderer, constellation, laserNetwork, dispose }.

Package Layout

dist/
  index.js          ESM build (minified + sourcemap)
  index.cjs         CommonJS build (minified + sourcemap)
  textures/         Copied texture assets
src/
  app.js            Visualization implementation
  index.js          Package entry (re-exports init)
  dev.js            Local demo bootstrapping
  index.html        Manual test page (expects bundler build)
  textures/         Source texture files
rollup.config.mjs   Build configuration

How textures are found

Textures ship in dist/textures, next to the bundle. The module resolves each one with new URL('./textures/…', import.meta.url), which bundlers such as webpack 5, Turbopack and Vite turn into a hashed asset they serve themselves, and which plain ESM in the browser resolves against the module's own URL. If a texture still fails to load, the module falls back to the same file on the jsDelivr CDN, pinned to the installed package version. You should not need to copy textures or pass URLs; onTextureError only fires when every candidate fails.

Development

npm install
npm run build          # Produces dist/ with bundled code and textures
npm run dev            # Rebuilds dist/ on every change to src/
npm pack               # Optional: inspect the tarball before publishing

For manual testing:

1. Run npm run build.
2. Serve the project root with any static server (for example npx http-server . -p 8080 -c-1).
3. Open http://localhost:8080/src/index.html.

That page loads src/dev.js, which imports the bundled module from dist/index.js and mounts the visualization into the #app element.

Publish Checklist

1. Update version in package.json.
2. Run npm run build and npm pack to verify the bundle contents.
3. Tag the release (git tag vX.Y.Z && git push --tags).
4. Publish: npm publish --access public.

License

MIT (c) 2025 Earth Visualization contributors. Includes Three.js (MIT) and bundled NASA imagery (public domain). Review the upstream licenses if you swap in alternate data.