astronomy-engine

Astronomy calculation for Sun, Moon, and planets.

Usage no npm install needed!

<script type="module">
  import astronomyEngine from 'https://cdn.skypack.dev/astronomy-engine';
</script>

README

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.

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

Function Description
HelioVector Calculates body position vector with respect to the center of the Sun.
GeoVector Calculates body position vector with respect to the center of the Earth.
Equator Calculates right ascension and declination.
Ecliptic Calculates ecliptic latitude, longitude, and Cartesian coordinates.
Horizon Calculates horizontal coordinates (azimuth, altitude) for a given observer on the Earth.
PairLongitude Calculates the difference in apparent ecliptic longitude between two bodies, as seen from the Earth.
BaryState Calculates the barycentric position and velocity vectors of the Sun or a planet.

Geographic helper functions

Function Description
ObserverVector Calculates a vector from the center of the Earth to an observer on the Earth's surface.
VectorObserver Calculates the geographic coordinates for a geocentric equatorial vector.

Rise, set, and culmination times

Function Description
SearchRiseSet Finds time of rise or set for a body as seen by an observer on the Earth.
SearchAltitude Finds time when a body reaches a given altitude above or below the horizon. Useful for finding civil, nautical, or astronomical twilight.
SearchHourAngle Finds when body reaches a given hour angle for an observer on the Earth. Hour angle = 0 finds culmination, the highest point in the sky.

Moon phases

Function Description
MoonPhase Determines the Moon's phase expressed as an ecliptic longitude.
SearchMoonQuarter Find the first quarter moon phase after a given date and time.
NextMoonQuarter Find the next quarter moon phase after a previous one that has been found.

Eclipses and Transits

Function Description
SearchLunarEclipse Search for the first lunar eclipse after a given date.
NextLunarEclipse Continue searching for more lunar eclipses.
SearchGlobalSolarEclipse Search for the first solar eclipse after a given date that is visible anywhere on the Earth.
NextGlobalSolarEclipse Continue searching for solar eclipses visible anywhere on the Earth.
SearchLocalSolarEclipse Search for the first solar eclipse after a given date that is visible at a particular location on the Earth.
NextLocalSolarEclipse Continue searching for solar eclipses visible at a particular location on the Earth.
SearchTransit Search for the next transit of Mercury or Venus.
NextTransit Continue searching for transits of Mercury or Venus.

Lunar perigee and apogee

Function Description
SearchLunarApsis Finds the next perigee or apogee of the Moon after a specified date.
NextLunarApsis Given an already-found apsis, find the next perigee or apogee of the Moon.

Planet perihelion and aphelion

Function Description
SearchPlanetApsis Finds the next perihelion or aphelion of a planet after a specified date.
NextPlanetApsis Given an already-found apsis, find the next perihelion or aphelion of a planet.

Visual magnitude and elongation

Function Description
Illumination Calculates visual magnitude and phase angle of bodies as seen from the Earth.
SearchPeakMagnitude Searches for the date and time Venus will next appear brightest as seen from the Earth.
AngleFromSun Returns full angle seen from Earth between body and Sun.
Elongation Calculates ecliptic longitude angle between a body and the Sun, as seen from the Earth.
SearchMaxElongation Searches for the next maximum elongation event for Mercury or Venus that occurs after the given date.

Oppositions and conjunctions

Function Description
SearchRelativeLongitude Find oppositions and conjunctions of planets.

Equinoxes and solstices

Function Description
Seasons Finds the equinoxes and solstices for a given calendar year.

Coordinate transforms

The following five 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 = Equatorial J2000: Uses the Earth's equator on January 1, 2000, at noon UTC.
  • EQD = Equator of-date: Uses the Earth's equator on a given date and time, adjusted for precession and nutation.
  • ECL = Ecliptic: Uses the mean plane of the Earth's orbit around the Sun. The x-axis is referenced against the J2000 equinox.
  • 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.
