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 humanreadable 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 alreadyfound 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 alreadyfound 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 3letter 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 ofdate: 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 xaxis 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 ofdate (EQD) to equatorial J2000 (EQJ). 
Rotation_EQD_ECL  Calculates a rotation matrix from equatorial ofdate (EQD) to ecliptic J2000 (ECL). 
Rotation_EQD_HOR  Calculates a rotation matrix from equatorial ofdate (EQD) to horizontal (HOR). 
Rotation_EQJ_EQD  Calculates a rotation matrix from equatorial J2000 (EQJ) to equatorial ofdate (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 ofdate (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 ofdate (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 bestfit 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. 
string
astroTime.toString() ⇒ Formats an AstroTime
object as an ISO 8601
date/time string in UTC, to millisecond resolution.
Example: 20180817T17:22:04.050Z
Kind: instance method of AstroTime
AstroTime
astroTime.AddDays(days) ⇒ 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
AstroTime.FromTerrestrialTime(tt) ⇒ 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 
SubEarth libration ecliptic latitude angle, in degrees. 
elon  number 
SubEarth 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 xcoordinate expressed in astronomical units (AU). 
y  number 
The ycoordinate expressed in astronomical units (AU). 
z  number 
The zcoordinate expressed in astronomical units (AU). 
t  AstroTime 
The time at which the vector is valid. 
number
vector.Length() ⇒ 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 xcoordinate expressed in astronomical units (AU). 
y  number 
The position ycoordinate expressed in astronomical units (AU). 
z  number 
The position zcoordinate expressed in astronomical units (AU). 
vx  number 
The velocity xcoordinate expressed in AU/day. 
vy  number 
The velocity ycoordinate expressed in AU/day. 
vz  number 
The velocity zcoordinate 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 xaxis is within the ecliptic plane and is oriented in the direction of the equinox. The yaxis is within the ecliptic plane and is oriented 90 degrees counterclockwise from the equinox, as seen from above the Sun's north pole. The zaxis 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 edgeon 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 
3character 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 semiduration 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 semiduration of the penumbral phase in minutes. 
sd_partial  number 
The semiduration of the penumbral phase in minutes, or 0.0 if none. 
sd_total  number 
The semiduration 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 ringshaped 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 ringlike 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 . 
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.
enum
Body : 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.
number
AngleBetween(a, b) ⇒ 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. 
AstroTime
MakeTime(date) ⇒ 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. 
LibrationInfo
Libration(date) ⇒ Kind: global function
Brief: Calculates the Moon's libration angles at a given moment in time.
Libration is an observed backandforth 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 Earthfacing 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. 
RotationMatrix
MakeRotation(rot) ⇒ 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. 
HorizontalCoordinates
Horizon(date, observer, ra, dec, refraction) ⇒ 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 falselike 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.) 
EclipticCoordinates
SunPosition(date) ⇒ 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. 
EquatorialCoordinates
Equator(body, date, observer, ofdate, aberration) ⇒ 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 trueequatorofdate. 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. 
Vector
ObserverVector(date, observer, ofdate) ⇒ 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. 
StateVector
ObserverState(date, observer, ofdate) ⇒ 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. 
Observer
VectorObserver(vector, ofdate) ⇒ 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. 
number
ObserverGravity(latitude, height) ⇒ 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. 
EclipticCoordinates
Ecliptic(equ) ⇒ 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. 
Vector
GeoMoon(date) ⇒ Kind: global function
Brief: Calculates the geocentric Cartesian coordinates for the Moon in the J2000 equatorial system.
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. 
StateVector
GeoMoonState(date) ⇒ Kind: global function
Brief: Calculates the geocentric position and velocity of the Moon at a given time.
Given a time of observation, calculates the Moon's position and velocity vectors. The position and velocity are of the Moon's center relative to the Earth's center. The position (x, y, z) components are expressed in AU (astronomical units). The velocity (vx, vy, vz) components are expressed in AU/day. If you need the Moon's position only, and not its velocity, it is much more efficient to use GeoMoon instead.
Param  Type  Description 

date  FlexibleDateTime 
The date and time for which to calculate the Moon's geocentric state. 
StateVector
GeoEmbState(date) ⇒ Kind: global function
Brief: Calculates the geocentric position and velocity of the Earth/Moon barycenter.
Given a time of observation, calculates the geocentric position and velocity vectors of the Earth/Moon barycenter (EMB). The position (x, y, z) components are expressed in AU (astronomical units). The velocity (vx, vy, vz) components are expressed in AU/day.
Param  Type  Description 

date  FlexibleDateTime 
The date and time for which to calculate the EMB's geocentric state. 
JupiterMoonsInfo
JupiterMoons(date) ⇒ Kind: global function
Returns: JupiterMoonsInfo
 Position and velocity vectors of Jupiter's largest 4 moons.
Brief: Calculates jovicentric positions and velocities of Jupiter's largest 4 moons.
Calculates position and velocity vectors for Jupiter's moons Io, Europa, Ganymede, and Callisto, at the given date and time. The vectors are jovicentric (relative to the center of Jupiter). Their orientation is the Earth's equatorial system at the J2000 epoch (EQJ). The position components are expressed in astronomical units (AU), and the velocity components are in AU/day.
To convert to heliocentric vectors, call HelioVector
with Astronomy.Body.Jupiter
to get Jupiter's heliocentric position, then
add the jovicentric vectors. Likewise, you can call GeoVector
to convert to geocentric vectors.
Param  Type  Description 

date  FlexibleDateTime 
The date and time for which to calculate Jupiter's moons. 
Vector
HelioVector(body, date) ⇒ Kind: global function
Brief: Calculates a vector from the center of the Sun to the given body at the given time.
Calculates heliocentric (i.e., with respect to the center of the Sun) Cartesian coordinates in the J2000 equatorial system of a celestial body at a specified time. The position is not corrected for light travel time or aberration.
Param  Type  Description 

body  Body 
One of the following values: Body.Sun , Body.Moon , Body.Mercury , Body.Venus , Body.Earth , Body.Mars , Body.Jupiter , Body.Saturn , Body.Uranus , Body.Neptune , Body.Pluto , Body.SSB , or Body.EMB . 
date  FlexibleDateTime 
The date and time for which the body's position is to be calculated. 
number
HelioDistance(body, date) ⇒ Kind: global function
Returns: number
 The heliocentric distance in AU.
Brief: Calculates the distance between a body and the Sun at a given time.
Given a date and time, this function calculates the distance between
the center of body
and the center of the Sun.
For the planets Mercury through Neptune, this function is significantly
more efficient than calling HelioVector followed by taking the length
of the resulting vector.
Param  Type  Description 

body  Body 
A body for which to calculate a heliocentric distance: the Sun, Moon, or any of the planets. 
date  FlexibleDateTime 
The date and time for which to calculate the heliocentric distance. 
Vector
GeoVector(body, date, aberration) ⇒ Kind: global function
Brief: Calculates a vector from the center of the Earth to the given body at the given time.
Calculates geocentric (i.e., with respect to the center of the Earth) Cartesian coordinates in the J2000 equatorial system of a celestial body at a specified time. The position is always corrected for light travel time: this means the position of the body is "backdated" based on how long it takes light to travel from the body to an observer on the Earth. Also, the position can optionally be corrected for aberration, an effect causing the apparent direction of the body to be shifted based on transverse movement of the Earth with respect to the rays of light coming from that body.
Param  Type  Description 

body  Body 
One of the following values: Body.Sun , Body.Moon , Body.Mercury , Body.Venus , Body.Earth , Body.Mars , Body.Jupiter , Body.Saturn , Body.Uranus , Body.Neptune , or Body.Pluto . 
date  FlexibleDateTime 
The date and time for which the body's position is to be calculated. 
aberration  bool 
Pass true to correct for aberration, or false to leave uncorrected. 
StateVector
BaryState(body, date) ⇒ 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 equatorial J2000 coordinates (EQJ).
Param  Type  Description 

body  Body 
The celestial body whose barycentric state vector is to be calculated. Supported values are Body.Sun , Body.Moon , Body.EMB , Body.SSB , and all planets: Body.Mercury , Body.Venus , Body.Earth , Body.Mars , Body.Jupiter , Body.Saturn , Body.Uranus , Body.Neptune , Body.Pluto . 
date  FlexibleDateTime 
The date and time for which to calculate position and velocity. 
StateVector
HelioState(body, date) ⇒ Kind: global function
Returns: StateVector
 An object that contains heliocentric position and velocity vectors.
Brief: Calculates heliocentric position and velocity vectors for the given body.
Given a body and a time, calculates the position and velocity vectors for the center of that body at that time, relative to the center of the Sun. The vectors are expressed in equatorial J2000 coordinates (EQJ). If you need the position vector only, it is more efficient to call HelioVector. The Sun's center is a noninertial frame of reference. In other words, the Sun experiences acceleration due to gravitational forces, mostly from the larger planets (Jupiter, Saturn, Uranus, and Neptune). If you want to calculate momentum, kinetic energy, or other quantities that require a nonaccelerating frame of reference, consider using BaryState instead.
Param  Type  Description 

body  Body 
The celestial body whose heliocentric state vector is to be calculated. Supported values are Body.Sun , Body.Moon , Body.EMB , Body.SSB , and all planets: Body.Mercury , Body.Venus , Body.Earth , Body.Mars , Body.Jupiter , Body.Saturn , Body.Uranus , Body.Neptune , Body.Pluto . 
date  FlexibleDateTime 
The date and time for which to calculate position and velocity. 
AstroTime
 null
Search(func, t1, t2, options) ⇒ Kind: global function
Returns: AstroTime
 null
 If the search is successful, returns the date and time of the solution.
If the search fails, returns null
.
Brief: Finds the time when a function ascends through zero.
Search for next time t (such that t is between t1
and t2
)
that func(t)
crosses from a negative value to a nonnegative value.
The given function must have "smooth" behavior over the entire inclusive range [t1
, t2
],
meaning that it behaves like a continuous differentiable function.
It is not required that t1
< t2
; t1
> t2
allows searching backward in time.
Note: t1
and t2
must be chosen such that there is no possibility
of more than one zerocrossing (ascending or descending), or it is possible
that the "wrong" event will be found (i.e. not the first event after t1)
or even that the function will return null
, indicating that no event was found.
Param  Type  Description 

func  function 
The function to find an ascending zero crossing for. The function must accept a single parameter of type AstroTime and return a numeric value. 
t1  AstroTime 
The lower time bound of a search window. 
t2  AstroTime 
The upper time bound of a search window. 
options 
SearchOptions  undefined

Options that can tune the behavior of the search. Most callers can omit this argument. 
AstroTime
 null
SearchSunLongitude(targetLon, dateStart, limitDays) ⇒ Kind: global function
Returns: AstroTime
 null
 The date and time when the Sun reaches the apparent ecliptic longitude targetLon
within the range of times specified by dateStart
and limitDays
.
If the Sun does not reach the target longitude within the specified time range, or the
time range is excessively wide, the return value is null
.
To avoid a null
return value, the caller must pick a time window around
the event that is within a few days but not so small that the event might fall outside the window.
Brief: Searches for when the Sun reaches a given ecliptic longitude.
Searches for the moment in time when the center of the Sun reaches a given apparent
ecliptic longitude, as seen from the center of the Earth, within a given range of dates.
This function can be used to determine equinoxes and solstices.
However, it is usually more convenient and efficient to call Seasons
to calculate equinoxes and solstices for a given calendar year.
SearchSunLongitude
is more general in that it allows searching for arbitrary longitude values.
Param  Type  Description 

targetLon  number 
The desired ecliptic longitude of date in degrees. This may be any value in the range [0, 360), although certain values have conventional meanings: When targetLon is 0, finds the March equinox, which is the moment spring begins in the northern hemisphere and the beginning of autumn in the southern hemisphere. When targetLon is 180, finds the September equinox, which is the moment autumn begins in the northern hemisphere and spring begins in the southern hemisphere. When targetLon is 90, finds the northern solstice, which is the moment summer begins in the northern hemisphere and winter begins in the southern hemisphere. When targetLon is 270, finds the southern solstice, which is the moment winter begins in the northern hemisphere and summer begins in the southern hemisphere. 
dateStart  FlexibleDateTime 
A date and time known to be earlier than the desired longitude event. 
limitDays  number 
A floating point number of days, which when added to dateStart , yields a date and time known to be after the desired longitude event. 
number
PairLongitude(body1, body2, date) ⇒ Kind: global function
Returns: number
 An angle in the range [0, 360), expressed in degrees.
Brief: Returns one body's ecliptic longitude with respect to another, as seen from the Earth.
This function determines where one body appears around the ecliptic plane
(the plane of the Earth's orbit around the Sun) as seen from the Earth,
relative to the another body's apparent position.
The function returns an angle in the halfopen range [0, 360) degrees.
The value is the ecliptic longitude of body1
relative to the ecliptic
longitude of body2
.
The angle is 0 when the two bodies are at the same ecliptic longitude as seen from the Earth. The angle increases in the prograde direction (the direction that the planets orbit the Sun and the Moon orbits the Earth).
When the angle is 180 degrees, it means the two bodies appear on opposite sides of the sky for an Earthly observer.
Neither body1
nor body2
is allowed to be Body.Earth
.
If this happens, the function throws an exception.
Param  Type  Description 

body1  Body 
The first body, whose longitude is to be found relative to the second body. 
body2  Body 
The second body, relative to which the longitude of the first body is to be found. 
date  FlexibleDateTime 
The date and time of the observation. 
number
AngleFromSun(body, date) ⇒ 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
.
Param  Type  Description 

body  Body 
The name of a supported celestial body other than the Earth. 
date  FlexibleDateTime 
The time at which the angle from the Sun is to be found. 
number
EclipticLongitude(body, date) ⇒ Kind: global function
Returns: number
 The ecliptic longitude angle of the body in degrees measured counterclockwise around the mean
plane of the Earth's orbit, as seen from above the Sun's north pole.
Ecliptic longitude starts at 0 at the J2000
equinox and
increases in the same direction the Earth orbits the Sun.
The returned value is always in the range [0, 360).
Brief: Calculates heliocentric ecliptic longitude based on the J2000 equinox.
Param  Type  Description 

body  Body 
The name of a celestial body other than the Sun. 
date  FlexibleDateTime 
The date and time for which to calculate the ecliptic longitude. 
IlluminationInfo
Illumination(body, date) ⇒ Kind: global function
Brief: Calculates visual magnitude and related information about a body.
Calculates the phase angle, visual magnitude, and other values relating to the body's illumination at the given date and time, as seen from the Earth.
Param  Type  Description 

body  Body 
The name of the celestial body being observed. Not allowed to be Body.Earth . 
date  FlexibleDateTime 
The date and time for which to calculate the illumination data for the given body. 
AstroTime
SearchRelativeLongitude(body, targetRelLon, startDate) ⇒ Kind: global function
Returns: AstroTime
 The time when the Earth and the body next reach the specified relative longitudes.
Brief: Searches for when the Earth and a given body reach a relative ecliptic longitude separation.
Searches for the date and time the relative ecliptic longitudes of
the specified body and the Earth, as seen from the Sun, reach a certain
difference. This function is useful for finding conjunctions and oppositions
of the planets. For the opposition of a superior planet (Mars, Jupiter, ..., Pluto),
or the inferior conjunction of an inferior planet (Mercury, Venus),
call with targetRelLon
= 0. The 0 value indicates that both
planets are on the same ecliptic longitude line, ignoring the other planet's
distance above or below the plane of the Earth's orbit.
For superior conjunctions, call with targetRelLon
= 180.
This means the Earth and the other planet are on opposite sides of the Sun.
Param  Type  Description 

body  Body 
Any planet other than the Earth. 
targetRelLon  number 
The desired angular difference in degrees between the ecliptic longitudes of body and the Earth. Must be in the range (180, +180]. 
startDate  FlexibleDateTime 
The date and time after which to find the next occurrence of the body and the Earth reaching the desired relative longitude. 
number
MoonPhase(date) ⇒ Kind: global function
Returns: number
 A value in the range [0, 360) indicating the difference
in ecliptic longitude between the center of the Sun and the
center of the Moon, as seen from the center of the Earth.
Certain longitude values have conventional meanings:
 0 = new moon
 90 = first quarter
 180 = full moon
 270 = third quarter
Brief: Determines the moon's phase expressed as an ecliptic longitude.
Param  Type  Description 

date  FlexibleDateTime 
The date and time for which to calculate the moon's phase. 
AstroTime
 null
SearchMoonPhase(targetLon, dateStart, limitDays) ⇒ Kind: global function
Returns: AstroTime
 null
 If the specified lunar phase occurs after dateStart
and before limitDays
days after dateStart
,
this function returns the date and time of the first such occurrence.
Otherwise, it returns null
.
Brief: Searches for the date and time that the Moon reaches a specified phase.
Lunar phases are defined in terms of geocentric ecliptic longitudes
with respect to the Sun. When the Moon and the Sun have the same ecliptic
longitude, that is defined as a new moon. When the two ecliptic longitudes
are 180 degrees apart, that is defined as a full moon.
To enumerate quarter lunar phases, it is simpler to call
SearchMoonQuarter once, followed by repeatedly calling
NextMoonQuarter. SearchMoonPhase
is only
necessary for finding other lunar phases than the usual quarter phases.
Param  Type  Description 

targetLon  number 
The difference in geocentric ecliptic longitude between the Sun and Moon that specifies the lunar phase being sought. This can be any value in the range [0, 360). Here are some helpful examples: 0 = new moon, 90 = first quarter, 180 = full moon, 270 = third quarter. 
dateStart  FlexibleDateTime 
The beginning of the window of time in which to search. 
limitDays  number 
The floating point number of days after dateStart that limits the window of time in which to search. 
MoonQuarter
SearchMoonQuarter(dateStart) ⇒ Kind: global function
Brief: Finds the first quarter lunar phase after the specified date and time.
The quarter lunar phases are: new moon, first quarter, full moon, and third quarter.
To enumerate quarter lunar phases, call SearchMoonQuarter
once,
then pass its return value to NextMoonQuarter to find the next
MoonQuarter
. Keep calling NextMoonQuarter
in a loop,
passing the previous return value as the argument to the next call.
Param  Type  Description 

dateStart  FlexibleDateTime 
The date and time after which to find the first quarter lunar phase. 
MoonQuarter
NextMoonQuarter(mq) ⇒ Kind: global function
Brief: Finds the next quarter lunar phase in a series.
Given a MoonQuarter object, finds the next consecutive quarter lunar phase. See remarks in SearchMoonQuarter for explanation of usage.
Param  Type  Description 

mq  MoonQuarter 
The return value of a prior call to MoonQuarter or NextMoonQuarter . 
AstroTime
 null
SearchRiseSet(body, observer, direction, dateStart, limitDays) ⇒ Kind: global function
Returns: AstroTime
 null
 The date and time of the rise or set event, or null if no such event
occurs within the specified time window.
Brief: Finds the next rise or set time for a body.
Finds a rise or set time for the given body as seen by an observer at the specified location on the Earth. Rise time is defined as the moment when the top of the body is observed to first appear above the horizon in the east. Set time is defined as the moment the top of the body is observed to sink below the horizon in the west. The times are adjusted for typical atmospheric refraction conditions.
Param  Type  Description 

body  Body 
The body to find the rise or set time for. 
observer  Observer 
Specifies the geographic coordinates and elevation above sea level of the observer. 
direction  number 
Either +1 to find rise time or 1 to find set time. Any other value will cause an exception to be thrown. 
dateStart  FlexibleDateTime 
The date and time after which the specified rise or set time is to be found. 
limitDays  number 
The fractional number of days after dateStart that limits when the rise or set time is to be found. 
AstroTime
 null
SearchAltitude(body, observer, direction, dateStart, limitDays, altitude) ⇒ Kind: global function
Returns: AstroTime
 null
 The date and time of the altitude event, or null if no such event
occurs within the specified time window.
Brief: Finds the next time a body reaches a given altitude.
Finds when the given body ascends or descends through a given
altitude angle, as seen by an observer at the specified location on the Earth.
By using the appropriate combination of direction
and altitude
parameters,
this function can be used to find when civil, nautical, or astronomical twilight
begins (dawn) or ends (dusk).
Civil dawn begins before sunrise when the Sun ascends through 6 degrees below
the horizon. To find civil dawn, pass +1 for direction
and 6 for altitude
.
Civil dusk ends after sunset when the Sun descends through 6 degrees below the horizon.
To find civil dusk, pass 1 for direction
and 6 for altitude
.
Nautical twilight is similar to civil twilight, only the altitude
value should be 12 degrees.
Astronomical twilight uses 18 degrees as the altitude
value.
Param  Type  Description 

body  Body 
The body for which to find the altitude event. Can be the Sun, Moon, or any planet other than the Earth. 
observer  Observer 
Specifies the geographic coordinates and elevation above sea level of the observer. 
direction  number 
Either +1 to find when the body ascends through the altitude, or 1 for when the body descends through the altitude. Any other value will cause an exception to be thrown. 
dateStart  FlexibleDateTime 
The date and time after which the specified altitude event is to be found. 
limitDays  number 
The fractional number of days after dateStart that limits when the altitude event is to be found. Must be a positive number. 
altitude  number 
The desired altitude angle of the body's center above (positive) or below (negative) the observer's local horizon, expressed in degrees. Must be in the range [90, +90]. 
HourAngleEvent
SearchHourAngle(body, observer, hourAngle, dateStart) ⇒ Kind: global function
Brief: Finds when a body will reach a given hour angle.
Finds the next time the given body is seen to reach the specified
hour angle
by the given observer.
Providing hourAngle
= 0 finds the next maximum altitude event (culmination).
Providing hourAngle
= 12 finds the next minimum altitude event.
Note that, especially close to the Earth's poles, a body as seen on a given day
may always be above the horizon or always below the horizon, so the caller cannot
assume that a culminating object is visible nor that an object is below the horizon
at its minimum altitude.
Param  Type  Description 

body  Body 
A celestial body other than the Earth. 
observer  Observer 
Specifies the geographic coordinates and elevation above sea level of the observer. 
hourAngle  number 
The hour angle expressed in sidereal hours for which the caller seeks to find the body attain. The value must be in the range [0, 24). The hour angle represents the number of sidereal hours that have elapsed since the most recent time the body crossed the observer's local meridian. This specifying hourAngle = 0 finds the moment in time the body reaches the highest angular altitude in a given sidereal day. 
dateStart  FlexibleDateTime 
The date and time after which the desired hour angle crossing event is to be found. 
SeasonInfo
Seasons(year) ⇒ Kind: global function
Brief: Finds the equinoxes and solstices for a given calendar year.
Param  Type  Description 

year 
number  AstroTime

The integer value or AstroTime object that specifies the UTC calendar year for which to find equinoxes and solstices. 
ElongationEvent
Elongation(body, date) ⇒ Kind: global function
Brief: Calculates the viewing conditions of a body relative to the Sun.
Calculates 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 the return type ElongationEvent for details.
This function is helpful for determining how easy it is to view a planet away from the Sun's glare on a given date. It also determines whether the object is visible in the morning or evening; this is more important the smaller the elongation is. It is also used to determine how far a planet is from opposition, conjunction, or quadrature.
Param  Type  Description 

body  Body 
The name of the observed body. Not allowed to be Body.Earth . 
date  FlexibleDateTime 
The date and time of the observation. 
ElongationEvent
SearchMaxElongation(body, startDate) ⇒ Kind: global function
Brief: Finds the next time Mercury or Venus reaches maximum elongation.
Searches for the next maximum elongation event for Mercury or Venus
that occurs after the given start date. Calling with other values
of body
will result in an exception.
Maximum elongation occurs when the body has the greatest
angular separation from the Sun, as seen from the Earth.
Returns an ElongationEvent
object containing the date and time of the next
maximum elongation, the elongation in degrees, and whether
the body is visible in the morning or evening.
Param  Type  Description 

body  Body 
Either Body.Mercury or Body.Venus . 
startDate  FlexibleDateTime 
The date and time after which to search for the next maximum elongation event. 
IlluminationInfo
SearchPeakMagnitude(body, startDate) ⇒ Kind: global function
Brief: Searches for the date and time Venus will next appear brightest as seen from the Earth.
Param  Type  Description 

body  Body 
Currently only Body.Venus is supported. Mercury's peak magnitude occurs at superior conjunction, when it is impossible to see from Earth, so peak magnitude events have little practical value for that planet. The Moon reaches peak magnitude very close to full moon, which can be found using SearchMoonQuarter or SearchMoonPhase. The other planets reach peak magnitude very close to opposition, which can be found using SearchRelativeLongitude. 
startDate  FlexibleDateTime 
The date and time after which to find the next peak magnitude event. 
Apsis
SearchLunarApsis(startDate) ⇒ Kind: global function
Brief: Finds the next perigee or apogee of the Moon.
Finds the next perigee (closest approach) or apogee (farthest remove) of the Moon that occurs after the specified date and time.
Param  Type  Description 

startDate  FlexibleDateTime 
The date and time after which to find the next perigee or apogee. 
Apsis
NextLunarApsis(apsis) ⇒ Kind: global function
Returns: Apsis
 The successor apogee for the given perigee, or the successor perigee for the given apogee.
Brief: Finds the next lunar apsis (perigee or apogee) in a series.
Given a lunar apsis returned by an initial call to SearchLunarApsis,
or a previous call to NextLunarApsis
, finds the next lunar apsis.
If the given apsis is a perigee, this function finds the next apogee, and vice versa.
Param  Type  Description 

apsis  Apsis 
A lunar perigee or apogee event. 
Apsis
SearchPlanetApsis(body, startTime) ⇒ Kind: global function
Returns: Apsis
 The next perihelion or aphelion that occurs after startTime
.
Brief: Finds the next perihelion or aphelion of a planet.
Finds the date and time of a planet's perihelion (closest approach to the Sun) or aphelion (farthest distance from the Sun) after a given time.
Given a date and time to start the search in startTime
, this function finds the
next date and time that the center of the specified planet reaches the closest or farthest point
in its orbit with respect to the center of the Sun, whichever comes first
after startTime
.
The closest point is called perihelion and the farthest point is called aphelion. The word apsis refers to either event.
To iterate through consecutive alternating perihelion and aphelion events,
call SearchPlanetApsis
once, then use the return value to call
NextPlanetApsis. After that, keep feeding the previous return value
from NextPlanetApsis
into another call of NextPlanetApsis
as many times as desired.
Param  Type  Description 

body  Body 
The planet for which to find the next perihelion/aphelion event. Not allowed to be Body.Sun or Body.Moon . 
startTime  FlexibleDateTime 
The date and time at which to start searching for the next perihelion or aphelion. 
Apsis
NextPlanetApsis(body, apsis) ⇒ Kind: global function
Returns: Apsis
 Same as the return value for SearchPlanetApsis.
Brief: Finds the next planetary perihelion or aphelion event in a series.
This function requires an Apsis value obtained from a call
to SearchPlanetApsis or NextPlanetApsis
.
Given an aphelion event, this function finds the next perihelion event, and vice versa.
See SearchPlanetApsis for more details.
Param  Type  Description 

body  Body 
The planet for which to find the next perihelion/aphelion event. Not allowed to be Body.Sun or Body.Moon . Must match the body passed into the call that produced the apsis parameter. 
apsis  Apsis 
An apsis event obtained from a call to SearchPlanetApsis or NextPlanetApsis . 
RotationMatrix
InverseRotation(rotation) ⇒ Kind: global function
Returns: RotationMatrix
 The inverse rotation matrix.
Brief: Calculates the inverse of a rotation matrix.
Given a rotation matrix that performs some coordinate transform, this function returns the matrix that reverses that trasnform.
Param  Type  Description 

rotation  RotationMatrix 
The rotation matrix to be inverted. 
RotationMatrix
CombineRotation(a, b) ⇒ Kind: global function
Returns: RotationMatrix
 The combined rotation matrix.
Brief: Creates a rotation based on applying one rotation followed by another.
Given two rotation matrices, returns a combined rotation matrix that is equivalent to rotating based on the first matrix, followed by the second.
Param  Type  Description 

a  RotationMatrix 
The first rotation to apply. 
b  RotationMatrix 
The second rotation to apply. 
RotationMatrix
IdentityMatrix() ⇒ Kind: global function
Returns: RotationMatrix
 The identity matrix.
Brief: Creates an identity rotation matrix.
Returns a rotation matrix that has no effect on orientation. This matrix can be the starting point for other operations, such as using a series of calls to Pivot to create a custom rotation matrix.
RotationMatrix
Pivot(rotation, axis, angle) ⇒ Kind: global function
Returns: RotationMatrix
 A pivoted matrix object.
Brief: Reorients a rotation matrix by pivoting it by an angle around one of its axes.
Given a rotation matrix, a selected coordinate axis, and an angle in degrees, this function pivots the rotation matrix by that angle around that coordinate axis.
For example, if you have rotation matrix that converts ecliptic coordinates (ECL)
to horizontal coordinates (HOR), but you really want to convert ECL to the orientation
of a telescope camera pointed at a given body, you can use Astronomy_Pivot
twice:
(1) pivot around the zenith axis by the body's azimuth, then (2) pivot around the
western axis by the body's altitude angle. The resulting rotation matrix will then
reorient ECL coordinates to the orientation of your telescope camera.
Param  Type  Description 

rotation  RotationMatrix 
The input rotation matrix. 
axis  number 
An integer that selects which coordinate axis to rotate around: 0 = x, 1 = y, 2 = z. Any other value will cause an exception. 
angle  number 
An angle in degrees indicating the amount of rotation around the specified axis. Positive angles indicate rotation counterclockwise as seen from the positive direction along that axis, looking towards the origin point of the orientation system. Any finite number of degrees is allowed, but best precision will result from keeping angle in the range [360, +360]. 
Vector
VectorFromSphere(sphere, time) ⇒ Kind: global function
Returns: Vector
 The vector form of the supplied spherical coordinates.
Brief: Converts spherical coordinates to Cartesian coordinates.
Given spherical coordinates and a time at which they are valid,
returns a vector of Cartesian coordinates. The returned value
includes the time, as required by AstroTime
.
Param  Type  Description 

sphere  Spherical 
Spherical coordinates to be converted. 
time  FlexibleDateTime 
The time that should be included in the returned vector. 
EquatorialCoordinates
EquatorFromVector(vec) ⇒ Kind: global function
Returns: EquatorialCoordinates
 Angular coordinates expressed in the same equatorial system as vec
.
Brief: Given an equatorial vector, calculates equatorial angular coordinates.
Param  Type  Description 

vec  Vector 
A vector in an equatorial coordinate system. 
Spherical
SphereFromVector(vector) ⇒ Kind: global function
Returns: Spherical
 Spherical coordinates that are equivalent to the given vector.
Brief: Converts Cartesian coordinates to spherical coordinates.
Given a Cartesian vector, returns latitude, longitude, and distance.
Param  Type  Description 

vector  Vector 
Cartesian vector to be converted to spherical coordinates. 
Spherical
HorizonFromVector(vector, refraction) ⇒ Kind: global function
Brief: Converts Cartesian coordinates to horizontal coordinates.
Given a horizontal Cartesian vector, returns horizontal azimuth and altitude.
IMPORTANT: This function differs from SphereFromVector in two ways:

SphereFromVector
returns alon
value that represents azimuth defined counterclockwise from north (e.g., west = +90), but this function represents a clockwise rotation (e.g., east = +90). The difference is becauseSphereFromVector
is intended to preserve the vector "righthand rule", while this function defines azimuth in a more traditional way as used in navigation and cartography.  This function optionally corrects for atmospheric refraction, while
SphereFromVector
does not.
The returned object contains the azimuth in lon
.
It is measured in degrees clockwise from north: east = +90 degrees, west = +270 degrees.
The altitude is stored in lat
.
The distance to the observed object is stored in dist
,
and is expressed in astronomical units (AU).
Param  Type  Description 

vector  Vector 
Cartesian vector to be converted to horizontal coordinates. 
refraction  string 
"normal" : correct altitude for atmospheric refraction (recommended). "jplhor" : for JPL Horizons compatibility testing only; not recommended for normal use. null : no atmospheric refraction correction is performed. 
Vector
VectorFromHorizon(sphere, time, refraction) ⇒ Kind: global function
Returns: Vector
 A vector in the horizontal system: x
= north, y
= west, and z
= zenith (up).
Brief: Given apparent angular horizontal coordinates in sphere
, calculate horizontal vector.
Param  Type  Description 

sphere  Spherical 
A structure that contains apparent horizontal coordinates: lat holds the refracted azimuth angle, lon holds the azimuth in degrees clockwise from north, and dist holds the distance from the observer to the object in AU. 
time  FlexibleDateTime 
The date and time of the observation. This is needed because the returned vector object requires a valid time value when passed to certain other functions. 
refraction  string 
"normal" : correct altitude for atmospheric refraction (recommended). "jplhor" : for JPL Horizons compatibility testing only; not recommended for normal use. null : no atmospheric refraction correction is performed. 
number
Refraction(refraction, altitude) ⇒ Kind: global function
Returns: number
 The angular adjustment in degrees to be added to the altitude angle to correct for atmospheric lensing.
Brief: Calculates the amount of "lift" to an altitude angle caused by atmospheric refraction.
Given an altitude angle and a refraction option, calculates the amount of "lift" caused by atmospheric refraction. This is the number of degrees higher in the sky an object appears due to the lensing of the Earth's atmosphere.
Param  Type  Description 

refraction  string 
"normal" : correct altitude for atmospheric refraction (recommended). "jplhor" : for JPL Horizons compatibility testing only; not recommended for normal use. null : no atmospheric refraction correction is performed. 
altitude  number 
An altitude angle in a horizontal coordinate system. Must be a value between 90 and +90. 
number
InverseRefraction(refraction, bent_altitude) ⇒ Kind: global function
Returns: number
 The angular adjustment in degrees to be added to the
altitude angle to correct for atmospheric lensing.
This will be less than or equal to zero.
Brief: Calculates the inverse of an atmospheric refraction angle.
Given an observed altitude angle that includes atmospheric refraction, calculate the negative angular correction to obtain the unrefracted altitude. This is useful for cases where observed horizontal coordinates are to be converted to another orientation system, but refraction first must be removed from the observed position.
Param  Type  Description 

refraction  string 
"normal" : correct altitude for atmospheric refraction (recommended). "jplhor" : for JPL Horizons compatibility testing only; not recommended for normal use. null : no atmospheric refraction correction is performed. 
bent_altitude  number 
The apparent altitude that includes atmospheric refraction. 
Vector
RotateVector(rotation, vector) ⇒ Kind: global function
Returns: Vector
 A vector in the orientation specified by rotation
.
Brief: Applies a rotation to a vector, yielding a rotated vector.
This function transforms a vector in one orientation to a vector in another orientation.
Param  Type  Description 

rotation  RotationMatrix 
A rotation matrix that specifies how the orientation of the vector is to be changed. 
vector  Vector 
The vector whose orientation is to be changed. 
StateVector
RotateState(rotation, state) ⇒ Kind: global function
Returns: StateVector
 A state vector in the orientation specified by rotation
.
Brief: Applies a rotation to a state vector, yielding a rotated vector.
This function transforms a state vector in one orientation to a vector in another orientation.
Param  Type  Description 

rotation  RotationMatrix 
A rotation matrix that specifies how the orientation of the state vector is to be changed. 
state  StateVector 
The state vector whose orientation is to be changed. Both the position and velocity components are transformed. 
RotationMatrix
Rotation_EQJ_ECL() ⇒ Kind: global function
Returns: RotationMatrix
 A rotation matrix that converts EQJ to ECL.
Brief: Calculates a rotation matrix from equatorial J2000 (EQJ) to ecliptic J2000 (ECL).
This is one of the family of functions that returns a rotation matrix for converting from one orientation to another. Source: EQJ = equatorial system, using equator at J2000 epoch. Target: ECL = ecliptic system, using equator at J2000 epoch.
RotationMatrix
Rotation_ECL_EQJ() ⇒ Kind: global function
Returns: RotationMatrix
 A rotation matrix that converts ECL to EQJ.
Brief: Calculates a rotation matrix from ecliptic J2000 (ECL) to equatorial J2000 (EQJ).
This is one of the family of functions that returns a rotation matrix for converting from one orientation to another. Source: ECL = ecliptic system, using equator at J2000 epoch. Target: EQJ = equatorial system, using equator at J2000 epoch.
RotationMatrix
Rotation_EQJ_EQD(time) ⇒ Kind: global function
Returns: RotationMatrix
 A rotation matrix that converts EQJ to EQD at time
.
Brief: Calculates a rotation matrix from equatorial J2000 (EQJ) to equatorial ofdate (EQD).
This is one of the family of functions that returns a rotation matrix for converting from one orientation to another. Source: EQJ = equatorial system, using equator at J2000 epoch. Target: EQD = equatorial system, using equator of the specified date/time.
Param  Type  Description 

time  FlexibleDateTime 
The date and time at which the Earth's equator defines the target orientation. 
RotationMatrix
Rotation_EQD_EQJ(time) ⇒ Kind: global function
Returns: RotationMatrix
 A rotation matrix that converts EQD at time
to EQJ.
Brief: Calculates a rotation matrix from equatorial ofdate (EQD) to equatorial J2000 (EQJ).
This is one of the family of functions that returns a rotation matrix for converting from one orientation to another. Source: EQD = equatorial system, using equator of the specified date/time. Target: EQJ = equatorial system, using equator at J2000 epoch.
Param  Type  Description 

time  FlexibleDateTime 
The date and time at which the Earth's equator defines the source orientation. 
RotationMatrix
Rotation_EQD_HOR(time, observer) ⇒ Kind: global function
Returns: RotationMatrix
 A rotation matrix that converts EQD to HOR at time
and for observer
.
The components of the horizontal vector are:
x = north, y = west, z = zenith (straight up from the observer).
These components are chosen so that the "righthand rule" works for the vector
and so that north represents the direction where azimuth = 0.
Brief: Calculates a rotation matrix from equatorial ofdate (EQD) to horizontal (HOR).
This is one of the family of functions that returns a rotation matrix for converting from one orientation to another. Source: EQD = equatorial system, using equator of the specified date/time. Target: HOR = horizontal system.
Use HorizonFromVector
to convert the return value
to a traditional altitude/azimuth pair.
Param  Type  Description 

time  FlexibleDateTime 
The date and time at which the Earth's equator applies. 
observer  Observer 
A location near the Earth's mean sea level that defines the observer's horizon. 
RotationMatrix
Rotation_HOR_EQD(time, observer) ⇒ Kind: global function
Returns: RotationMatrix
 A rotation matrix that converts HOR to EQD at time
and for observer
.
Brief: Calculates a rotation matrix from horizontal (HOR) to equatorial ofdate (EQD).
This is one of the family of functions that returns a rotation matrix for converting from one orientation to another. Source: HOR = horizontal system (x=North, y=West, z=Zenith). Target: EQD = equatorial system, using equator of the specified date/time.
Param  Type  Description 

time  FlexibleDateTime 
The date and time at which the Earth's equator applies. 
observer  Observer 
A location near the Earth's mean sea level that defines the observer's horizon. 
RotationMatrix
Rotation_HOR_EQJ(time, observer) ⇒ Kind: global function
Returns: RotationMatrix
 A rotation matrix that converts HOR to EQD at time
and for observer
.
Brief: Calculates a rotation matrix from horizontal (HOR) to J2000 equatorial (EQJ).
This is one of the family of functions that returns a rotation matrix for converting from one orientation to another. Source: HOR = horizontal system (x=North, y=West, z=Zenith). Target: EQJ = equatorial system, using equator at the J2000 epoch.
Param  Type  Description 

time  FlexibleDateTime 
The date and time of the observation. 
observer  Observer 
A location near the Earth's mean sea level that defines the observer's horizon. 
RotationMatrix
Rotation_EQJ_HOR(time, observer) ⇒ Kind: global function
Returns: RotationMatrix
 A rotation matrix that converts EQJ to HOR at time
and for observer
.
The components of the horizontal vector are:
x = north, y = west, z = zenith (straight up from the observer).
These components are chosen so that the "righthand rule" works for the vector
and so that north represents the direction where azimuth = 0.
Brief: Calculates a rotation matrix from equatorial J2000 (EQJ) to horizontal (HOR).
This is one of the family of functions that returns a rotation matrix for converting from one orientation to another. Source: EQJ = equatorial system, using the equator at the J2000 epoch. Target: HOR = horizontal system.
Use HorizonFromVector to convert the return value to a traditional altitude/azimuth pair.
Param  Type  Description 

time  FlexibleDateTime 
The date and time of the desired horizontal orientation. 
observer  Observer 
A location near the Earth's mean sea level that defines the observer's horizon. 
RotationMatrix
Rotation_EQD_ECL(time) ⇒ Kind: global function
Returns: RotationMatrix
 A rotation matrix that converts EQD to ECL.
Brief: Calculates a rotation matrix from equatorial ofdate (EQD) to ecliptic J2000 (ECL).
This is one of the family of functions that returns a rotation matrix for converting from one orientation to another. Source: EQD = equatorial system, using equator of date. Target: ECL = ecliptic system, using equator at J2000 epoch.
Param  Type  Description 

time  FlexibleDateTime 
The date and time of the source equator. 
RotationMatrix
Rotation_ECL_EQD(time) ⇒ Kind: global function
Returns: RotationMatrix
 A rotation matrix that converts ECL to EQD.
Brief: Calculates a rotation matrix from ecliptic J2000 (ECL) to equatorial ofdate (EQD).
This is one of the family of functions that returns a rotation matrix for converting from one orientation to another. Source: ECL = ecliptic system, using equator at J2000 epoch. Target: EQD = equatorial system, using equator of date.
Param  Type  Description 

time  FlexibleDateTime 
The date and time of the desired equator. 
RotationMatrix
Rotation_ECL_HOR(time, observer) ⇒ Kind: global function
Returns: RotationMatrix
 A rotation matrix that converts ECL to HOR at time
and for observer
.
The components of the horizontal vector are:
x = north, y = west, z = zenith (straight up from the observer).
These components are chosen so that the "righthand rule" works for the vector
and so that north represents the direction where azimuth = 0.
Brief: Calculates a rotation matrix from ecliptic J2000 (ECL) to horizontal (HOR).
This is one of the family of functions that returns a rotation matrix for converting from one orientation to another. Source: ECL = ecliptic system, using equator at J2000 epoch. Target: HOR = horizontal system.
Use HorizonFromVector to convert the return value to a traditional altitude/azimuth pair.
Param  Type  Description 

time  FlexibleDateTime 
The date and time of the desired horizontal orientation. 
observer  Observer 
A location near the Earth's mean sea level that defines the observer's horizon. 
RotationMatrix
Rotation_HOR_ECL(time, observer) ⇒ Kind: global function
Returns: RotationMatrix
 A rotation matrix that converts HOR to ECL.
Brief: Calculates a rotation matrix from horizontal (HOR) to ecliptic J2000 (ECL).
This is one of the family of functions that returns a rotation matrix for converting from one orientation to another. Source: HOR = horizontal system. Target: ECL = ecliptic system, using equator at J2000 epoch.
Param  Type  Description 

time  FlexibleDateTime 
The date and time of the horizontal observation. 
observer  Observer 
The location of the horizontal observer. 
RotationMatrix
Rotation_EQJ_GAL() ⇒ Kind: global function
Returns: RotationMatrix
 A rotation matrix that converts EQJ to GAL.
Brief: Calculates a rotation matrix from equatorial J2000 (EQJ) to galactic (GAL).
This is one of the family of functions that returns a rotation matrix for converting from one orientation to another. Source: EQJ = equatorial system, using the equator at the J2000 epoch. Target: GAL = galactic system (IAU 1958 definition).
RotationMatrix
Rotation_GAL_EQJ() ⇒ Kind: global function
Returns: RotationMatrix
 A rotation matrix that converts GAL to EQJ.
Brief: Calculates a rotation matrix from galactic (GAL) to equatorial J2000 (EQJ).
This is one of the family of functions that returns a rotation matrix for converting from one orientation to another. Source: GAL = galactic system (IAU 1958 definition). Target: EQJ = equatorial system, using the equator at the J2000 epoch.
ConstellationInfo
Constellation(ra, dec) ⇒ Kind: global function
Returns: ConstellationInfo
 An object that contains the 3letter abbreviation and full name
of the constellation that contains the given (ra,dec), along with
the converted B1875 (ra,dec) for that point.
Brief: Determines the constellation that contains the given point in the sky.
Given J2000 equatorial (EQJ) coordinates of a point in the sky, determines the constellation that contains that point.
Param  Type  Description 

ra  number 
The right ascension (RA) of a point in the sky, using the J2000 equatorial system. 
dec  number 
The declination (DEC) of a point in the sky, using the J2000 equatorial system. 
LunarEclipseInfo
SearchLunarEclipse(date) ⇒ Kind: global function
Brief: Searches for a lunar eclipse.
This function finds the first lunar eclipse that occurs after startTime
.
A lunar eclipse may be penumbral, partial, or total.
See LunarEclipseInfo for more information.
To find a series of lunar eclipses, call this function once,
then keep calling NextLunarEclipse as many times as desired,
passing in the peak
value returned from the previous call.
Param  Type  Description 

date  FlexibleDateTime 
The date and time for starting the search for a lunar eclipse. 
LunarEclipseInfo
NextLunarEclipse(prevEclipseTime) ⇒ Kind: global function
Brief: Searches for the next lunar eclipse in a series.
After using SearchLunarEclipse to find the first lunar eclipse
in a series, you can call this function to find the next consecutive lunar eclipse.
Pass in the peak
value from the LunarEclipseInfo returned by the
previous call to SearchLunarEclipse
or NextLunarEclipse
to find the next lunar eclipse.
Param  Type  Description 

prevEclipseTime  FlexibleDateTime 
A date and time near a full moon. Lunar eclipse search will start at the next full moon. 
GlobalSolarEclipseInfo
SearchGlobalSolarEclipse(startTime) ⇒ Kind: global function
Brief: Searches for a solar eclipse visible anywhere on the Earth's surface.
This function finds the first solar eclipse that occurs after startTime
.
A solar eclipse may be partial, annular, or total.
See GlobalSolarEclipseInfo for more information.
To find a series of solar eclipses, call this function once,
then keep calling NextGlobalSolarEclipse as many times as desired,
passing in the peak
value returned from the previous call.
Param  Type  Description 

startTime  FlexibleDateTime 
The date and time for starting the search for a solar eclipse. 
GlobalSolarEclipseInfo
NextGlobalSolarEclipse(prevEclipseTime) ⇒ Kind: global function
Brief: Searches for the next global solar eclipse in a series.
After using SearchGlobalSolarEclipse to find the first solar eclipse
in a series, you can call this function to find the next consecutive solar eclipse.
Pass in the peak
value from the GlobalSolarEclipseInfo returned by the
previous call to SearchGlobalSolarEclipse
or NextGlobalSolarEclipse
to find the next solar eclipse.
Param  Type  Description 

prevEclipseTime  FlexibleDateTime 
A date and time near a new moon. Solar eclipse search will start at the next new moon. 
LocalSolarEclipseInfo
SearchLocalSolarEclipse(startTime, observer) ⇒ Kind: global function
Brief: Searches for a solar eclipse visible at a specific location on the Earth's surface.
This function finds the first solar eclipse that occurs after startTime
.
A solar eclipse may be partial, annular, or total.
See LocalSolarEclipseInfo for more information.
To find a series of solar eclipses, call this function once,
then keep calling NextLocalSolarEclipse as many times as desired,
passing in the peak
value returned from the previous call.
IMPORTANT: An eclipse reported by this function might be partly or completely invisible to the observer due to the time of day. See LocalSolarEclipseInfo for more information about this topic.
Param  Type  Description 

startTime  FlexibleDateTime 
The date and time for starting the search for a solar eclipse. 
observer  Observer 
The geographic location of the observer. 
LocalSolarEclipseInfo
NextLocalSolarEclipse(prevEclipseTime, observer) ⇒ Kind: global function
Brief: Searches for the next local solar eclipse in a series.
After using SearchLocalSolarEclipse to find the first solar eclipse
in a series, you can call this function to find the next consecutive solar eclipse.
Pass in the peak
value from the LocalSolarEclipseInfo returned by the
previous call to SearchLocalSolarEclipse
or NextLocalSolarEclipse
to find the next solar eclipse.
This function finds the first solar eclipse that occurs after startTime
.
A solar eclipse may be partial, annular, or total.
See LocalSolarEclipseInfo for more information.
Param  Type  Description 

prevEclipseTime  FlexibleDateTime 
The date and time for starting the search for a solar eclipse. 
observer  Observer 
The geographic location of the observer. 
TransitInfo
SearchTransit(body, startTime) ⇒ Kind: global function
Brief: Searches for the first transit of Mercury or Venus after a given date.
Finds the first transit of Mercury or Venus after a specified date.
A transit is when an inferior planet passes between the Sun and the Earth
so that the silhouette of the planet is visible against the Sun in the background.
To continue the search, pass the finish
time in the returned structure to
NextTransit.
Param  Type  Description 

body  Body 
The planet whose transit is to be found. Must be Body.Mercury or Body.Venus . 
startTime  FlexibleDateTime 
The date and time for starting the search for a transit. 
TransitInfo
NextTransit(body, prevTransitTime) ⇒ Kind: global function
Brief: Searches for the next transit of Mercury or Venus in a series.
After calling SearchTransit to find a transit of Mercury or Venus, this function finds the next transit after that. Keep calling this function as many times as you want to keep finding more transits.
Param  Type  Description 

body  Body 
The planet whose transit is to be found. Must be Body.Mercury or Body.Venus . 
prevTransitTime  FlexibleDateTime 
A date and time near the previous transit. 
AxisInfo
RotationAxis(body, date) ⇒ Kind: global function
Brief: Calculates information about a body's rotation axis at a given time.
Calculates the orientation of a body's rotation axis, along with
the rotation angle of its prime meridian, at a given moment in time.
This function uses formulas standardized by the IAU Working Group on Cartographics and Rotational Elements 2015 report, as described in the following document:
https://astropedia.astrogeology.usgs.gov/download/Docs/WGCCRE/WGCCRE2015reprint.pdf
See AxisInfo for more detailed information.
Param  Type  Description 

body  Body 
One of the following values: Body.Sun , Body.Moon , Body.Mercury , Body.Venus , Body.Earth , Body.Mars , Body.Jupiter , Body.Saturn , Body.Uranus , Body.Neptune , Body.Pluto . 
date  FlexibleDateTime 
The time at which to calculate the body's rotation axis. 
Date
 number
 AstroTime
FlexibleDateTime : Kind: global typedef
Brief: A Date
, number
, or AstroTime
value that specifies the date and time of an astronomical event.
FlexibleDateTime
is a placeholder type that represents three different types
that may be passed to many Astronomy Engine functions: a JavaScript Date
object,
a number representing the realvalued number of UT days since the J2000 epoch,
or an AstroTime object.
This flexibility is for convenience of outside callers.
Internally, Astronomy Engine always converts a FlexibleDateTime
parameter
to an AstroTime
object by calling MakeTime.
object
SearchOptions : Kind: global typedef
Brief: Options for the Search function.
Properties
Name  Type  Description 

dt_tolerance_seconds 
number  undefined

The number of seconds for a time window smaller than which the search is considered successful. Using too large a tolerance can result in an inaccurate time estimate. Using too small a tolerance can cause excessive computation, or can even cause the search to fail because of limited floatingpoint resolution. Defaults to 1 second. 
init_f1 
number  undefined

As an optimization, if the caller of Search has already calculated the value of the function being searched (the parameter func ) at the time coordinate t1 , it can pass in that value as init_f1 . For very expensive calculations, this can measurably improve performance. 
init_f2 
number  undefined

The same as init_f1 , except this is the optional initial value of func(t2) instead of func(t1) . 
iter_limit 
number  undefined
