Astronomy Engine (JavaScript / TypeScript)

This is the complete programming reference for the JavaScript version of Astronomy Engine. It supports client side programming in the browser, and backend use of Node.js.

Astronomy Engine is available as an npm package.

Both the browser and backend versions of the JavaScript code are generated from TypeScript code in astronomy.ts, which is also provided here for those who want to use it directly.

Other programming languages are supported also. See the home page for more info.

Quick Start

To use Astronomy Engine in your own project, you can use the TypeScript file astronomy.ts from this directory.

For convenience, this directory also contains human-readable JavaScript files astronomy.js and minified versions for the browser (astronomy.browser.min.js) and Node.js (astronomy.min.js). These JavaScript sources are all compiled from the TypeScript source astronomy.ts.

To get started quickly, here are some browser scripting examples and some Node.js examples.

Topic Index

Position of Sun, Moon, and planets

Geographic helper functions

Rise, set, and culmination times

Moon phases

Eclipses and Transits

Lunar perigee and apogee

Planet perihelion and aphelion

Visual magnitude and elongation

Oppositions and conjunctions

Equinoxes and solstices

Coordinate transforms

The following orientation systems are supported. Astronomy Engine can convert a vector from any of these orientations to any of the others. It also allows converting from a vector to spherical (angular) coordinates and back, within a given orientation. Note the 3-letter codes for each of the orientation systems; these are used in function and type names.

• EQJ = J2000 Mean Equator: Uses the Earth's mean equator (corrected for precession but ignoring nutation) on January 1, 2000, at noon UTC. This moment in time is called J2000.
• EQD = True Equator of Date: Uses the Earth's equator on a given date and time, adjusted for precession and nutation.
• ECL = J2000 Mean Ecliptic: Uses the plane of the Earth's orbit around the Sun at J2000. The x-axis is referenced against the J2000 mean equinox.
• ECT = True Ecliptic of Date: Uses the true (corrected for precession and nutation) orbital plane of the Earth on the given date. The x-axis is referenced against the true equinox for that date.
• HOR = Horizontal: Uses the viewpoint of an observer at a specific location on the Earth at a given date and time.
• GAL = Galactic: Based on the IAU 1958 definition of galactic coordinates.

Gravitational simulation of small bodies

Astronomy Engine provides a GravitySimulator class that allows you to model the trajectories of one or more small bodies like asteroids, comets, or coasting spacecraft. If you know an initial position vector and velocity vector for a small body, the gravity simulator can incrementally simulate the pull of gravity on it from the Sun and planets, to calculate its movement through the Solar System.

API Reference

AstroTime

Kind: global class
Brief: The date and time of an astronomical observation.

Objects of type AstroTime are used throughout the internals of the Astronomy library, and are included in certain return objects. Use the constructor or the MakeTime function to create an AstroTime object.
Properties

new AstroTime(date)

astroTime.toString() ⇒ string

Formats an AstroTime object as an ISO 8601 date/time string in UTC, to millisecond resolution. Example: 2018-08-17T17:22:04.050Z

Kind: instance method of AstroTime

astroTime.AddDays(days) ⇒ AstroTime

Returns a new AstroTime object adjusted by the floating point number of days. Does NOT modify the original AstroTime object.

Kind: instance method of AstroTime

AstroTime.FromTerrestrialTime(tt) ⇒ AstroTime

Kind: static method of AstroTime
Returns: AstroTime - An AstroTime object for the specified terrestrial time.
Brief: Creates an AstroTime value from a Terrestrial Time (TT) day value.

This function can be used in rare cases where a time must be based on Terrestrial Time (TT) rather than Universal Time (UT). Most developers will want to invoke new AstroTime(ut) with a universal time instead of this function, because usually time is based on civil time adjusted by leap seconds to match the Earth's rotation, rather than the uniformly flowing TT used to calculate solar system dynamics. In rare cases where the caller already knows TT, this function is provided to create an AstroTime value that can be passed to Astronomy Engine functions.