Function Description
RotateVector Applies a rotation matrix to a vector, yielding a vector in another orientation system.
InverseRotation Given a rotation matrix, finds the inverse rotation matrix that does the opposite transformation.
CombineRotation Given two rotation matrices, returns a rotation matrix that combines them into a net transformation.
IdentityMatrix Returns a 3x3 identity matrix, which can be used to form other rotation matrices.
Pivot Transforms a rotation matrix by pivoting it around a given axis by a given angle.
VectorFromSphere Converts spherical coordinates to Cartesian coordinates.
SphereFromVector Converts Cartesian coordinates to spherical coordinates.
EquatorFromVector Given an equatorial vector, calculates equatorial angular coordinates.
VectorFromHorizon Given apparent angular horizontal coordinates, calculates horizontal vector.
HorizonFromVector Given a vector in horizontal orientation, calculates horizontal angular coordinates.
Rotation_EQD_EQJ Calculates a rotation matrix from equatorial of-date (EQD) to equatorial J2000 (EQJ).
Rotation_EQD_ECL Calculates a rotation matrix from equatorial of-date (EQD) to ecliptic J2000 (ECL).
Rotation_EQD_HOR Calculates a rotation matrix from equatorial of-date (EQD) to horizontal (HOR).
Rotation_EQJ_EQD Calculates a rotation matrix from equatorial J2000 (EQJ) to equatorial of-date (EQD).
Rotation_EQJ_ECL Calculates a rotation matrix from equatorial J2000 (EQJ) to ecliptic J2000 (ECL).
Rotation_EQJ_HOR Calculates a rotation matrix from equatorial J2000 (EQJ) to horizontal (HOR).
Rotation_ECL_EQD Calculates a rotation matrix from ecliptic J2000 (ECL) to equatorial of-date (EQD).
Rotation_ECL_EQJ Calculates a rotation matrix from ecliptic J2000 (ECL) to equatorial J2000 (EQJ).
Rotation_ECL_HOR Calculates a rotation matrix from ecliptic J2000 (ECL) to horizontal (HOR).
Rotation_HOR_EQD Calculates a rotation matrix from horizontal (HOR) to equatorial of-date (EQD).
Rotation_HOR_EQJ Calculates a rotation matrix from horizontal (HOR) to J2000 equatorial (EQJ).
Rotation_HOR_ECL Calculates a rotation matrix from horizontal (HOR) to ecliptic J2000 (ECL).
Rotation_EQJ_GAL Calculates a rotation matrix from equatorial J2000 (EQJ) to galactic (GAL).
Rotation_GAL_EQJ Calculates a rotation matrix from galactic (GAL) to equatorial J2000 (EQJ).

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

Name Type Description
date Date The JavaScript Date object for the given date and time. This Date corresponds to the numeric day value stored in the ut property.
ut number Universal Time (UT1/UTC) in fractional days since the J2000 epoch. Universal Time represents time measured with respect to the Earth's rotation, tracking mean solar days. The Astronomy library approximates UT1 and UTC as being the same thing. This gives sufficient accuracy for the precision requirements of this project.
tt number Terrestrial Time in fractional days since the J2000 epoch. TT represents a continuously flowing ephemeris timescale independent of any variations of the Earth's rotation, and is adjusted from UT using a best-fit piecewise polynomial model devised by Espenak and Meeus.

new AstroTime(date)

Param Type Description
date FlexibleDateTime A JavaScript Date object, a numeric UTC value expressed in J2000 days, or another AstroTime object.

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

Param Type Description
days number The floating point number of days by which to adjust the given date and time. Positive values adjust the date toward the future, and negative values adjust the date toward the past.

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.

Param Type Description
tt number The number of days since the J2000 epoch as expressed in Terrestrial Time.

LibrationInfo

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

Name Type Description
elat number Sub-Earth libration ecliptic latitude angle, in degrees.
elon number Sub-Earth libration ecliptic longitude angle, in degrees.
mlat number Moon's geocentric ecliptic latitude.
mlon number Moon's geocentric ecliptic longitude.
dist_km number Distance between the centers of the Earth and Moon in kilometers.
diam_deg number The apparent angular diameter of the Moon, in degrees, as seen from the center of the Earth.

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

