Astronomy calculation for Sun, Moon, and planets.
npm install astronomy-engine
This is the complete programming reference for the JavaScript version
of Astronomy Engine. It supports client side programming
in the browser, and backend use of Node.js.
Astronomy Engine is available as an npm package.
Both the browser and backend versions of the JavaScript code are generated from
TypeScript code in astronomy.ts,
which is also provided here for those who want to use it directly.
Other programming languages are supported also.
See the home page for more info.
---
astronomy.tsFor convenience, this directory also contains human-readable JavaScript files astronomy.js
and minified versions for the browser (astronomy.browser.min.js) and Node.js (astronomy.min.js).
These JavaScript sources are all compiled from the TypeScript source astronomy.ts.
To get started quickly, here are some browser scripting examples
and some Node.js examples.
---
| 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 | Converts J2000 mean equator (EQJ) coordinates to true ecliptic of date (ECT) coordinates. |
| EclipticLongitude | Calculates true ecliptic of date (ECT) longitude for a body. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| Function | Description |
| -------- | ----------- |
| SearchLunarApsis | Finds the next perigee or apogee of the Moon after a specified date. |
| NextLunarApsis | Given an already-found apsis, find the next perigee or apogee of the Moon. |
| Function | Description |
| -------- | ----------- |
| SearchPlanetApsis | Finds the next perihelion or aphelion of a planet after a specified date. |
| NextPlanetApsis | Given an already-found apsis, find the next perihelion or aphelion of a planet. |
| 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. |
| Function | Description |
| -------- | ----------- |
| SearchRelativeLongitude | Find oppositions and conjunctions of planets. |
| Function | Description |
| -------- | ----------- |
| Seasons | Finds the equinoxes and solstices for a given calendar year. |
| SunPosition | Calculates the Sun's apparent true ecliptic of date (ECT) coordinates as seen from the Earth. |
The following orientation systems are supported.
Astronomy Engine can convert a vector from any of these orientations to any of the others.
It also allows converting from a vector to spherical (angular) coordinates and back,
within a given orientation. Note the 3-letter codes for each of the orientation systems;
these are used in function and type names.
- EQJ = J2000 Mean Equator: Uses the Earth's mean equator (corrected for precession but ignoring nutation) on January 1, 2000, at noon UTC. This moment in time is called J2000.
- EQD = True Equator of Date: Uses the Earth's equator on a given date and time, adjusted for precession and nutation.
- ECL = J2000 Mean Ecliptic: Uses the plane of the Earth's orbit around the Sun at J2000. The x-axis is referenced against the J2000 mean equinox.
- ECT = True Ecliptic of Date: Uses the true (corrected for precession and nutation) orbital plane of the Earth on the given date. The x-axis is referenced against the true equinox for that date.
- HOR = Horizontal: Uses the viewpoint of an observer at a specific location on the Earth at a given date and time.
- GAL = Galactic: Based on the IAU 1958 definition of galactic coordinates.
| 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 true equator of date (EQD) to J2000 mean equator (EQJ). |
| Rotation_EQD_ECT | Calculates a rotation matrix from true equator of date (EQD) to true ecliptic of date (ECT). |
| Rotation_EQD_ECL | Calculates a rotation matrix from true equator of date (EQD) to J2000 mean ecliptic (ECL). |
| Rotation_EQD_HOR | Calculates a rotation matrix from true equator of date (EQD) to horizontal (HOR). |
| Rotation_EQJ_EQD | Calculates a rotation matrix from J2000 mean equator (EQJ) to true equator of date (EQD). |
| Rotation_EQJ_ECT | Calculates a rotation matrix from J2000 mean equator (EQJ) to true ecliptic of date (ECT). |
| Rotation_EQJ_ECL | Calculates a rotation matrix from J2000 mean equator (EQJ) to J2000 mean ecliptic (ECL). |
| Rotation_EQJ_HOR | Calculates a rotation matrix from J2000 mean equator (EQJ) to horizontal (HOR). |
| Rotation_ECT_EQD | Calculates a rotation matrix from true ecliptic of date (ECT) to true equator of date (EQD). |
| Rotation_ECT_EQJ | Calculates a rotation matrix from true ecliptic of date (ECT) J2000 mean equator (EQJ). |
| Rotation_ECL_EQD | Calculates a rotation matrix from J2000 mean ecliptic (ECL) to true equator of date (EQD). |
| Rotation_ECL_EQJ | Calculates a rotation matrix from J2000 mean ecliptic (ECL) to J2000 mean equator (EQJ). |
| Rotation_ECL_HOR | Calculates a rotation matrix from J2000 mean ecliptic (ECL) to horizontal (HOR). |
| Rotation_HOR_EQD | Calculates a rotation matrix from horizontal (HOR) to true equator of date (EQD). |
| Rotation_HOR_EQJ | Calculates a rotation matrix from horizontal (HOR) to J2000 mean equator (EQJ). |
| Rotation_HOR_ECL | Calculates a rotation matrix from horizontal (HOR) to J2000 mean ecliptic (ECL). |
| Rotation_EQJ_GAL | Calculates a rotation matrix from J2000 mean equator (EQJ) to galactic (GAL). |
| Rotation_GAL_EQJ | Calculates a rotation matrix from galactic (GAL) to J2000 mean equator (EQJ). |
Astronomy Engine provides a GravitySimulator class
that allows you to model the trajectories of one or more small bodies like asteroids,
comets, or coasting spacecraft. If you know an initial position vector
and velocity vector for a small body, the gravity simulator can incrementally
simulate the pull of gravity on it from the Sun and planets, to calculate its
movement through the Solar System.
---
Objects of type AstroTime are used throughout the internals
of the Astronomy library, and are included in certain return objects.
Use the constructor or the MakeTime function to create an AstroTime object.
Properties
| Name | Type | Description |
| --- | --- | --- |
| date | Date | The JavaScript Date object for the given date and time. This Date corresponds to the numeric day value stored in the ut property. |
| ut | number | Universal Time (UT1/UTC) in fractional days since the J2000 epoch. Universal Time represents time measured with respect to the Earth's rotation, tracking mean solar days. The Astronomy library approximates UT1 and UTC as being the same thing. This gives sufficient accuracy for the precision requirements of this project. |
| tt | number | Terrestrial Time in fractional days since the J2000 epoch. TT represents a continuously flowing ephemeris timescale independent of any variations of the Earth's rotation, and is adjusted from UT using a best-fit piecewise polynomial model devised by Espenak and Meeus. |
*
| Param | Type | Description |
| --- | --- | --- |
| date | FlexibleDateTime | A JavaScript Date object, a numeric UTC value expressed in J2000 days, or another AstroTime object. |
*
AstroTime object as an ISO 86012018-08-17T17:22:04.050ZKind: instance method of AstroTime
*
AstroTime object adjusted by the floating point number of days.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 - An AstroTime object for the specified terrestrial time. 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. |
*
| Name | Type | Description |
| --- | --- | --- |
| elat | number | Sub-Earth libration ecliptic latitude angle, in degrees. |
| elon | number | Sub-Earth libration ecliptic longitude angle, in degrees. |
| mlat | number | Moon's geocentric ecliptic latitude, in degrees. |
| mlon | number | Moon's geocentric ecliptic longitude, in degrees. |
| 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. |
*
Holds the Cartesian coordinates of a vector in 3D space,
along with the time at which the vector is valid.
Properties
| Name | Type | Description |
| --- | --- | --- |
| x | number | The x-coordinate expressed in astronomical units (AU). |
| y | number | The y-coordinate expressed in astronomical units (AU). |
| z | number | The z-coordinate expressed in astronomical units (AU). |
| t | AstroTime | The time at which the vector is valid. |
*
Kind: instance method of Vector
*
Holds the state vector of a body at a given time, including its position,
velocity, and the time they are valid.
Properties
| Name | Type | Description |
| --- | --- | --- |
| x | number | The position x-coordinate expressed in astronomical units (AU). |
| y | number | The position y-coordinate expressed in astronomical units (AU). |
| z | number | The position z-coordinate expressed in astronomical units (AU). |
| vx | number | The velocity x-coordinate expressed in AU/day. |
| vy | number | The velocity y-coordinate expressed in AU/day. |
| vz | number | The velocity z-coordinate expressed in AU/day. |
| t | AstroTime | The time at which the vector is valid. |
*
Spherical 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. |
*
| 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. |
*
| 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]]. |
*
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. |
*
The origin and date of the coordinate system may vary depending on the caller's usage.
In general, ecliptic coordinates are measured with respect to the mean plane of the Earth's
orbit around the Sun.
Includes Cartesian coordinates (ex, ey, ez) measured in
astronomical units (AU)
and spherical coordinates (elon, elat) measured in degrees.
Properties
| Name | Type | Description |
| --- | --- | --- |
| vec | Vector | Ecliptic cartesian vector with components measured in astronomical units (AU). The x-axis is within the ecliptic plane and is oriented in the direction of the equinox. The y-axis is within the ecliptic plane and is oriented 90 degrees counterclockwise from the equinox, as seen from above the Sun's north pole. The z-axis is oriented perpendicular to the ecliptic plane, along the direction of the Sun's north pole. |
| elat | number | The ecliptic latitude of the body in degrees. This is the angle north or south of the ecliptic plane. The value is in the range [-90, +90]. Positive values are north and negative values are south. |
| elon | number | The ecliptic longitude of the body in degrees. This is the angle measured counterclockwise around the ecliptic plane, as seen from above the Sun's north pole. This is the same direction that the Earth orbits around the Sun. The angle is measured starting at 0 from the equinox and increases up to 360 degrees. |
*
| 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. |
*
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 |
| --- | --- | --- |
| io | StateVector | The position and velocity of Jupiter's moon Io. |
| europa | StateVector | The position and velocity of Jupiter's moon Europa. |
| ganymede | StateVector | The position and velocity of Jupiter's moon Ganymede. |
| callisto | StateVector | The position and velocity of Jupiter's moon Callisto. |
*
| Name | Type | Description |
| --- | --- | --- |
| time | AstroTime | The date and time pertaining to the other calculated values in this object. |
| mag | number | The apparent visual magnitude of the celestial body. |
| phase_angle | number | The angle in degrees as seen from the center of the celestial body between the Sun and the Earth. The value is always in the range 0 to 180. The phase angle provides a measure of what fraction of the body's face appears illuminated by the Sun as seen from the Earth. When the observed body is the Sun, the phase property is set to 0, although this has no physical meaning because the Sun emits, rather than reflects, light. When the phase is near 0 degrees, the body appears "full". When it is 90 degrees, the body appears "half full". And when it is 180 degrees, the body appears "new" and is very difficult to see because it is both dim and lost in the Sun's glare as seen from the Earth. |
| phase_fraction | number | The fraction of the body's face that is illuminated by the Sun, as seen from the Earth. Calculated from phase_angle for convenience. This value ranges from 0 to 1. |
| helio_dist | number | The distance between the center of the Sun and the center of the body in astronomical units (AU). |
| geo_dist | number | The distance between the center of the Earth and the center of the body in AU. |
| gc | Vector | Geocentric coordinates: the 3D vector from the center of the Earth to the center of the body. The components are in expressed in AU and are oriented with respect to the J2000 equatorial plane. |
| hc | Vector | Heliocentric coordinates: The 3D vector from the center of the Sun to the center of the body. Like gc, hc is expressed in AU and oriented with respect to the J2000 equatorial plane. |
| ring_tilt | number \| undefined | For Saturn, this is the angular tilt of the planet's rings in degrees away from the line of sight from the Earth. When the value is near 0, the rings appear edge-on from the Earth and are therefore difficult to see. When ring_tilt approaches its maximum value (about 27 degrees), the rings appear widest and brightest from the Earth. Unlike the JPL Horizons online tool, this library includes the effect of the ring tilt angle in the calculated value for Saturn's visual magnitude. For all bodies other than Saturn, the value of ring_tilt is undefined. |
*
| 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. |
*
| Name | Type | Description |
| --- | --- | --- |
| pressure | number | Atmospheric pressure in pascals. |
| temperature | number | Atmospheric temperature in kelvins. |
| density | number | Atmospheric density relative to sea level. |
*
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. |
*
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. |
*
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]. |
*
For a planet orbiting the Sun, apsis is a perihelion or aphelion, respectively.
For the Moon orbiting the Earth, apsis is a perigee or apogee, respectively.
See
- SearchLunarApsis
- NextLunarApsis
- SearchPlanetApsis
- NextPlanetApsis
Properties
| Name | Type | Description |
| --- | --- | --- |
| time | AstroTime | The date and time of the apsis. |
| kind | ApsisKind | For a closest approach (perigee or perihelion), kind is ApsisKind.Pericenter. For a farthest distance event (apogee or aphelion), kind is ApsisKind.Apocenter. |
| 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. |
*
| Name | Type | Description |
| --- | --- | --- |
| symbol | string | 3-character mnemonic symbol for the constellation, e.g. "Ori". |
| name | string | Full name of constellation, e.g. "Orion". |
| ra1875 | number | Right ascension expressed in B1875 coordinates. |
| dec1875 | number | Declination expressed in B1875 coordinates. |
*
Returned by SearchLunarEclipse or NextLunarEclipse
to report information about a lunar eclipse event.
When a lunar eclipse is found, it is classified as penumbral, partial, or total.
Penumbral eclipses are difficult to observe, because the Moon is only slightly dimmed
by the Earth's penumbra; no part of the Moon touches the Earth's umbra.
Partial eclipses occur when part, but not all, of the Moon touches the Earth's umbra.
Total eclipses occur when the entire Moon passes into the Earth's umbra.
The kind field thus holds one of the enum values EclipseKind.Penumbral, EclipseKind.Partial,
or EclipseKind.Total, depending on the kind of lunar eclipse found.
The obscuration field holds a value in the range [0, 1] that indicates what fraction
of the Moon's apparent disc area is covered by the Earth's umbra at the eclipse's peak.
This indicates how dark the peak eclipse appears. For penumbral eclipses, the obscuration
is 0, because the Moon does not pass through the Earth's umbra. For partial eclipses,
the obscuration is somewhere between 0 and 1. For total lunar eclipses, the obscuration is 1.
Field peak holds the date and time of the peak of the eclipse, when it is at its peak.
Fields sd_penum, sd_partial, and sd_total hold the semi-duration of each phase
of the eclipse, which is half of the amount of time the eclipse spends in each
phase (expressed in minutes), or 0 if the eclipse never reaches that phase.
By converting from minutes to days, and subtracting/adding with peak, the caller
may determine the date and time of the beginning/end of each eclipse phase.
Properties
| Name | Type | Description |
| --- | --- | --- |
| kind | EclipseKind | The type of lunar eclipse found. |
| obscuration | number | The peak fraction of the Moon's apparent disc that is covered by the Earth's umbra. |
| peak | AstroTime | The time of the eclipse at its peak. |
| sd_penum | number | The semi-duration of the penumbral phase in minutes. |
| sd_partial | number | The semi-duration of the penumbral phase in minutes, or 0.0 if none. |
| sd_total | number | The semi-duration of the penumbral phase in minutes, or 0.0 if none. |
*
Returned by SearchGlobalSolarEclipse or NextGlobalSolarEclipse
to report information about a solar eclipse event.
The eclipse is classified as partial, annular, or total, depending on the
maximum amount of the Sun's disc obscured, as seen at the peak location
on the surface of the Earth.
The kind field thus holds one of the values EclipseKind.Partial, EclipseKind.Annular, or EclipseKind.Total.
A total eclipse is when the peak observer sees the Sun completely blocked by the Moon.
An annular eclipse is like a total eclipse, but the Moon is too far from the Earth's surface
to completely block the Sun; instead, the Sun takes on a ring-shaped appearance.
A partial eclipse is when the Moon blocks part of the Sun's disc, but nobody on the Earth
observes either a total or annular eclipse.
If kind is EclipseKind.Total or EclipseKind.Annular, the latitude and longitude
fields give the geographic coordinates of the center of the Moon's shadow projected
onto the daytime side of the Earth at the instant of the eclipse's peak.
If kind has any other value, latitude and longitude are undefined and should
not be used.
For total or annular eclipses, the obscuration field holds the fraction (0, 1]
of the Sun's apparent disc area that is blocked from view by the Moon's silhouette,
as seen by an observer located at the geographic coordinates latitude, longitude
at the darkest time peak. The value will always be 1 for total eclipses, and less than
1 for annular eclipses.
For partial eclipses, obscuration is undefined and should not be used.
This is because there is little practical use for an obscuration value of
a partial eclipse without supplying a particular observation location.
Developers who wish to find an obscuration value for partial solar eclipses should therefore use
SearchLocalSolarEclipse and provide the geographic coordinates of an observer.
Properties
| Name | Type | Description |
| --- | --- | --- |
| kind | EclipseKind | One of the following enumeration values: EclipseKind.Partial, EclipseKind.Annular, EclipseKind.Total. |
| obscuration | number \| undefined | The peak fraction of the Sun's apparent disc area obscured by the Moon (total and annular eclipses only) |
| peak | AstroTime | The date and time when the solar eclipse is darkest. This is 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 EclipseKind.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 EclipseKind.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. |
*
When reporting a solar eclipse observed at a specific location on the Earth
(a "local" solar eclipse), a series of events occur. In addition
to the time of each event, it is important to know the altitude of the Sun,
because each event may be invisible to the observer if the Sun is below
the horizon.
If altitude is negative, the event is theoretical only; it would be
visible if the Earth were transparent, but the observer cannot actually see it.
If altitude is positive but less than a few degrees, visibility will be impaired by
atmospheric interference (sunrise or sunset conditions).
Properties
| 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. |
*
Returned by SearchLocalSolarEclipse or NextLocalSolarEclipse
to report information about a solar eclipse as seen at a given geographic location.
When a solar eclipse is found, it is classified by setting kind
to EclipseKind.Partial, EclipseKind.Annular, or EclipseKind.Total.
A partial solar eclipse is when the Moon does not line up directly enough with the Sun
to completely block the Sun's light from reaching the observer.
An annular eclipse occurs when the Moon's disc is completely visible against the Sun
but the Moon is too far away to completely block the Sun's light; this leaves the
Sun with a ring-like appearance.
A total eclipse occurs when the Moon is close enough to the Earth and aligned with the
Sun just right to completely block all sunlight from reaching the observer.
The obscuration field reports what fraction of the Sun's disc appears blocked
by the Moon when viewed by the observer at the peak eclipse time.
This is a value that ranges from 0 (no blockage) to 1 (total eclipse).
The obscuration value will be between 0 and 1 for partial eclipses and annular eclipses.
The value will be exactly 1 for total eclipses. Obscuration gives an indication
of how dark the eclipse appears.
There are 5 "event" fields, each of which contains a time and a solar altitude.
Field peak holds the date and time of the center of the eclipse, when it is at its peak.
The fields partial_begin and partial_end are always set, and indicate when
the eclipse begins/ends. If the eclipse reaches totality or becomes annular,total_begin and total_end indicate when the total/annular phase begins/ends.
When an event field is valid, the caller must also check its altitude field to
see whether the Sun is above the horizon at the time indicated by the time field.
See EclipseEvent for more information.
Properties
| Name | Type | Description |
| --- | --- | --- |
| kind | EclipseKind | The type of solar eclipse found: EclipseKind.Partial, EclipseKind.Annular, or EclipseKind.Total. |
| obscuration | number | The fraction of the Sun's apparent disc area obscured by the Moon at the eclipse peak. |
| 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. |
*
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. |
*
This object is returned by SearchMoonNode and NextMoonNode
to report information about the center of the Moon passing through the ecliptic plane.
Properties
| Name | Type | Description |
| --- | --- | --- |
| kind | NodeEventKind | Whether the node is ascending (south to north) or descending (north to south). |
| time | AstroTime | The time when the body passes through the ecliptic plane. |
*
This structure is returned by RotationAxis to report
the orientation of a body's rotation axis at a given moment in time.
The axis is specified by the direction in space that the body's north pole
points, using angular equatorial coordinates in the J2000 system (EQJ).
Thus ra is the right ascension, and dec is the declination, of the
body's north pole vector at the given moment in time. The north pole
of a body is defined as the pole that lies on the north side of the
Solar System's invariable plane,
regardless of the body's direction of rotation.
The spin field indicates the angular position of a prime meridian
arbitrarily recommended for the body by the International Astronomical
Union (IAU).
The fields ra, dec, and spin correspond to the variables
α0, δ0, and W, respectively, from
Report of the IAU Working Group on Cartographic Coordinates and Rotational Elements: 2015.
The field north is a unit vector pointing in the direction of the body's north pole.
It is expressed in the J2000 mean equator system (EQJ).
Properties
| 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. |
*
This class calculates the movement of arbitrary small bodies,
such as asteroids or comets, that move through the Solar System.
It does so by calculating the gravitational forces on the small bodies
from the Sun and planets. The user of this class supplies a
list of initial positions and velocities for the small bodies.
Then the class can update the positions and velocities over small
time steps.
*
| Param | Type | Description |
| --- | --- | --- |
| originBody | Body | Specifies the origin of the reference frame. All position vectors and velocity vectors will use originBody as the origin of the coordinate system. This origin applies to all the input vectors provided in the bodyStates parameter of this function, along with all output vectors returned by Update. Most callers will want to provide one of the following: Body.Sun for heliocentric coordinates, Body.SSB for solar system barycentric coordinates, or Body.Earth for geocentric coordinates. Note that the gravity simulator does not correct for light travel time; all state vectors are tied to a Newtonian "instantaneous" time. |
| date | FlexibleDateTime | The initial time at which to start the simulation. |
| bodyStates | Array.<StateVector> | An array of zero or more initial state vectors (positions and velocities) of the small bodies to be simulated. The caller must know the positions and velocities of the small bodies at an initial moment in time. Their positions and velocities are expressed with respect to originBody, using equatorial J2000 orientation (EQJ). Positions are expressed in astronomical units (AU). Velocities are expressed in AU/day. All the times embedded within the state vectors must exactly match date, or this constructor will throw an exception. |
*
GravitySimulator *
GravitySimulator *
Updates the simulation of the user-supplied small bodies
to the time indicated by the date parameter.
Returns an array of state vectors for the simulated bodies.
The array is in the same order as the original array that
was used to construct this simulator object.
The positions and velocities in the returned array are
referenced to the originBody that was used to construct
this simulator.
Kind: instance method of GravitySimulator
Returns: Array.<StateVector> - An array of state vectors, one for each simulated small body.
| Param | Type | Description |
| --- | --- | --- |
| date | FlexibleDateTime | A time that is a small increment away from the current simulation time. It is up to the developer to figure out an appropriate time increment. Depending on the trajectories, a smaller or larger increment may be needed for the desired accuracy. Some experimentation may be needed. Generally, bodies that stay in the outer Solar System and move slowly can use larger time steps. Bodies that pass into the inner Solar System and move faster will need a smaller time step to maintain accuracy. The date value may be after or before the current simulation time to move forward or backward in time. |
*
Sometimes it is helpful to "explore" various times near a given
simulation time step, while repeatedly returning to the original
time step. For example, when backdating a position for light travel
time, the caller may wish to repeatedly try different amounts of
backdating. When the backdating solver has converged, the caller
wants to leave the simulation in its original state.
This function allows a single "undo" of a simulation, and does so
very efficiently.
Usually this function will be called immediately after a matching
call to Update. It has the effect of rolling
back the most recent update. If called twice in a row, it reverts
the swap and thus has no net effect.
The constructor initializes the current state and previous
state to be identical. Both states represent the time parameter that was
passed into the constructor. Therefore, Swap will
have no effect from the caller's point of view when passed a simulator
that has not yet been updated by a call to Update.
Kind: instance method of GravitySimulator
*
In order to simulate the movement of small bodies through the Solar System,
the simulator needs to calculate the state vectors for the Sun and planets.
If an application wants to know the positions of one or more of the planets
in addition to the small bodies, this function provides a way to obtain
their state vectors. This is provided for the sake of efficiency, to avoid
redundant calculations.
The state vector is returned relative to the position and velocity
of the originBody parameter that was passed to this object's constructor.
Kind: instance method of GravitySimulator
| Param | Type | Description |
| --- | --- | --- |
| body | Body | The Sun, Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, or Neptune. |
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
enumThe 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, likeAstronomy.Body.Moon, Astronomy.Body.Jupiter, etc.
*
enumPericenter: The body is at its closest distance to the object it orbits.Apocenter: The body is at its farthest distance from the object it orbits.
*
enumPenumbral: A lunar eclipse in which only the Earth's penumbra falls on the Moon. (Never used for a solar eclipse.)Partial: A partial lunar/solar eclipse.Annular: A solar eclipse in which the entire Moon is visible against the Sun, but the Sun appears as a ring around the Moon. (Never used for a lunar eclipse.)Total: A total lunar/solar eclipse.
*
enumInvalid is a placeholder for an unknown or missing node.Ascending indicates a body passing through the ecliptic plane from south to north.Descending indicates a body passing through the ecliptic plane from north to south.
*
numbernumber - The angle between the two vectors expressed in degrees.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. |
*
numbernumber - An angle in degrees in the range [0, 180]. 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. |
*
AtmosphereInfoThis function calculates idealized values of pressure, temperature, and density
using the U.S. Standard Atmosphere (1976) model.
1. COESA, U.S. Standard Atmosphere, 1976, U.S. Government Printing Office, Washington, DC, 1976.
2. Jursa, A. S., Ed., Handbook of Geophysics and the Space Environment, Air Force Geophysics Laboratory, 1985.
See:
https://hbcp.chemnetbase.com/faces/documents/14_12/14_12_0001.xhtml
https://ntrs.nasa.gov/api/citations/19770009539/downloads/19770009539.pdf
https://www.ngdc.noaa.gov/stp/space-weather/online-publications/miscellaneous/us-standard-atmosphere-1976/us-standard-atmosphere_st76-1562_noaa.pdf
| Param | Type | Description |
| --- | --- | --- |
| elevationMeters | number | The elevation above sea level at which to calculate atmospheric variables. Must be in the range -500 to +100000, or an exception will occur. |
*
VectorVector - The position vector at the solved backdated time.t field holds the time that light left the observedWhen observing a distant object, for example Jupiter as seen from Earth,
the amount of time it takes for light to travel from the object to the
observer can significantly affect the object's apparent position.
This function solves the light travel time correction for the apparent
relative position vector of a target body as seen by an observer body
at a given observation time.
For geocentric calculations, GeoVector also includes light
travel time correction, but the time t embedded in its returned vector
refers to the observation time, not the backdated time that light left
the observed body. Thus BackdatePosition provides direct
access to the light departure time for callers that need it.
For a more generalized light travel correction solver, see CorrectLightTravel.
| Param | Type | Description |
| --- | --- | --- |
| date | FlexibleDateTime | The time of observation. |
| observerBody | Body | The body to be used as the observation location. |
| targetBody | Body | The body to be observed. |
| aberration | boolean | true to correct for aberration, or false to leave uncorrected. |
*
StateVectorStateVector - An object that contains barycentric position and velocity vectors. Given a body and a time, calculates the barycentric position and velocity
vectors for the center of that body at that time.
The vectors are expressed in J2000 mean equator coordinates (EQJ).
| 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. |
*
RotationMatrix