LibrationInfo

Kind: global class
Brief: Lunar libration angles, returned by Libration.
Properties

Vector

Kind: global class
Brief: A 3D Cartesian vector with a time attached to it.

Holds the Cartesian coordinates of a vector in 3D space, along with the time at which the vector is valid.
Properties

vector.Length() ⇒ number

Returns the length of the vector in astronomical units (AU).

Kind: instance method of Vector

StateVector

Kind: global class
Brief: A combination of a position vector, a velocity vector, and a time.

Holds the state vector of a body at a given time, including its position, velocity, and the time they are valid.
Properties

Spherical

Kind: global class
Brief: Holds spherical coordinates: latitude, longitude, distance.

Spherical coordinates represent the location of a point using two angles and a distance.
Properties

EquatorialCoordinates

Kind: global class
Brief: Holds right ascension, declination, and distance of a celestial object.
Properties

RotationMatrix

Kind: global class
Brief: Contains a rotation matrix that can be used to transform one coordinate system to another.
Properties

HorizontalCoordinates

Kind: global class
Brief: Represents the location of an object seen by an observer on the Earth.

Holds azimuth (compass direction) and altitude (angle above/below the horizon) of a celestial object as seen by an observer at a particular location on the Earth's surface. Also holds right ascension and declination of the same object. All of these coordinates are optionally adjusted for atmospheric refraction; therefore the right ascension and declination values may not exactly match those found inside a corresponding EquatorialCoordinates object.
Properties

EclipticCoordinates

Kind: global class
Brief: Ecliptic coordinates of a celestial body.

The origin and date of the coordinate system may vary depending on the caller's usage. In general, ecliptic coordinates are measured with respect to the mean plane of the Earth's orbit around the Sun. Includes Cartesian coordinates (ex, ey, ez) measured in astronomical units (AU) and spherical coordinates (elon, elat) measured in degrees.
Properties

Observer

Kind: global class
Brief: Represents the geographic location of an observer on the surface of the Earth.
Properties

JupiterMoonsInfo

Kind: global class
Brief: Holds the positions and velocities of Jupiter's major 4 moons.

The JupiterMoons function returns an object of this type to report position and velocity vectors for Jupiter's largest 4 moons Io, Europa, Ganymede, and Callisto. Each position vector is relative to the center of Jupiter. Both position and velocity are oriented in the EQJ system (that is, using Earth's equator at the J2000 epoch). The positions are expressed in astronomical units (AU), and the velocities in AU/day.
Properties

IlluminationInfo

Kind: global class
Brief: Information about the apparent brightness and sunlit phase of a celestial object.
Properties

MoonQuarter

Kind: global class
Brief: A quarter lunar phase, along with when it occurs.
Properties

AtmosphereInfo

Kind: global class
Brief: Information about idealized atmospheric variables at a given elevation.
Properties

HourAngleEvent

Kind: global class
Brief: Horizontal position of a body upon reaching an hour angle.

Returns information about an occurrence of a celestial body reaching a given hour angle as seen by an observer at a given location on the surface of the Earth.
Properties

SeasonInfo

Kind: global class
Brief: When the seasons change for a given calendar year.

Represents the dates and times of the two solstices and the two equinoxes in a given calendar year. These four events define the changing of the seasons on the Earth.
Properties

ElongationEvent

Kind: global class
Brief: The viewing conditions of a body relative to the Sun.

Represents the angular separation of a body from the Sun as seen from the Earth and the relative ecliptic longitudes between that body and the Earth as seen from the Sun.
See: Elongation
Properties

Apsis

Kind: global class
Brief: A closest or farthest point in a body's orbit around its primary.

For a planet orbiting the Sun, apsis is a perihelion or aphelion, respectively. For the Moon orbiting the Earth, apsis is a perigee or apogee, respectively.
See

• SearchLunarApsis
• NextLunarApsis
• SearchPlanetApsis
• NextPlanetApsis

Properties

ConstellationInfo