Name Type Description
x number The x-coordinate expressed in astronomical units (AU).
y number The y-coordinate expressed in astronomical units (AU).
z number The z-coordinate expressed in astronomical units (AU).
t AstroTime The time at which the vector is valid.

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

Name Type Description
x number The position x-coordinate expressed in astronomical units (AU).
y number The position y-coordinate expressed in astronomical units (AU).
z number The position z-coordinate expressed in astronomical units (AU).
vx number The velocity x-coordinate expressed in AU/day.
vy number The velocity y-coordinate expressed in AU/day.
vz number The velocity z-coordinate expressed in AU/day.
t AstroTime The time at which the vector is valid.

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

Name Type Description
lat number The latitude angle: -90..+90 degrees.
lon number The longitude angle: 0..360 degrees.
dist number Distance in AU.

EquatorialCoordinates

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

Name Type Description
ra number Right ascension in sidereal hours: [0, 24).
dec number Declination in degrees: [-90, +90].
dist number Distance to the celestial object expressed in astronomical units (AU).
vec Vector The equatorial coordinates in cartesian form, using AU distance units. x = direction of the March equinox, y = direction of the June solstice, z = north.

RotationMatrix

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

Name Type Description
rot Array.<Array.<number>> A normalized 3x3 rotation matrix. For example, the identity matrix is represented as [[1, 0, 0], [0, 1, 0], [0, 0, 1]].

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

Name Type Description
azimuth number A horizontal compass direction angle in degrees measured starting at north and increasing positively toward the east. The value is in the range [0, 360). North = 0, east = 90, south = 180, west = 270.
altitude number A vertical angle in degrees above (positive) or below (negative) the horizon. The value is in the range [-90, +90]. The altitude angle is optionally adjusted upward due to atmospheric refraction.
ra number The right ascension of the celestial body in sidereal hours. The value is in the reange [0, 24). If altitude was adjusted for atmospheric reaction, ra is likewise adjusted.
dec number The declination of of the celestial body in degrees. The value in the range [-90, +90]. If altitude was adjusted for atmospheric reaction, dec is likewise adjusted.

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

Name Type Description
vec Vector Ecliptic cartesian vector with components measured in astronomical units (AU). The x-axis is within the ecliptic plane and is oriented in the direction of the equinox. The y-axis is within the ecliptic plane and is oriented 90 degrees counterclockwise from the equinox, as seen from above the Sun's north pole. The z-axis is oriented perpendicular to the ecliptic plane, along the direction of the Sun's north pole.
elat number The ecliptic latitude of the body in degrees. This is the angle north or south of the ecliptic plane. The value is in the range [-90, +90]. Positive values are north and negative values are south.
elon number The ecliptic longitude of the body in degrees. This is the angle measured counterclockwise around the ecliptic plane, as seen from above the Sun's north pole. This is the same direction that the Earth orbits around the Sun. The angle is measured starting at 0 from the equinox and increases up to 360 degrees.

Observer

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

Name Type Description
latitude number The observer's geographic latitude in degrees north of the Earth's equator. The value is negative for observers south of the equator. Must be in the range -90 to +90.
longitude number The observer's geographic longitude in degrees east of the prime meridian passing through Greenwich, England. The value is negative for observers west of the prime meridian. The value should be kept in the range -180 to +180 to minimize floating point errors.
height number The observer's elevation above mean sea level, expressed in meters.

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

Name Type Description
moon Array.<StateVector> An array of state vectors, one for each of the four major moons of Jupiter, in the following order: 0=Io, 1=Europa, 2=Ganymede, 3=Callisto.

IlluminationInfo

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

