Spacekit

Javascript library for 3D space visualizations

3D
typpo/spacekittyppo.github.io/spacekit/

README

spacekit


Spacekit is a JavaScript library for creating interactive 3D space visualizations - whether of the Earth/moon system, solar system, or beyond.

See the full documentation

Note that this library is a work in progress and the API might change!

Usage


Install via npm:

  1. ```
  2. npm install spacekit.js
  3. ```

And then use require or import:

  1. ```js
  2. const Spacekit = require('spacekit.js');
  3. // or
  4. import Spacekit from 'spacekit.js';
  5. ```

You can also download a raw build or use the latest build in a script tag:
  1. ```html
  2. <script src="https://typpo.github.io/spacekit/build/spacekit.js"></script>
  3. ```

Terminology and components


Simulation: the main container for your visualization.  A simulation is comprised by a Camera plus whatever you choose to put in it. See documentation for full options.
  1. ```javascript
  2. const sim = new Spacekit.Simulation(document.getElementById('my-container'), {
  3. // Required
  4. basePath: '../path/to/asset',
  5. // Optional
  6. camera: {
  7.    initialPosition: [0, -10, 5],
  8.    enableDrift: false,
  9. },
  10. debug: {
  11.    showAxes: false,
  12.    showGrid: false,
  13.    showStats: false,
  14. },
  15. });
  16. ```

Skybox: the image background of the visualization.  The "universe" of the visualization is contained within a large sphere, so "skysphere" may be a better (less conventional) way to describe it.  Some skybox assets are provided, including starry milky way background from ESA and NASA Tycho. See documentation for full preset options.
  1. ```javascript
  2. // Use an existing skybox preset.
  3. const skybox = sim.createSkybox(Spacekit.SkyboxPresets.NASA_TYCHO);

  5. // Add a skybox preset
  6. const skybox = sim.createSkybox({
  7.   textureUrl: '../path/to/image.png'
  8. });
  9. ```

Stars: an alternative to a skybox.  Instead of showing an image, this class loads real star data and positions the stars accordingly in the simulation.  Usually this is more performant but less visually stunning.
  1. ```javascript
  2. // Use an existing skybox preset.
  3. const skybox = sim.createStars({minSize /* optional */: 0.75 /* default */});

  5. // Add a skybox preset
  6. const skybox = sim.createSkybox({
  7.   textureUrl: '../path/to/image.png'
  8. });
  9. ```

SpaceObject: an object that can be added to the visualization (SpaceObjects can sometimes be referred to as simply "Object").  SpaceObjects can orbit, rotate, etc.  Subclasses include RotatingObject (has a defined spin axis), ShapeObject (has a 3D shapefile), and SphereObject (is spherical, like the Earth).
  1. ```javascript
  2. // Create objects using presets. The presets include scientific ephem params and/or position.
  3. const sun = viz.createObject('sun', Spacekit.SpaceObjectPresets.SUN);
  4. viz.createObject('mercury', Spacekit.SpaceObjectPresets.MERCURY);
  5. viz.createObject('venus', Spacekit.SpaceObjectPresets.VENUS);

  7. // Create a stationary object at [3, 1, -5] position.
  8. const obj = viz.createObject('myobj', {
  9.   position: [3, 1, -5],
  10. };

  12. // Create an object that orbits.

  14. // Ephem is a class representing Kepler ephemerides, which defines the trajectory of astronomical objects as well
  15. // as artificial satellites in the sky, i.e., the position (and possibly velocity) over time.
  16. const ephem = new Spacekit.Ephem({
  17.   epoch: 2458600.5,
  18.   a: 5.38533,
  19.   e: 0.19893,
  20.   i: 22.11137,
  21.   om: 294.42992,
  22.   w: 314.28890,
  23.   ma: 229.14238,
  24. }, 'deg');

  26. const asteroid = sim.createObject('Asteroid Aci', {
  27.   ephem,
  28. });

  30. // Create a shape object
  31. const obj = viz.createShape('myobj', {
  32.   position: [3, 1, -5],
  33.   shape: {
  34.     // Example shape file -
  35.     // http://astro.troja.mff.cuni.cz/projects/asteroids3D/web.php?page=db_asteroid_detail&asteroid_id=1046
  36.     shapeUrl: '../path/to/shape.obj', // Cacus
  37.   },
  38.   rotation: {
  39.     lambdaDeg: 251,
  40.     betaDeg: -63,
  41.     period: 3.755067,
  42.     yorp: 1.9e-8,
  43.     phi0: 0,
  44.     jd0: 2443568.0,
  45.   },
  46.   debug: {
  47.     showAxes: true,
  48.   },
  49. });

  51. // Create a sphere object
  52. sim.createSphere('earth', {
  53.   textureUrl: './earth_66mya.jpg',
  54.   radius: 2 /* default to 1 */
  55.   debug: {
  56.     showAxes: true,
  57.   },
  58. });
  59. ```

KeplerParticles: an optimized class for creating many particles that follow Kepler orbits.  These particles don't have a specific shape or size.  Instead, they share a 2D texture.  This is useful for when you want to show many objects at once, such as the asteroid belt.

Dependencies


Spacekit relies on some image and data assets that are not included in the Javascript file.

By default, these dependencies are hosted on the spacekit site (typpo.github.io/spacekit).  If you want to host these assets yourself, you can set the Simulation's basePath parameter to a folder that contains these files:

  - Spacekit asset directory
  - Spacekit data directory

For example:

  1. ```
  2. const viz = new Spacekit.Simulation({
  3.   basePath: 'https://mysite.com/static/spacekit',
  4. });
  5. ```

If you want to contribute to this project, you will also need to install Python (2.7 or 3).

Running an Example


Running ./server.sh will start a basic Python webserver.  Go to http://localhost:8001/examples/index.html to load a simple example.

If you're making changes to the code, run yarn build to update the build outputs.  yarn build:watch will continuously watch for your changes and update the build and also host a server on localhost:8001 (so you don't have to start the Python server separately).

Usage


See the examples directory for full usage examples.  For now, here's some example code that will build an interactive visualization of a couple planets:

  1. ```javascript
  2. // Create the visualization and put it in our div.
  3. const viz = new Spacekit.Simulation(document.getElementById('main-container'), {
  4.   assetPath: '../src/assets',
  5. });

  7. // Create a skybox using NASA TYCHO artwork.
  8. const skybox = viz.createSkybox(Spacekit.SkyboxPresets.NASA_TYCHO);

  10. // Create our first object - the sun - using a preset space object.
  11. const sun = viz.createObject('sun', Spacekit.SpaceObjectPresets.SUN);

  13. // Then add some planets
  14. viz.createObject('mercury', Spacekit.SpaceObjectPresets.MERCURY);
  15. viz.createObject('venus', Spacekit.SpaceObjectPresets.VENUS);
  16. viz.createObject('earth', Spacekit.SpaceObjectPresets.EARTH);
  17. viz.createObject('mars', Spacekit.SpaceObjectPresets.MARS);
  18. viz.createObject('jupiter', Spacekit.SpaceObjectPresets.JUPITER);
  19. viz.createObject('saturn', Spacekit.SpaceObjectPresets.SATURN);
  20. viz.createObject('uranus', Spacekit.SpaceObjectPresets.URANUS);
  21. viz.createObject('neptune', Spacekit.SpaceObjectPresets.NEPTUNE);
  22. ```

example