Kind: global class
Brief: Reports the constellation that a given celestial point lies within.
Properties

LunarEclipseInfo

Kind: global class
Brief: Returns information about a lunar eclipse.

Returned by SearchLunarEclipse or NextLunarEclipse to report information about a lunar eclipse event. When a lunar eclipse is found, it is classified as penumbral, partial, or total. Penumbral eclipses are difficult to observe, because the Moon is only slightly dimmed by the Earth's penumbra; no part of the Moon touches the Earth's umbra. Partial eclipses occur when part, but not all, of the Moon touches the Earth's umbra. Total eclipses occur when the entire Moon passes into the Earth's umbra.

The kind field thus holds one of the enum values EclipseKind.Penumbral, EclipseKind.Partial, or EclipseKind.Total, depending on the kind of lunar eclipse found.

The obscuration field holds a value in the range [0, 1] that indicates what fraction of the Moon's apparent disc area is covered by the Earth's umbra at the eclipse's peak. This indicates how dark the peak eclipse appears. For penumbral eclipses, the obscuration is 0, because the Moon does not pass through the Earth's umbra. For partial eclipses, the obscuration is somewhere between 0 and 1. For total lunar eclipses, the obscuration is 1.

Field peak holds the date and time of the peak of the eclipse, when it is at its peak.

Fields sd_penum, sd_partial, and sd_total hold the semi-duration of each phase of the eclipse, which is half of the amount of time the eclipse spends in each phase (expressed in minutes), or 0 if the eclipse never reaches that phase. By converting from minutes to days, and subtracting/adding with peak, the caller may determine the date and time of the beginning/end of each eclipse phase.
Properties

GlobalSolarEclipseInfo

Kind: global class
Brief: Reports the time and geographic location of the peak of a solar eclipse.

Returned by SearchGlobalSolarEclipse or NextGlobalSolarEclipse to report information about a solar eclipse event.

The eclipse is classified as partial, annular, or total, depending on the maximum amount of the Sun's disc obscured, as seen at the peak location on the surface of the Earth.

The kind field thus holds one of the values EclipseKind.Partial, EclipseKind.Annular, or EclipseKind.Total. A total eclipse is when the peak observer sees the Sun completely blocked by the Moon. An annular eclipse is like a total eclipse, but the Moon is too far from the Earth's surface to completely block the Sun; instead, the Sun takes on a ring-shaped appearance. A partial eclipse is when the Moon blocks part of the Sun's disc, but nobody on the Earth observes either a total or annular eclipse.

If kind is EclipseKind.Total or EclipseKind.Annular, the latitude and longitude fields give the geographic coordinates of the center of the Moon's shadow projected onto the daytime side of the Earth at the instant of the eclipse's peak. If kind has any other value, latitude and longitude are undefined and should not be used.

For total or annular eclipses, the obscuration field holds the fraction (0, 1] of the Sun's apparent disc area that is blocked from view by the Moon's silhouette, as seen by an observer located at the geographic coordinates latitude, longitude at the darkest time peak. The value will always be 1 for total eclipses, and less than 1 for annular eclipses. For partial eclipses, obscuration is undefined and should not be used. This is because there is little practical use for an obscuration value of a partial eclipse without supplying a particular observation location. Developers who wish to find an obscuration value for partial solar eclipses should therefore use SearchLocalSolarEclipse and provide the geographic coordinates of an observer.
Properties

EclipseEvent

Kind: global class
Brief: Holds a time and the observed altitude of the Sun at that time.

When reporting a solar eclipse observed at a specific location on the Earth (a "local" solar eclipse), a series of events occur. In addition to the time of each event, it is important to know the altitude of the Sun, because each event may be invisible to the observer if the Sun is below the horizon.

If altitude is negative, the event is theoretical only; it would be visible if the Earth were transparent, but the observer cannot actually see it. If altitude is positive but less than a few degrees, visibility will be impaired by atmospheric interference (sunrise or sunset conditions).
Properties

LocalSolarEclipseInfo