Name Type Description
time AstroTime The date and time pertaining to the other calculated values in this object.
mag number The apparent visual magnitude of the celestial body.
phase_angle number The angle in degrees as seen from the center of the celestial body between the Sun and the Earth. The value is always in the range 0 to 180. The phase angle provides a measure of what fraction of the body's face appears illuminated by the Sun as seen from the Earth. When the observed body is the Sun, the phase property is set to 0, although this has no physical meaning because the Sun emits, rather than reflects, light. When the phase is near 0 degrees, the body appears "full". When it is 90 degrees, the body appears "half full". And when it is 180 degrees, the body appears "new" and is very difficult to see because it is both dim and lost in the Sun's glare as seen from the Earth.
phase_fraction number The fraction of the body's face that is illuminated by the Sun, as seen from the Earth. Calculated from phase_angle for convenience. This value ranges from 0 to 1.
helio_dist number The distance between the center of the Sun and the center of the body in astronomical units (AU).
geo_dist number The distance between the center of the Earth and the center of the body in AU.
gc Vector Geocentric coordinates: the 3D vector from the center of the Earth to the center of the body. The components are in expressed in AU and are oriented with respect to the J2000 equatorial plane.
hc Vector Heliocentric coordinates: The 3D vector from the center of the Sun to the center of the body. Like gc, hc is expressed in AU and oriented with respect to the J2000 equatorial plane.
ring_tilt number | undefined For Saturn, this is the angular tilt of the planet's rings in degrees away from the line of sight from the Earth. When the value is near 0, the rings appear edge-on from the Earth and are therefore difficult to see. When ring_tilt approaches its maximum value (about 27 degrees), the rings appear widest and brightest from the Earth. Unlike the JPL Horizons online tool, this library includes the effect of the ring tilt angle in the calculated value for Saturn's visual magnitude. For all bodies other than Saturn, the value of ring_tilt is undefined.

MoonQuarter

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

Name Type Description
quarter number An integer as follows: 0 = new moon, 1 = first quarter, 2 = full moon, 3 = third quarter.
time AstroTime The date and time of the quarter lunar phase.

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

Name Type Description
time AstroTime The date and time of the celestial body reaching the hour angle.
hor HorizontalCoordinates Topocentric horizontal coordinates for the body at the time indicated by the time property.

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

Name Type Description
mar_equinox AstroTime The date and time of the March equinox in the given calendar year. This is the moment in March that the plane of the Earth's equator passes through the center of the Sun; thus the Sun's declination changes from a negative number to a positive number. The March equinox defines the beginning of spring in the northern hemisphere and the beginning of autumn in the southern hemisphere.
jun_solstice AstroTime The date and time of the June solstice in the given calendar year. This is the moment in June that the Sun reaches its most positive declination value. At this moment the Earth's north pole is most tilted most toward the Sun. The June solstice defines the beginning of summer in the northern hemisphere and the beginning of winter in the southern hemisphere.
sep_equinox AstroTime The date and time of the September equinox in the given calendar year. This is the moment in September that the plane of the Earth's equator passes through the center of the Sun; thus the Sun's declination changes from a positive number to a negative number. The September equinox defines the beginning of autumn in the northern hemisphere and the beginning of spring in the southern hemisphere.
dec_solstice AstroTime The date and time of the December solstice in the given calendar year. This is the moment in December that the Sun reaches its most negative declination value. At this moment the Earth's south pole is tilted most toward the Sun. The December solstice defines the beginning of winter in the northern hemisphere and the beginning of summer in the southern hemisphere.

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

Name Type Description
time AstroTime The date and time of the observation.
visibility string Either "morning" or "evening", indicating when the body is most easily seen.
elongation number The angle in degrees, as seen from the center of the Earth, of the apparent separation between the body and the Sun. This angle is measured in 3D space and is not projected onto the ecliptic plane. When elongation is less than a few degrees, the body is very difficult to see from the Earth because it is lost in the Sun's glare. The elongation is always in the range [0, 180].
ecliptic_separation number The absolute value of the difference between the body's ecliptic longitude and the Sun's ecliptic longitude, both as seen from the center of the Earth. This angle measures around the plane of the Earth's orbit (the ecliptic), and ignores how far above or below that plane the body is. The ecliptic separation is measured in degrees and is always in the range [0, 180].

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

