EXPERIMENTAL - USE AT OWN RISK
CelestialFinder
A JavaScript library that calculates the position of a celestial bodies in the solar system at a given time.
Current Version (0.2.x)
The current version supports:
- The Sun
- The Moon
Usage
Installation
CelestialFinder is distributed as a npm package.
npm i celestialfinder
Importing
Import the CelestialFinder class in your JavaScript file.
import CelestialFinder from 'celestialfinder'
The create an instance of the CelestialFinder class by providing a date and time in hours. The date input is a string in the format 'yy-mm-dd', and hours are given as integers or with fractions (eg. 1 hour 45 minutes as 1.75).
const celestialFinder = new CelestialFinder(date, hours)
Example:
const celestialFinder = new CelestialFinder('2010-10-12', 16)
Find the position
Now you can use the celestialFinder
to calculate the position of a celestial object at the given date and time. The object returned is of the form (numbers included as an example):
{
rightAscension: {
hours: -3.875798062906315,
minutes: 7.452116225621106,
seconds: 27.12697353726636
},
declination: {
degrees: -15.074768465809955,
arcminutes: 55.51389205140271,
arcseconds: 30.833523084162806
}
}
The Sun
For the position of the Sun, as seen from Earth:
celestialFinder.positionOfTheSun()
The distance in astronomical units, AU, between the Sun and Earth at the given time:
celestialFinder.distanceToTheSun()
The periapsis at the given time:
celestialFinder.periapsisOfTheSun()
The Moon
For the position of the Moon, as seen from Earth:
celestialFinder.positionOfTheMoon()
Time since 2000
For the calculations of the position there is a need to also calculate the time eloped since midnight between 31 december 1999 and 1 january 2000, epoch 2000, in days. It is possible to get this by using CelestialFinder.
celestialFinder.timeSince2000()
Known Issues
The position of the celestial objects do come with errors. Do not use this library for sending real rockets into space and hope to make a soft landing. Odds are that you will end like the passengers in Aniara, science fiction poem written by Swedish Nobel laureate Harry Martinson.
TypeError/Declaration file
There seems to be an issue where Visual Studio Code thinks the library is in Typescript. It will then give an error like:
Could not find a declaration file for module './lib/CelestialFinder.js'.[..] implicitly has an 'any' type.ts(7016)
And in the browser inspector or development tools it gets an error like:
Uncaught TypeError: Failed to resolve module specifier "CelestialFinder". Relative references must start with either "/", "./", or "../".
Solution: When importing the library, use the whole relative path. Example: The class wanting to use the library is in /src/controller, the path could be '../../node_modules/celestialfinder/index.js'
Future Features
Hopefully future releases will support:
- Mercury
- Venus
- Mars
- Jupiter
- Saturn
- Uranus
- Neptune
- Pluto and other bodies like Ceres
Other planned features include the ability to give time for next perihelium or aphelium.
Calculations
The calculations are based on Paul Schlyters work published at https://stjarnhimlen.se/comp/ppcomp.html.
Orbital Elements
The orbital elements for the supported celestial bodies are stored in json. The elements are:
- a: Semi-major axis of the orbit, or mean distance from the sun.
- e: Eccentricity, the elongation of the orbit compared to a circle.
- i: Inclination to the ecliptic, the plane of Earth's orbit.
- N: Longitude of the ascending node, the point of the orbit that passes the plane of reference. Often denoted with Ω (uppercase omega).
- w: Argument of periapsis (perihelion for heliocentric orbits). Often denoted with ω (lowercase omega)
- M: Mean anomaly, fictitious "angle" that increase linear with time. The True anomaly changes faster at perihelion.
The data stored in the json-file is in case of angles in degrees. The semi-major axis is in astronomical units, AU, except for the moon which is in earth radii.
Time scale
Time is calculated in days since (or before) january 1 in the year 2000. The following formula is used for validity over the entire Gregorian Calendar:
d = 367*y - 7 * ( y + (m+9)/12 ) / 4 - 3 * ( ( y + (m-9)/7 ) / 100 + 1 ) / 4 + 275*m/9 + D - 730515
All division is integer, thus rounded down.
Versions
0.1
First release, supports calculating the position of the Sun.
0.2
CelestialFinder now supports finding the position of the Moon. It is also possible to get the time eloped since epoch 2000, that is the midnight between 31 december 1999 and 1 january 2000. Released as a npm package.
0.2.1
Code rewrites making it possible to call and get results from calculations such as distance, periapsis, anomalies and more for a given time. These features are undocumented.
0.2.2
Updated README.md with clearer instructions for installation and usage.
0.2.3-0.2.4
Code cleaning and fixing som errors in README.md.
0.2.5-0.2.6
Renaming of methods for finding the position of the Sun and Moon. Adding the ability to get the distance between Earth and Sun, and also the periapsis.
0.2.7
Add fix for negative value for Right Ascension.
License
This project is part of "laboration 2" in the course "1DV610 - Introduktion till mjukvarukvalitet" at Linnéuniversitetet. It's published under MIT License.
Contributing
The library is available at GitHub (https://github.com/JFSvensson/1DV610_L2_JFSvensson). Pull requests and/or suggestions for future releases are welcome.