Kind: global class
Brief: Information about a solar eclipse as seen by an observer at a given time and geographic location.

Returned by SearchLocalSolarEclipse or NextLocalSolarEclipse to report information about a solar eclipse as seen at a given geographic location.

When a solar eclipse is found, it is classified by setting kind to EclipseKind.Partial, EclipseKind.Annular, or EclipseKind.Total. A partial solar eclipse is when the Moon does not line up directly enough with the Sun to completely block the Sun's light from reaching the observer. An annular eclipse occurs when the Moon's disc is completely visible against the Sun but the Moon is too far away to completely block the Sun's light; this leaves the Sun with a ring-like appearance. A total eclipse occurs when the Moon is close enough to the Earth and aligned with the Sun just right to completely block all sunlight from reaching the observer.

The obscuration field reports what fraction of the Sun's disc appears blocked by the Moon when viewed by the observer at the peak eclipse time. This is a value that ranges from 0 (no blockage) to 1 (total eclipse). The obscuration value will be between 0 and 1 for partial eclipses and annular eclipses. The value will be exactly 1 for total eclipses. Obscuration gives an indication of how dark the eclipse appears.

There are 5 "event" fields, each of which contains a time and a solar altitude. Field peak holds the date and time of the center of the eclipse, when it is at its peak. The fields partial_begin and partial_end are always set, and indicate when the eclipse begins/ends. If the eclipse reaches totality or becomes annular, total_begin and total_end indicate when the total/annular phase begins/ends. When an event field is valid, the caller must also check its altitude field to see whether the Sun is above the horizon at the time indicated by the time field. See EclipseEvent for more information.
Properties

TransitInfo

Kind: global class
Brief: Information about a transit of Mercury or Venus, as seen from the Earth.

Returned by SearchTransit or NextTransit to report information about a transit of Mercury or Venus. A transit is when Mercury or Venus passes between the Sun and Earth so that the other planet is seen in silhouette against the Sun.

The calculations are performed from the point of view of a geocentric observer.
Properties

NodeEventInfo

Kind: global class
Brief: Information about an ascending or descending node of a body.

This object is returned by SearchMoonNode and NextMoonNode to report information about the center of the Moon passing through the ecliptic plane.
Properties

AxisInfo

Kind: global class
Brief: Information about a body's rotation axis at a given time.

This structure is returned by RotationAxis to report the orientation of a body's rotation axis at a given moment in time. The axis is specified by the direction in space that the body's north pole points, using angular equatorial coordinates in the J2000 system (EQJ).

Thus ra is the right ascension, and dec is the declination, of the body's north pole vector at the given moment in time. The north pole of a body is defined as the pole that lies on the north side of the Solar System's invariable plane, regardless of the body's direction of rotation.

The spin field indicates the angular position of a prime meridian arbitrarily recommended for the body by the International Astronomical Union (IAU).

The fields ra, dec, and spin correspond to the variables α0, δ0, and W, respectively, from Report of the IAU Working Group on Cartographic Coordinates and Rotational Elements: 2015. The field north is a unit vector pointing in the direction of the body's north pole. It is expressed in the J2000 mean equator system (EQJ).
Properties

GravitySimulator

Kind: global class
Brief: A simulation of zero or more small bodies moving through the Solar System.

This class calculates the movement of arbitrary small bodies, such as asteroids or comets, that move through the Solar System. It does so by calculating the gravitational forces on the small bodies from the Sun and planets. The user of this class supplies a list of initial positions and velocities for the small bodies. Then the class can update the positions and velocities over small time steps.

new GravitySimulator(originBody, date, bodyStates)

gravitySimulator.OriginBody

Kind: instance property of GravitySimulator
Brief: The body that was selected as the coordinate origin when this simulator was created.

gravitySimulator.Time

Kind: instance property of GravitySimulator
Brief: The time represented by the current step of the gravity simulation.

gravitySimulator.Update(date) ⇒ Array.<StateVector>