Properties

Name Type Description
time AstroTime The date and time of the apsis.
kind number For a closest approach (perigee or perihelion), kind is 0. For a farthest distance event (apogee or aphelion), kind is 1.
dist_au number The distance between the centers of the two bodies in astronomical units (AU).
dist_km number The distance between the centers of the two bodies in kilometers.

ConstellationInfo

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

Name Type Description
symbol string 3-character mnemonic symbol for the constellation, e.g. "Ori".
name string Full name of constellation, e.g. "Orion".
ra1875 number Right ascension expressed in B1875 coordinates.
dec1875 number Declination expressed in B1875 coordinates.

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 strings "penumbral", "partial", or "total", depending on the kind of lunar eclipse found.

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

Name Type Description
kind string The type of lunar eclipse found.
peak AstroTime The time of the eclipse at its peak.
sd_penum number The semi-duration of the penumbral phase in minutes.
sd_partial number The semi-duration of the penumbral phase in minutes, or 0.0 if none.
sd_total number The semi-duration of the penumbral phase in minutes, or 0.0 if none.

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.

Field peak holds the date and time of the peak of the eclipse, defined as the instant when the axis of the Moon's shadow cone passes closest to the Earth's center.

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 strings "partial", "annular", or "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 "total" or "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.
Properties

Name Type Description
kind string One of the following string values: "partial", "annular", "total".
peak AstroTime The date and time of the peak of the eclipse, defined as the instant when the axis of the Moon's shadow cone passes closest to the Earth's center.
distance number The distance in kilometers between the axis of the Moon's shadow cone and the center of the Earth at the time indicated by peak.
latitude number | undefined If kind holds "total", the geographic latitude in degrees where the center of the Moon's shadow falls on the Earth at the time indicated by peak; otherwise, latitude holds undefined.
longitude number | undefined If kind holds "total", the geographic longitude in degrees where the center of the Moon's shadow falls on the Earth at the time indicated by peak; otherwise, longitude holds undefined.

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 (i.e. it at night).

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

Name Type Description
time AstroTime The date and time of the event.
altitude number The angular altitude of the center of the Sun above/below the horizon, at time, corrected for atmospheric refraction and expressed in degrees.

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 "partial", "annular", or "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.

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

Name Type Description
kind string The type of solar eclipse found: "partial", "annular", or "total".
partial_begin EclipseEvent The time and Sun altitude at the beginning of the eclipse.
total_begin EclipseEvent | undefined If this is an annular or a total eclipse, the time and Sun altitude when annular/total phase begins; otherwise undefined.
peak EclipseEvent The time and Sun altitude when the eclipse reaches its peak.
total_end EclipseEvent | undefined If this is an annular or a total eclipse, the time and Sun altitude when annular/total phase ends; otherwise undefined.
partial_end EclipseEvent The time and Sun altitude at the end of the eclipse.

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

Name Type Description
start AstroTime The date and time at the beginning of the transit. This is the moment the planet first becomes visible against the Sun in its background.
peak AstroTime When the planet is most aligned with the Sun, as seen from the Earth.
finish AstroTime The date and time at the end of the transit. This is the moment the planet is last seen against the Sun in its background.
separation number The minimum angular separation, in arcminutes, between the centers of the Sun and the planet. This angle pertains to the time stored in peak.

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

Name Type Description
kind NodeEventKind Whether the node is ascending (south to north) or descending (north to south).
time AstroTime The time when the body passes through the ecliptic plane.

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 equatorial J2000 system (EQJ).
Properties

Name Type Description
ra number The J2000 right ascension of the body's north pole direction, in sidereal hours.
dec number The J2000 declination of the body's north pole direction, in degrees.
spin number Rotation angle of the body's prime meridian, in degrees.
north Vector A J2000 dimensionless unit vector pointing in the direction of the body's north pole.

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.

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.

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.

