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
• 1,584 instanced satellites with illumination logic
• 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 or a CDN.
• onTextureError (function): Called with the failing URL if a texture cannot be loaded.

The initializer returns { scene, camera, renderer, 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

All textures are imported inside the module; the Rollup build copies them into dist/textures and rewrites the URLs automatically, so consumers get working paths by default.

Development

npm install
npm run build          # Produces dist/ with bundled code and textures
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).
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.