Advances the gravity simulation by a small time step.

Updates the simulation of the user-supplied small bodies to the time indicated by the date parameter. Returns an array of state vectors for the simulated bodies. The array is in the same order as the original array that was used to construct this simulator object. The positions and velocities in the returned array are referenced to the originBody that was used to construct this simulator.

Kind: instance method of GravitySimulator
Returns: Array.<StateVector> - An array of state vectors, one for each simulated small body.

gravitySimulator.Swap()

Exchange the current time step with the previous time step.

Sometimes it is helpful to "explore" various times near a given simulation time step, while repeatedly returning to the original time step. For example, when backdating a position for light travel time, the caller may wish to repeatedly try different amounts of backdating. When the backdating solver has converged, the caller wants to leave the simulation in its original state.

This function allows a single "undo" of a simulation, and does so very efficiently.

Usually this function will be called immediately after a matching call to Update. It has the effect of rolling back the most recent update. If called twice in a row, it reverts the swap and thus has no net effect.

The constructor initializes the current state and previous state to be identical. Both states represent the time parameter that was passed into the constructor. Therefore, Swap will have no effect from the caller's point of view when passed a simulator that has not yet been updated by a call to Update.

Kind: instance method of GravitySimulator

gravitySimulator.SolarSystemBodyState(body)

Get the position and velocity of a Solar System body included in the simulation.

In order to simulate the movement of small bodies through the Solar System, the simulator needs to calculate the state vectors for the Sun and planets.

If an application wants to know the positions of one or more of the planets in addition to the small bodies, this function provides a way to obtain their state vectors. This is provided for the sake of efficiency, to avoid redundant calculations.

The state vector is returned relative to the position and velocity of the originBody parameter that was passed to this object's constructor.

Kind: instance method of GravitySimulator

C_AUDAY

Kind: global variable
Brief: The speed of light in AU/day.

KM_PER_AU

Kind: global variable
Brief: The number of kilometers per astronomical unit.

AU_PER_LY

Kind: global variable
Brief: The number of astronomical units per light-year.

DEG2RAD

Kind: global variable
Brief: The factor to convert degrees to radians = pi/180.

HOUR2RAD

Kind: global variable
Brief: The factor to convert sidereal hours to radians = pi/12.

RAD2DEG

Kind: global variable
Brief: The factor to convert radians to degrees = 180/pi.

RAD2HOUR

Kind: global variable
Brief: The factor to convert radians to sidereal hours = 12/pi.

JUPITER_EQUATORIAL_RADIUS_KM

Kind: global variable
Brief: The equatorial radius of Jupiter, expressed in kilometers.

JUPITER_POLAR_RADIUS_KM

Kind: global variable
Brief: The polar radius of Jupiter, expressed in kilometers.

JUPITER_MEAN_RADIUS_KM

Kind: global variable
Brief: The volumetric mean radius of Jupiter, expressed in kilometers.

IO_RADIUS_KM

Kind: global variable
Brief: The mean radius of Jupiter's moon Io, expressed in kilometers.

EUROPA_RADIUS_KM

Kind: global variable
Brief: The mean radius of Jupiter's moon Europa, expressed in kilometers.

GANYMEDE_RADIUS_KM

Kind: global variable
Brief: The mean radius of Jupiter's moon Ganymede, expressed in kilometers.

CALLISTO_RADIUS_KM

Kind: global variable
Brief: The mean radius of Jupiter's moon Callisto, expressed in kilometers.

Body : enum

Kind: global enum
Brief: String constants that represent the solar system bodies supported by Astronomy Engine.

The following strings represent solar system bodies supported by various Astronomy Engine functions. Not every body is supported by every function; consult the documentation for each function to find which bodies it supports.

"Sun", "Moon", "Mercury", "Venus", "Earth", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto", "SSB" (Solar System Barycenter), "EMB" (Earth/Moon Barycenter)

You can also use enumeration syntax for the bodies, like Astronomy.Body.Moon, Astronomy.Body.Jupiter, etc.