Param Type Description
a Vector The first of a pair of vectors between which to measure an angle.
b Vector The second of a pair of vectors between which to measure an angle.

MakeTime(date) ⇒ AstroTime

Kind: global function
Brief: Converts multiple date/time formats to AstroTime format.

Given a Date object or a number days since noon (12:00) on January 1, 2000 (UTC), this function creates an AstroTime object.

Given an AstroTime object, returns the same object unmodified. Use of this function is not required for any of the other exposed functions in this library, because they all guarantee converting date/time parameters to AstroTime as needed. However, it may be convenient for callers who need to understand the difference between UTC and TT (Terrestrial Time). In some use cases, converting once to AstroTime format and passing the result into multiple function calls may be more efficient than passing in native JavaScript Date objects.

Param Type Description
date FlexibleDateTime A Date object, a number of UTC days since the J2000 epoch (noon on January 1, 2000), or an AstroTime object. See remarks above.

Libration(date) ⇒ LibrationInfo

Kind: global function
Brief: Calculates the Moon's libration angles at a given moment in time.

Libration is an observed back-and-forth wobble of the portion of the Moon visible from the Earth. It is caused by the imperfect tidal locking of the Moon's fixed rotation rate, compared to its variable angular speed of orbit around the Earth.

This function calculates a pair of perpendicular libration angles, one representing rotation of the Moon in eclitpic longitude elon, the other in ecliptic latitude elat, both relative to the Moon's mean Earth-facing position.

This function also returns the geocentric position of the Moon expressed in ecliptic longitude mlon, ecliptic latitude mlat, the distance dist_km between the centers of the Earth and Moon expressed in kilometers, and the apparent angular diameter of the Moon diam_deg.

Param Type Description
date FlexibleDateTime A Date object, a number of UTC days since the J2000 epoch (noon on January 1, 2000), or an AstroTime object.

MakeRotation(rot) ⇒ RotationMatrix

Kind: global function
Brief: Creates a rotation matrix that can be used to transform one coordinate system to another.

This function verifies that the rot parameter is of the correct format: a number[3][3] array. It throws an exception if rot is not of that shape. Otherwise it creates a new RotationMatrix object based on rot.

Param Type Description
rot Array.<Array.<number>> An array [3][3] of numbers. Defines a rotation matrix used to premultiply a 3D vector to reorient it into another coordinate system.

Horizon(date, observer, ra, dec, refraction) ⇒ HorizontalCoordinates

Kind: global function
Brief: Converts equatorial coordinates to horizontal coordinates.

Given a date and time, a geographic location of an observer on the Earth, and equatorial coordinates (right ascension and declination) of a celestial body, returns horizontal coordinates (azimuth and altitude angles) for that body as seen by that observer. Allows optional correction for atmospheric refraction.

Param Type Description
date FlexibleDateTime The date and time for which to find horizontal coordinates.
observer Observer The location of the observer for which to find horizontal coordinates.
ra number Right ascension in sidereal hours of the celestial object, referred to the mean equinox of date for the J2000 epoch.
dec number Declination in degrees of the celestial object, referred to the mean equator of date for the J2000 epoch. Positive values are north of the celestial equator and negative values are south.
refraction string If omitted or has a false-like value (false, null, undefined, etc.) the calculations are performed without any correction for atmospheric refraction. If the value is the string "normal", uses the recommended refraction correction based on Meeus "Astronomical Algorithms" with a linear taper more than 1 degree below the horizon. The linear taper causes the refraction to linearly approach 0 as the altitude of the body approaches the nadir (-90 degrees). If the value is the string "jplhor", uses a JPL Horizons compatible formula. This is the same algorithm as "normal", only without linear tapering; this can result in physically impossible altitudes of less than -90 degrees, which may cause problems for some applications. (The "jplhor" option was created for unit testing against data generated by JPL Horizons, and is otherwise not recommended for use.)

SunPosition(date) ⇒ EclipticCoordinates

Kind: global function
Brief: Returns apparent geocentric true ecliptic coordinates of date for the Sun.

