Kepler Utils

This node package uses JPL's Keplerian Elements for Aproximate Positions of the Major Planets to calculate the heliocentric positions of the planets in our solar system on a given date. It provides a set of tools for converting Gregorian dates to Julian dates as well as calculating the positions of the planets.

Getting Started

Follow the instructions below to get this project up and running on your sytstem

Prerequisites

You will need to have the NodeJS environment installed on your machine if you want to use the NodeJS Package Manager to install this project.

Installing

You can add this package to your project by running

$ npm install kepler-utils

You can also clone this project if you want to use it without NodeJS

$ git clone https://github.com/popnfresh234/kepler-utils.git

Usage

First, require the module in your project

const KeplerUtils = require('kepler-utils');

The KeplerUtils project contains two helper modules, JulianUtils for converting dates and OrbitalUtils for calculating orbital positions.

Typical usage would be to calculate the orbital positions of a planet at a given date. For this we make use of the OrbitalUtils module. The OribtalUtils module provides a method that takes a planet object provided by KeplerUtils and the number of centuries since the J2000 reference frame. The number of centuries since J2000 is given by a helper method in the JulianUtils module.

const SolarSystem = KeplerUtils.SolarSystem;
const julianDate = KeplerUtils.JulianUtils.getJulianDate('1985/04/30');
const centuriesSinceJ2000 = KeplerUtils.JulianUtils.getCenturiesSincej2000(julianDate);
const marsPosition = KeplerUtils.OrbitalUtils.calcOrbitals(SolarSystem.mars, centuriesSinceJ2000);

SolarSystem

KeplerUtils provides a SolarySystem object that has whose keys are the planet names, eg mars, and whose properties are data about the planets You can access the objet as follows:

const SolarSystem = KeplerUtils.SolarSystem;
const mars = SolarSystem.mars;

A planet object is structured as follows:

const mars = {
  display: 'Mars',
  name: 'mars',
  scaleFactor: 1,
  rFactor: 0.532,
  color: '#CF7167',
  apiDate: '1987/9/4',
  periDate: '1988/8/13',
  orbit: {
    elements: {
      a: { val: 1.52371034, deg: false },
      e: { val: 0.0933941, deg: false },
      i: { val: 1.84969142, deg: true },
      L: { val: -4.55343205, deg: true },
      lPeri: { val: -23.94362959, deg: true },
      lAscNode: { val: 49.55953891, deg: true },
    },
    cYs: {
      a: { val: 0.00001847, deg: false },
      e: { val: 0.00007882, deg: false },
      i: { val: -0.00813131, deg: true },
      L: { val: 19140.30268499, deg: true },
      lPeri: { val: 0.44441088, deg: true },
      lAscNode: { val: -0.29257343, deg: true },
    },
  },
};

To calculate the position of the planet we use the orbit object, which contains the planet's orbital elements at J2000 and the cYs to be applied to those elements to find their position at a given date.

For example, to find the eccentricity on 1985/04/30 we would perform the following operation:

orbit.elements.a + ( orbit.cYs.a * centuriesSinceJ2000 );

The above is for reference only, this calculation is actually caried out in the OrbitalUtils module.

JulianUtils Functions

getJulianDate ( gregorianDate )

Takes a Gregorian date in the format YYYY/MM/DD and returns the equivalent Julian Date

getGregorianDate ( julianDate )

Takes a Julian date and returns a Date object for that day.

getJ2000 ()

Returns the Julian date for the J2000 reference date of 2000/1/1

getCenturiesSinceJ2000 ( gregorianDate )

Takes a Gregorian date in the format YYYY/MM/DD and returns the numbers of centuries elapsed since J2000.

OrbitalUtils Functions

calcOrbitals ( planet, centuriesSinceJ2000 )

Takes a Planet object provided by KeplerUtils.SolarSystem and the number of centuries elapsed since J2000 provided by KeplerUtils.JulianUtils and returns an object with data about the given planets position in space.

Typical output is as follows:

{
  a: 1.5237076300553047,
  e: 0.09338253541738535,
  i: 1.850884457379603,
  L: 67.15410829602524,
  lPeri: 335.9911658129864,
  lAscNode: 49.60246570018125,
  M: 91.16294248303882,
  eccAnom: 96.479194,
  trueAnom: 101.77532685909541,
  b: 1.5170494907935048,
  helioCentricCoords:
     {
       x: 0.3265591021725068,
       y: 1.50455324006384,
       z: 0.023473333963656553,
     },
};

The keys of the returned object is as follows:

| Key | Property | Units| |-----|----------|------| | a | semi-major axis | au | |e| eccentricity| unitless| |i| inclination | degrees| |L| mean longitude | degrees| |lPeri| longitude of perihelion | degrees| |lAscNode|longitude of ascending node|degrees| |M|mean anomaly|degrees| |eccAnom|eccentric anomaly|degrees| |trueAnom|true anomaly|degrees| |b|semi minor axis|au| |heliocentricCoords|rectangular coords of plaents|au|

This data can then be used to plot the positions of the planets for whatever use case you may have.

getPlutoFullOrbit ()

This method returns an [] of objects containing rectangular coordinates for an entire period of Pluto's orbit. As Pluto's orbit doesn't fit a perfect ellipse well, we can make use of these points to manually plot the path of Pluto's orbit for dispaly purposes.

An example of the output of this function is as follow:

[ 
  { x: -20.256870769288906,
    y: -20.126040799230992,
    z: 8.01303272889247 },
  { x: -20.209017036396666,
    y: -20.177347181609036,
    z: 8.004682070653734 },
    ...
]

Versioning

This project uses SemVer for versioning.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Acknowledgments

The following resources were indispensable for creating this project

• JPL's Keplerian Elements for Aproximate Positions of the Major Planets
• Wikipedia entry on Orbital Elements for a high level overview
• Wikipedia entry on Julian Dates
• Wikipedia entry on Mean Longitude
• J. Giesen's website regarding Kepler and solving for the eccentric anomaly
• Rocket and Space Technology regarding solving for the True Anomaly
• Stargazing Network regarding converting from polar to rectangular coordinates.