ApsisKind : enum

Kind: global enum
Brief: The two kinds of apsis: pericenter (closest) and apocenter (farthest).

Pericenter: The body is at its closest distance to the object it orbits. Apocenter: The body is at its farthest distance from the object it orbits.

EclipseKind : enum

Kind: global enum
Brief: The different kinds of lunar/solar eclipses..

Penumbral: A lunar eclipse in which only the Earth's penumbra falls on the Moon. (Never used for a solar eclipse.) Partial: A partial lunar/solar eclipse. Annular: A solar eclipse in which the entire Moon is visible against the Sun, but the Sun appears as a ring around the Moon. (Never used for a lunar eclipse.) Total: A total lunar/solar eclipse.

NodeEventKind : enum

Kind: global enum
Brief: Indicates whether a crossing through the ecliptic plane is ascending or descending.

Invalid is a placeholder for an unknown or missing node. Ascending indicates a body passing through the ecliptic plane from south to north. Descending indicates a body passing through the ecliptic plane from north to south.

AngleBetween(a, b) ⇒ number

Kind: global function
Returns: number - The angle between the two vectors expressed in degrees. The value is in the range [0, 180].
Brief: Calculates the angle in degrees between two vectors.

Given a pair of vectors, this function returns the angle in degrees between the two vectors in 3D space. The angle is measured in the plane that contains both vectors.

AngleFromSun(body, date) ⇒ number

Kind: global function
Returns: number - An angle in degrees in the range [0, 180].
Brief: Calculates the angular separation between the Sun and the given body.

Returns the full angle seen from the Earth, between the given body and the Sun. Unlike PairLongitude, this function does not project the body's "shadow" onto the ecliptic; the angle is measured in 3D space around the plane that contains the centers of the Earth, the Sun, and body.

Atmosphere(elevationMeters) ⇒ AtmosphereInfo

Kind: global function
Brief: Calculates U.S. Standard Atmosphere (1976) variables as a function of elevation.

This function calculates idealized values of pressure, temperature, and density using the U.S. Standard Atmosphere (1976) model.

1. COESA, U.S. Standard Atmosphere, 1976, U.S. Government Printing Office, Washington, DC, 1976.
2. Jursa, A. S., Ed., Handbook of Geophysics and the Space Environment, Air Force Geophysics Laboratory, 1985. See: https://hbcp.chemnetbase.com/faces/documents/14_12/14_12_0001.xhtml https://ntrs.nasa.gov/api/citations/19770009539/downloads/19770009539.pdf https://www.ngdc.noaa.gov/stp/space-weather/online-publications/miscellaneous/us-standard-atmosphere-1976/us-standard-atmosphere_st76-1562_noaa.pdf

BackdatePosition(date, observerBody, targetBody, aberration) ⇒ Vector

Kind: global function
Returns: Vector - The position vector at the solved backdated time. The t field holds the time that light left the observed body to arrive at the observer at the observation time.
Brief: Solve for light travel time correction of apparent position.

When observing a distant object, for example Jupiter as seen from Earth, the amount of time it takes for light to travel from the object to the observer can significantly affect the object's apparent position.

This function solves the light travel time correction for the apparent relative position vector of a target body as seen by an observer body at a given observation time.

For geocentric calculations, GeoVector also includes light travel time correction, but the time t embedded in its returned vector refers to the observation time, not the backdated time that light left the observed body. Thus BackdatePosition provides direct access to the light departure time for callers that need it.

For a more generalized light travel correction solver, see CorrectLightTravel.

BaryState(body, date) ⇒ StateVector

Kind: global function
Returns: StateVector - An object that contains barycentric position and velocity vectors.
Brief: Calculates barycentric position and velocity vectors for the given body.

Given a body and a time, calculates the barycentric position and velocity vectors for the center of that body at that time. The vectors are expressed in J2000 mean equator coordinates (EQJ).

CombineRotation(a, b) ⇒ RotationMatrix

Kind: g