This function is used for calculating the times of equinoxes and solstices.

Geocentric means coordinates as the Sun would appear to a hypothetical observer at the center of the Earth. Ecliptic coordinates of date are measured along the plane of the Earth's mean orbit around the Sun, using the equinox of the Earth as adjusted for precession and nutation of the Earth's axis of rotation on the given date.

Param Type Description
date FlexibleDateTime The date and time at which to calculate the Sun's apparent location as seen from the center of the Earth.

Equator(body, date, observer, ofdate, aberration) ⇒ EquatorialCoordinates

Kind: global function
Returns: EquatorialCoordinates - The topocentric coordinates of the body as adjusted for the given observer.
Brief: Calculates equatorial coordinates of a Solar System body at a given time.

Returns topocentric equatorial coordinates (right ascension and declination) in one of two different systems: J2000 or true-equator-of-date. Allows optional correction for aberration. Always corrects for light travel time (represents the object as seen by the observer with light traveling to the Earth at finite speed, not where the object is right now). Topocentric refers to a position as seen by an observer on the surface of the Earth. This function corrects for parallax of the object between a geocentric observer and a topocentric observer. This is most significant for the Moon, because it is so close to the Earth. However, it can have a small effect on the apparent positions of other bodies.

Param Type Description
body Body The body for which to find equatorial coordinates. Not allowed to be Body.Earth.
date FlexibleDateTime Specifies the date and time at which the body is to be observed.
observer Observer The location on the Earth of the observer.
ofdate bool Pass true to return equatorial coordinates of date, i.e. corrected for precession and nutation at the given date. This is needed to get correct horizontal coordinates when you call Horizon. Pass false to return equatorial coordinates in the J2000 system.
aberration bool Pass true to correct for aberration, or false to leave uncorrected.

ObserverVector(date, observer, ofdate) ⇒ Vector

Kind: global function
Returns: Vector - An equatorial vector from the center of the Earth to the specified location on (or near) the Earth's surface.
Brief: Calculates geocentric equatorial coordinates of an observer on the surface of the Earth.

This function calculates a vector from the center of the Earth to a point on or near the surface of the Earth, expressed in equatorial coordinates. It takes into account the rotation of the Earth at the given time, along with the given latitude, longitude, and elevation of the observer.

The caller may pass ofdate as true to return coordinates relative to the Earth's equator at the specified time, or false to use the J2000 equator.

The returned vector has components expressed in astronomical units (AU). To convert to kilometers, multiply the x, y, and z values by the constant value KM_PER_AU.

The inverse of this function is also available: VectorObserver.

Param Type Description
date FlexibleDateTime The date and time for which to calculate the observer's position vector.
observer Observer The geographic location of a point on or near the surface of the Earth.
ofdate boolean Selects the date of the Earth's equator in which to express the equatorial coordinates. The caller may pass false to use the orientation of the Earth's equator at noon UTC on January 1, 2000, in which case this function corrects for precession and nutation of the Earth as it was at the moment specified by the time parameter. Or the caller may pass true to use the Earth's equator at time as the orientation.

ObserverState(date, observer, ofdate) ⇒ StateVector

Kind: global function
Brief: Calculates geocentric equatorial position and velocity of an observer on the surface of the Earth.

This function calculates position and velocity vectors of an observer on or near the surface of the Earth, expressed in equatorial coordinates. It takes into account the rotation of the Earth at the given time, along with the given latitude, longitude, and elevation of the observer.

The caller may pass ofdate as true to return coordinates relative to the Earth's equator at the specified time, or false to use the J2000 equator.

The returned position vector has components expressed in astronomical units (AU). To convert to kilometers, multiply the x, y, and z values by the constant value KM_PER_AU. The returned velocity vector has components expressed in AU/day.

Param Type Description
date FlexibleDateTime The date and time for which to calculate the observer's position and velocity vectors.
observer Observer The geographic location of a point on or near the surface of the Earth.
ofdate boolean Selects the date of the Earth's equator in which to express the equatorial coordinates. The caller may pass false to use the orientation of the Earth's equator at noon UTC on January 1, 2000, in which case this function corrects for precession and nutation of the Earth as it was at the moment specified by the time parameter. Or the caller may pass true to use the Earth's equator at time as the orientation.

VectorObserver(vector, ofdate) ⇒ Observer

Kind: global function
Returns: Observer - The geographic latitude, longitude, and elevation above sea level that corresponds to the given equatorial vector.
Brief: Calculates the geographic location corresponding to an equatorial vector.

This is the inverse function of ObserverVector. Given a geocentric equatorial vector, it returns the geographic latitude, longitude, and elevation for that vector.

Param Type Description
vector Vector The geocentric equatorial position vector for which to find geographic coordinates. The components are expressed in Astronomical Units (AU). You can calculate AU by dividing kilometers by the constant KM_PER_AU. The time vector.t determines the Earth's rotation.
ofdate boolean Selects the date of the Earth's equator in which vector is expressed. The caller may select false to use the orientation of the Earth's equator at noon UTC on January 1, 2000, in which case this function corrects for precession and nutation of the Earth as it was at the moment specified by vector.t. Or the caller may select true to use the Earth's equator at vector.t as the orientation.

ObserverGravity(latitude, height) ⇒ number

Kind: global function
Returns: number - The effective gravitational acceleration expressed in meters per second squared [m/s^2].
Brief: Calculates the gravitational acceleration experienced by an observer on the Earth.

This function implements the WGS 84 Ellipsoidal Gravity Formula. The result is a combination of inward gravitational acceleration with outward centrifugal acceleration, as experienced by an observer in the Earth's rotating frame of reference. The resulting value increases toward the Earth's poles and decreases toward the equator, consistent with changes of the weight measured by a spring scale of a fixed mass moved to different latitudes and heights on the Earth.

Param Type Description
latitude number The latitude of the observer in degrees north or south of the equator. By formula symmetry, positive latitudes give the same answer as negative latitudes, so the sign does not matter.
height number The height above the sea level geoid in meters. No range checking is done; however, accuracy is only valid in the range 0 to 100000 meters.

Ecliptic(equ) ⇒ EclipticCoordinates

Kind: global function
Brief: Converts equatorial Cartesian coordinates to ecliptic Cartesian and angular coordinates.

Given J2000 equatorial Cartesian coordinates, returns J2000 ecliptic latitude, longitude, and cartesian coordinates. You can call GeoVector and pass the resulting vector to this function.

Param Type Description
equ Vector A vector in the J2000 equatorial coordinate system.

GeoMoon(date) ⇒ Vector

Kind: global function
Brief: Calculates equatorial geocentric Cartesian coordinates for the Moon.

Given a time of observation, calculates the Moon's position as a vector. The vector gives the location of the Moon's center relative to the Earth's center with x-, y-, and z-components measured in astronomical units. The coordinates are oriented with respect to the Earth's equator at the J2000 epoch. In Astronomy Engine, this orientation is called EQJ. Based on the Nautical Almanac Office's Improved Lunar Ephemeris of 1954, which in turn derives from E. W. Brown's lunar theories. Adapted from Turbo Pascal code from the book Astronomy on the Personal Computer by Montenbruck and Pfleger.

Param Type Description
date FlexibleDateTime The date and time for which to calculate the Moon's geocentric position.

EclipticGeoMoon(date) ⇒ Spherical

Kind: global function
Brief: Calculates spherical ecliptic geocentric position of the Moon.

Given a time of observation, calculates the Moon's geocentric position in ecliptic spherical coordinates. Provides the ecliptic latitude and longitude in degrees, and the geocentric distance in astronomical units (AU). The ecliptic longitude is measured relative to the equinox of date.

This algorithm is based on the Nautical Almanac Office's Improved Lunar Ephemeris of 1954, which in turn derives from E. W. Brown's lunar theories from the early twentieth century. It is adapted from Turbo Pascal code from the book Astronomy on the Personal Compute