mirror/astronomy
1
0
Fork 0
mirror of https://github.com/cosinekitty/astronomy.git synced 2026-03-26 18:33:42 -04:00
Code Issues Packages Projects Releases Wiki Activity
Files
7eb88d30b3d52ceed4a5752f424ddb5d7cf46465
astronomy/source/c
History

README.md

Astronomy Engine (C/C++)

This is the complete programming reference for the C version of Astronomy Engine. It can be used directly from C++ programs also. Other programming languages are supported. See the home page for more info.

Quick Start

To get started quickly, here are some examples.

Contents

Topic Index

Position of Sun, Moon, and planets

Function Description
HelioVector Calculates vector with respect to the center of the Sun.
GeoVector Calculates 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.

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.
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.

Lunar perigee and apogee

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

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.

Functions

Astronomy_AddDays(time, days) ⇒ astro_time_t

Calculates the sum or difference of an astro_time_t with a specified floating point number of days.

Sometimes we need to adjust a given astro_time_t value by a certain amount of time. This function adds the given real number of days in days to the date and time in time.

More precisely, the result's Universal Time field ut is exactly adjusted by days and the Terrestrial Time field tt is adjusted correctly for the resulting UTC date and time, according to the historical and predictive Delta-T model provided by the United States Naval Observatory.

The value stored in time will not be modified; it is passed by value.

Returns: A date and time that is conceptually equal to time + days.

Type Parameter Description
astro_time_t time A date and time for which to calculate an adjusted date and time.
double days A floating point number of days by which to adjust time. May be negative, 0, or positive.

Astronomy_AngleFromSun(body, time) ⇒ astro_angle_result_t

Returns the angle between the given body and the Sun, as seen from the Earth.

This function calculates the angular separation between the given body and the Sun, as seen from the center of the Earth. This angle is helpful for determining how easy it is to see the body away from the glare of the Sun.

Returns: If successful, the returned structure contains ASTRO_SUCCESS in the status field and angle holds the angle in degrees between the Sun and the specified body as seen from the center of the Earth. If an error occurs, the status field contains a value other than ASTRO_SUCCESS that indicates the error condition.

Type Parameter Description
astro_body_t body The celestial body whose angle from the Sun is to be measured. Not allowed to be BODY_EARTH.
astro_time_t time The time at which the observation is made.

Astronomy_BodyCode(name) ⇒ astro_body_t

Returns the astro_body_t value corresponding to the given English name.

Returns: If name is one of the strings (case-sensitive) listed above, the returned value is the corresponding astro_body_t value, otherwise it is BODY_INVALID.

Type Parameter Description
const char * name One of the following strings: Sun, Moon, Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto.

Astronomy_BodyName(body) ⇒ const char *

Finds the name of a celestial body.

Returns: The English-language name of the celestial body, or "" if the body is not valid.

Type Parameter Description
astro_body_t body The celestial body whose name is to be found.

Astronomy_CurrentTime() ⇒ astro_time_t

Returns the computer's current date and time in the form of an astro_time_t.

Uses the computer's system clock to find the current UTC date and time with 1-second granularity. Converts that date and time to an astro_time_t value and returns the result. Callers can pass this value to other Astronomy Engine functions to calculate current observational conditions.

Astronomy_Ecliptic(equ) ⇒ astro_ecliptic_t

Converts J2000 equatorial Cartesian coordinates to J2000 ecliptic coordinates.

Given coordinates relative to the Earth's equator at J2000 (the instant of noon UTC on 1 January 2000), this function converts those coordinates to J2000 ecliptic coordinates, which are relative to the plane of the Earth's orbit around the Sun.

Returns: Ecliptic coordinates in the J2000 frame of reference.

Type Parameter Description
astro_vector_t equ Equatorial coordinates in the J2000 frame of reference. You can call Astronomy_GeoVector to obtain suitable equatorial coordinates.

Astronomy_EclipticLongitude(body, time) ⇒ astro_angle_result_t

Calculates heliocentric ecliptic longitude of a body based on the J2000 equinox.

This function calculates the angle around the plane of the Earth's orbit of a celestial body, as seen from the center of the Sun. The angle is measured prograde (in the direction of the Earth's orbit around the Sun) in degrees from the J2000 equinox. The ecliptic longitude is always in the range [0, 360).

Returns: On success, returns a structure whose status is ASTRO_SUCCESS and whose angle holds the ecliptic longitude in degrees. On failure, status holds a value other than ASTRO_SUCCESS.

Type Parameter Description
astro_body_t body A body other than the Sun.
astro_time_t time The date and time at which the body's ecliptic longitude is to be calculated.

Astronomy_Elongation(body, time) ⇒ astro_elongation_t

Determines visibility of a celestial body relative to the Sun, as seen from the Earth.

This function returns an astro_elongation_t structure, which provides the following information about the given celestial body at the given time:

  • visibility is an enumerated type that specifies whether the body is more easily seen in the morning before sunrise, or in the evening after sunset.
  • elongation is the angle in degrees between two vectors: one from the center of the Earth to the center of the Sun, the other from the center of the Earth to the center of the specified body. This angle indicates how far away the body is from the glare of the Sun. This elongation angle is always in the range [0, 180].
  • relative_longitude is 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, and ignores how far above or below that plane the body is. The relative longitude is measured in degrees and is always in the range [0, 180].

Returns: If successful, the status field in the returned structure contains ASTRO_SUCCESS and all the other fields in the structure are valid. On failure, status contains some other value as an error code and the other fields contain invalid values.

Type Parameter Description
astro_body_t body The celestial body whose visibility is to be calculated.
astro_time_t time The date and time of the observation.

Astronomy_Equator(body, time, observer, equdate, aberration) ⇒ astro_equatorial_t

Calculates equatorial coordinates of a celestial body as seen by an observer on the Earth's surface.

Calculates topocentric equatorial coordinates in one of two different systems: J2000 or true-equator-of-date, depending on the value of the equdate parameter. Equatorial coordinates include right ascension, declination, and distance in astronomical units.

This function corrects for light travel time: it adjusts the apparent location of the observed body based on how long it takes for light to travel from the body to the Earth.

This function corrects for topocentric parallax, meaning that it adjusts for the angular shift depending on where the observer is located on the Earth. This is most significant for the Moon, because it is so close to the Earth. However, parallax corection has a small effect on the apparent positions of other bodies.

Correction for aberration is optional, using the aberration parameter.

Type Parameter Description
astro_body_t body The celestial body to be observed. Not allowed to be BODY_EARTH.
astro_time_t time The date and time at which the observation takes place.
astro_observer_t observer A location on or near the surface of the Earth.
astro_equator_date_t equdate Selects the date of the Earth's equator in which to express the equatorial coordinates.
astro_aberration_t aberration Selects whether or not to correct for aberration.

Astronomy_GeoMoon(time) ⇒ astro_vector_t

Calculates the geocentric position of the Moon at a given time.

Given a time of observation, calculates the Moon's position as a vector. The vector gives the location of the Moon's center relative to the Earth's center with x-, y-, and z-components measured in astronomical units.

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

Returns: The Moon's position as a vector in J2000 Cartesian equatorial coordinates.

Type Parameter Description
astro_time_t time The date and time for which to calculate the Moon's position.

Astronomy_GeoVector(body, time, aberration) ⇒ astro_vector_t

Calculates geocentric Cartesian coordinates of a body in the J2000 equatorial system.

This function calculates the position of the given celestial body as a vector, using the center of the Earth as the origin. The result is expressed as a Cartesian vector in the J2000 equatorial system: the coordinates are based on the mean equator of the Earth at noon UTC on 1 January 2000.

If given an invalid value for body, or the body is BODY_PLUTO and the time is outside the year range 1700..2200, this function will fail. The caller should always check the status field inside the returned astro_vector_t for ASTRO_SUCCESS (success) or any other value (failure) before trusting the resulting vector.

Unlike Astronomy_HelioVector, this function always corrects for light travel time. This means the position of the body is "back-dated" by the amount of time it takes light to travel from that 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 due to transverse movement of the Earth with respect to the rays of light coming from that body.

Returns: A heliocentric position vector of the center of the given body.

Type Parameter Description
astro_body_t body A body for which to calculate a heliocentric position: the Sun, Moon, or any of the planets.
astro_time_t time The date and time for which to calculate the position.
astro_aberration_t aberration ABERRATION to correct for aberration, or NO_ABERRATION to leave uncorrected.

Astronomy_HelioVector(body, time) ⇒ astro_vector_t

Calculates heliocentric Cartesian coordinates of a body in the J2000 equatorial system.

This function calculates the position of the given celestial body as a vector, using the center of the Sun as the origin. The result is expressed as a Cartesian vector in the J2000 equatorial system: the coordinates are based on the mean equator of the Earth at noon UTC on 1 January 2000.

The position is not corrected for light travel time or aberration. This is different from the behavior of Astronomy_GeoVector.

If given an invalid value for body, or the body is BODY_PLUTO and the time is outside the year range 1700..2200, this function will fail. The caller should always check the status field inside the returned astro_vector_t for ASTRO_SUCCESS (success) or any other value (failure) before trusting the resulting vector.

Returns: A heliocentric position vector of the center of the given body.

Type Parameter Description
astro_body_t body A body for which to calculate a heliocentric position: the Sun, Moon, or any of the planets.
astro_time_t time The date and time for which to calculate the position.

Astronomy_Horizon(time, observer, ra, dec, refraction) ⇒ astro_horizon_t

Calculates the apparent location of a body relative to the local horizon of an observer on the Earth.

Given a date and time, the geographic location of an observer on the Earth, and equatorial coordinates (right ascension and declination) of a celestial body, this function returns horizontal coordinates (azimuth and altitude angles) for the body relative to the horizon at the geographic location.

The right ascension ra and declination dec passed in must be equator of date coordinates, based on the Earth's true equator at the date and time of the observation. Otherwise the resulting horizontal coordinates will be inaccurate. Equator of date coordinates can be obtained by calling Astronomy_Equator, passing in EQUATOR_OF_DATE as its equdate parameter. It is also recommended to enable aberration correction by passing in ABERRATION as the aberration parameter.

This function optionally corrects for atmospheric refraction. For most uses, it is recommended to pass REFRACTION_NORMAL in the refraction parameter to correct for optical lensing of the Earth's atmosphere that causes objects to appear somewhat higher above the horizon than they actually are. However, callers may choose to avoid this correction by passing in REFRACTION_NONE. If refraction correction is enabled, the azimuth, altitude, right ascension, and declination in the astro_horizon_t structure returned by this function will all be corrected for refraction. If refraction is disabled, none of these four coordinates will be corrected; in that case, the right ascension and declination in the returned structure will be numerically identical to the respective ra and dec values passed in.

Returns: The body's apparent horizontal coordinates and equatorial coordinates, both optionally corrected for refraction.

Type Parameter Description
astro_time_t time The date and time of the observation.
astro_observer_t observer The geographic location of the observer.
double ra The right ascension of the body in sidereal hours. See remarks above for more details.
double dec The declination of the body in degrees. See remarks above for more details.
astro_refraction_t refraction Selects whether to correct for atmospheric refraction, and if so, which model to use. The recommended value for most uses is REFRACTION_NORMAL. See remarks above for more details.

Astronomy_Illumination(body, time) ⇒ astro_illum_t

Astronomy_LongitudeFromSun(body, time) ⇒ astro_angle_result_t

Astronomy_MakeObserver(latitude, longitude, height) ⇒ astro_observer_t

Creates an observer object that represents a location on or near the surface of the Earth.

Some Astronomy Engine functions calculate values pertaining to an observer on the Earth. These functions require a value of type astro_observer_t that represents the location of such an observer.

Returns: An observer object that can be passed to astronomy functions that require a geographic location.

Type Parameter Description
double latitude The geographic latitude of the observer in degrees north (positive) or south (negative) of the equator.
double longitude The geographic longitude of the observer in degrees east (positive) or west (negative) of the prime meridian at Greenwich, England.
double height The height of the observer in meters above mean sea level.

Astronomy_MakeTime(year, month, day, hour, minute, second) ⇒ astro_time_t

Creates an astro_time_t value from a given calendar date and time.

Given a UTC calendar date and time, calculates an astro_time_t value that can be passed to other Astronomy Engine functions for performing various calculations relating to that date and time.

It is the caller's responsibility to ensure that the parameter values are correct. The parameters are not checked for validity, and this function never returns any indication of an error. Invalid values, for example passing in February 31, may cause unexpected return values.

Returns: An astro_time_t value that represents the given calendar date and time.

Type Parameter Description
int year The UTC calendar year, e.g. 2019.
int month The UTC calendar month in the range 1..12.
int day The UTC calendar day in the range 1..31.
int hour The UTC hour of the day in the range 0..23.
int minute The UTC minute in the range 0..59.
double second The UTC floating-point second in the range [0, 60).

Astronomy_MoonPhase(time) ⇒ astro_angle_result_t

Astronomy_NextLunarApsis(apsis) ⇒ astro_apsis_t

Astronomy_NextMoonQuarter(mq) ⇒ astro_moon_quarter_t

Astronomy_Search(func, context, t1, t2, dt_tolerance_seconds) ⇒ astro_search_result_t

Searches for a time at which a function's value increases through zero.

Certain astronomy calculations involve finding a time when an event occurs. Often such events can be defined as the root of a function: the time at which the function's value becomes zero.

Astronomy_Search finds the ascending root of a function: the time at which the function's value becomes zero while having a positive slope. That is, as time increases, the function transitions from a negative value, through zero at a specific moment, to a positive value later. The goal of the search is to find that specific moment.

The search function is specified by two parameters: func and context. The func parameter is a pointer to the function itself, which accepts a time and a context containing any other arguments needed to evaluate the function. The context parameter supplies that context for the given search. As an example, a caller may wish to find the moment a celestial body reaches a certain ecliptic longitude. In that case, the caller might create a structure that contains an astro_body_t member to specify the body and a double to hold the target longitude. The function would cast the pointer context passed in as a pointer to that structure type. It could subtract the target longitude from the actual longitude at a given time; thus the difference would equal zero at the moment in time the planet reaches the desired longitude.

The func returns an astro_func_result_t structure every time it is called. If the returned strcture has a value of status other than ASTRO_SUCCESS, the search immediately fails and reports that same error code in the status returned by Astronomy_Search. Otherwise, status is ASTRO_SUCCESS and value is the value of the function, and the search proceeds until it either finds the ascending root or fails for some reason.

The search calls func repeatedly to rapidly narrow in on any ascending root within the time window specified by t1 and t2. The search never reports a solution outside this time window.

Astronomy_Search uses a combination of bisection and quadratic interpolation to minimize the number of function calls. However, it is critical that the supplied time window be small enough that there cannot be more than one root (ascedning or descending) within it; otherwise the search can fail. Beyond that, it helps to make the time window as small as possible, ideally such that the function itself resembles a smooth parabolic curve within that window.

If an ascending root is not found, or more than one root (ascending and/or descending) exists within the window t1..t2, the search will fail with status code ASTRO_SEARCH_FAILURE.

If the search does not converge within 20 iterations, it will fail with status code ASTRO_NO_CONVERGE.

Returns: If successful, the returned structure has status equal to ASTRO_SUCCESS and time set to a value within dt_tolerance_seconds of an ascending root. On success, the time value will always be in the inclusive range [t1, t2]. If the search fails, status will be set to a value other than ASTRO_SUCCESS. See the remarks above for more details.

Type Parameter Description
astro_search_func_t func The function for which to find the time of an ascending root. See remarks above for more details.
void * context Any ancillary data needed by the function func to calculate a value. The data type varies depending on the function passed in. For example, the function may involve a specific celestial body that must be specified somehow.
astro_time_t t1 The lower time bound of the search window. See remarks above for more details.
astro_time_t t2 The upper time bound of the search window. See remarks above for more details.
double dt_tolerance_seconds Specifies an amount of time in seconds within which a bounded ascending root is considered accurate enough to stop. A typical value is 1 second.

Astronomy_SearchHourAngle(body, observer, hourAngle, dateStart) ⇒ astro_hour_angle_t

Astronomy_SearchLunarApsis(startTime) ⇒ astro_apsis_t

Astronomy_SearchMaxElongation(body, startDate) ⇒ astro_elongation_t

Astronomy_SearchMoonPhase(targetLon, dateStart, limitDays) ⇒ astro_search_result_t

Astronomy_SearchMoonQuarter(dateStart) ⇒ astro_moon_quarter_t

Astronomy_SearchPeakMagnitude(body, startDate) ⇒ astro_illum_t

Astronomy_SearchRelativeLongitude(body, targetRelLon, startDate) ⇒ astro_search_result_t

Astronomy_SearchRiseSet(body, observer, direction, dateStart, limitDays) ⇒ astro_search_result_t

Astronomy_SearchSunLongitude(targetLon, dateStart, limitDays) ⇒ astro_search_result_t

Astronomy_Seasons(year) ⇒ astro_seasons_t

Finds both equinoxes and both solstices for a given calendar year.

The changes of seasons are defined by solstices and equinoxes. Given a calendar year number, this function calculates the March and September equinoxes and the June and December solstices.

The equinoxes are the moments twice each year when the plane of the Earth's equator passes through the center of the Sun. In other words, the Sun's declination is zero at both equinoxes. The March equinox defines the beginning of spring in the northern hemisphere and the beginning of autumn in the southern hemisphere. The September equinox defines the beginning of autumn in the northern hemisphere and the beginning of spring in the southern hemisphere.

The solstices are the moments twice each year when one of the Earth's poles is most tilted toward the Sun. More precisely, the Sun's declination reaches its minimum value at the December solstice, which defines the beginning of winter in the northern hemisphere and the beginning of summer in the southern hemisphere. The Sun's declination reaches its maximum value at the June solstice, which defines the beginning of summer in the northern hemisphere and the beginning of winter in the southern hemisphere.

Returns: The times of the four seasonal changes in the given calendar year. This function should always succeed. However, to be safe, callers should check the status field of the returned structure to make sure it contains ASTRO_SUCCESS. Any failures indicate a bug in the algorithm and should be reported as an issue.

Type Parameter Description
int year The calendar year number for which to calculate equinoxes and solstices. The value may be any integer, but only the years 1800 through 2100 have been validated for accuracy: unit testing against data from the United States Naval Observatory confirms that all equinoxes and solstices for that range of years are within 2 minutes of the correct time.

Astronomy_SunPosition(time) ⇒ astro_ecliptic_t

Calculates geocentric ecliptic coordinates for the Sun.

This function calculates the position of the Sun as seen from the Earth. The returned value includes both Cartesian and spherical coordinates. The x-coordinate and longitude values in the returned structure are based on the true equinox of date: one of two points in the sky where the instantaneous plane of the Earth's equator at the given date and time (the equatorial plane) intersects with the plane of the Earth's orbit around the Sun (the ecliptic plane). By convention, the apparent location of the Sun at the March equinox is chosen as the longitude origin and x-axis direction, instead of the one for September.

Astronomy_SunPosition corrects for precession and nutation of the Earth's axis in order to obtain the exact equatorial plane at the given time.

This function can be used for calculating changes of seasons: equinoxes and solstices. In fact, the function Astronomy_Seasons does use this function for that purpose.

Returns: The ecliptic coordinates of the Sun using the Earth's true equator of date.

Type Parameter Description
astro_time_t time The date and time for which to calculate the Sun's position.

Astronomy_TimeFromUtc(utc) ⇒ astro_time_t

Creates an astro_time_t value from a given calendar date and time.

This function is similar to Astronomy_MakeTime, only it receives a UTC calendar date and time in the form of an astro_utc_t structure instead of as separate numeric parameters. Astronomy_TimeFromUtc is the inverse of Astronomy_UtcFromTime.

Returns: A value that can be used for astronomical calculations for the given date and time.

Type Parameter Description
astro_utc_t utc The UTC calendar date and time to be converted to astro_time_t.

Astronomy_UtcFromTime(time) ⇒ astro_utc_t

Determines the calendar year, month, day, and time from an astro_time_t value.

After calculating the date and time of an astronomical event in the form of an astro_time_t value, it is often useful to display the result in a human-readable form. This function converts the linear time scales in the ut field of astro_time_t into a calendar date and time: year, month, day, hours, minutes, and seconds, expressed in UTC.

Returns: A date and time broken out into conventional year, month, day, hour, minute, and second.

Type Parameter Description
astro_time_t time The astronomical time value to be converted to calendar date and time.

Astronomy_VectorLength(vector) ⇒ double

Calculates the length of the given vector.

Calculates the non-negative length of the given vector. The length is expressed in the same units as the vector's components, usually astronomical units (AU).

Returns: The length of the vector.

Type Parameter Description
astro_vector_t vector The vector whose length is to be calculated.

Enumerated Types

astro_aberration_t

Aberration calculation options.

Aberration is an effect causing the apparent direction of an observed body to be shifted due to transverse movement of the Earth with respect to the rays of light coming from that body. This angular correction can be anywhere from 0 to about 20 arcseconds, depending on the position of the observed body relative to the instantaneous velocity vector of the Earth.

Some Astronomy Engine functions allow optional correction for aberration by passing in a value of this enumerated type.

Aberration correction is useful to improve accuracy of coordinates of apparent locations of bodies seen from the Earth. However, because aberration affects not only the observed body (such as a planet) but the surrounding stars, aberration may be unhelpful (for example) for determining exactly when a planet crosses from one constellation to another.

Enum Value Description
ABERRATION Request correction for aberration.
NO_ABERRATION Do not correct for aberration.

astro_apsis_kind_t

The type of apsis: pericenter (closest approach) or apocenter (farthest distance).

Enum Value Description
APSIS_PERICENTER The body is at its closest approach to the object it orbits.
APSIS_APOCENTER The body is at its farthest distance from the object it orbits.
APSIS_INVALID Undefined or invalid apsis.

astro_body_t

A celestial body.

Enum Value Description
BODY_INVALID An invalid or undefined celestial body.
BODY_MERCURY Mercury
BODY_VENUS Venus
BODY_EARTH Earth
BODY_MARS Mars
BODY_JUPITER Jupiter
BODY_SATURN Saturn
BODY_URANUS Uranus
BODY_NEPTUNE Neptune
BODY_PLUTO Pluto
BODY_SUN Sun
BODY_MOON Moon

astro_direction_t

Selects whether to search for a rise time or a set time.

The Astronomy_SearchRiseSet function finds the rise or set time of a body depending on the value of its direction parameter.

Enum Value Description
DIRECTION_RISE Search for the time a body begins to rise above the horizon.
DIRECTION_SET Search for the time a body finishes sinking below the horizon.

astro_equator_date_t

Selects the date on which the Earth's equator to be used for representing equatorial coordinates.

The Earth's equator is not always in the same plane due to precession and nutation.

Sometimes it is useful to have a fixed plane of reference for equatorial coordinates across different calendar dates. In these cases, a fixed epoch, or reference time, is helpful. Astronomy Engine provides the J2000 epoch for such cases. This refers to the plane of the Earth's orbit as it was on noon UTC on 1 January 2000.

For some other purposes, it is more helpful to represent coordinates using the Earth's equator exactly as it is on that date. For example, when calculating rise/set times or horizontal coordinates, it is most accurate to use the orientation of the Earth's equator at that same date and time. For these uses, Astronomy Engine allows of-date calculations.

Enum Value Description
EQUATOR_J2000 Represent equatorial coordinates in the J2000 epoch.
EQUATOR_OF_DATE Represent equatorial coordinates using the Earth's equator at the given date and time.

astro_refraction_t

Selects whether to correct for atmospheric refraction, and if so, how.

Enum Value Description
REFRACTION_NONE No atmospheric refraction correction (airless).
REFRACTION_NORMAL Recommended correction for standard atmospheric refraction.
REFRACTION_JPLHOR Used only for compatibility testing with JPL Horizons online tool.

astro_status_t

Indicates success/failure of an Astronomy Engine function call.

Enum Value Description
ASTRO_SUCCESS The operation was successful.
ASTRO_NOT_INITIALIZED A placeholder that can be used for data that is not yet initialized.
ASTRO_INVALID_BODY The celestial body was not valid. Different sets of bodies are supported depending on the function.
ASTRO_NO_CONVERGE A numeric solver failed to converge. This should not happen unless there is a bug in Astronomy Engine.
ASTRO_BAD_TIME Cannot calculate Pluto's position outside the year range 1700..2200.
ASTRO_BAD_VECTOR Vector magnitude is too small to be normalized into a unit vector.
ASTRO_SEARCH_FAILURE Search was not able to find an ascending root crossing of the function in the specified time interval.
ASTRO_EARTH_NOT_ALLOWED The Earth cannot be treated as a celestial body seen from an observer on the Earth itself.
ASTRO_NO_MOON_QUARTER No lunar quarter occurs inside the specified time range.
ASTRO_WRONG_MOON_QUARTER Internal error: Astronomy_NextMoonQuarter found the wrong moon quarter.
ASTRO_INTERNAL_ERROR A self-check failed inside the code somewhere, indicating a bug needs to be fixed.
ASTRO_INVALID_PARAMETER A parameter value passed to a function was not valid.

astro_visibility_t

Indicates whether a body (especially Mercury or Venus) is best seen in the morning or evening.

Enum Value Description
VISIBLE_MORNING The body is best visible in the morning, before sunrise.
VISIBLE_EVENING The body is best visible in the evening, after sunset.

Structures

astro_angle_result_t

An angular value expressed in degrees.

Type Member Description
astro_status_t status ASTRO_SUCCESS if this struct is valid; otherwise an error code.
double angle An angle expressed in degrees.

astro_apsis_t

An apsis event: pericenter (closest approach) or apocenter (farthest distance).

For the Moon orbiting the Earth, or a planet orbiting the Sun, an apsis is an event where the orbiting body reaches its closest or farthest point from the primary body. The closest approach is called pericenter and the farthest point is apocenter.

More specific terminology is common for particular orbiting bodies. The Moon's closest approach to the Earth is called perigee and its furthest point is called apogee. The closest approach of a planet to the Sun is called perihelion and the furthest point is called aphelion.

This data structure is returned by Astronomy_SearchLunarApsis and Astronomy_NextLunarApsis to iterate through consecutive alternating perigees and apogees.

Type Member Description
astro_status_t status ASTRO_SUCCESS if this struct is valid; otherwise an error code.
astro_time_t time The date and time of the apsis.
astro_apsis_kind_t kind Whether this is a pericenter or apocenter event.
double dist_au The distance between the centers of the bodies in astronomical units.
double dist_km The distance between the centers of the bodies in kilometers.

astro_ecliptic_t

Ecliptic angular and Cartesian coordinates.

Coordinates of a celestial body as seen from the center of the Sun (heliocentric), oriented with respect to the plane of the Earth's orbit around the Sun (the ecliptic).

Type Member Description
astro_status_t status ASTRO_SUCCESS if this struct is valid; otherwise an error code.
double ex Cartesian x-coordinate: in the direction of the equinox along the ecliptic plane.
double ey Cartesian y-coordinate: in the ecliptic plane 90 degrees prograde from the equinox.
double ez Cartesian z-coordinate: perpendicular to the ecliptic plane. Positive is north.
double elat Latitude in degrees north (positive) or south (negative) of the ecliptic plane.
double elon Longitude in degrees around the ecliptic plane prograde from the equinox.

astro_elongation_t

Contains information about the visibility of a celestial body at a given date and time. See Astronomy_Elongation for more information.

Type Member Description
astro_status_t status ASTRO_SUCCESS if this struct is valid; otherwise an error code.
astro_time_t time The date and time of the observation.
astro_visibility_t visibility Whether the body is best seen in the morning or the evening.
double elongation The angle in degrees between the body and the Sun, as seen from the Earth.
double relative_longitude The difference between the ecliptic longitudes of the body and the Sun.

astro_equatorial_t

Equatorial angular coordinates.

Coordinates of a celestial body as seen from the Earth (geocentric or topocentric, depending on context), oriented with respect to the projection of the Earth's equator onto the sky.

Type Member Description
astro_status_t status ASTRO_SUCCESS if this struct is valid; otherwise an error code.
double ra right ascension in sidereal hours.
double dec declination in degrees
double dist distance to the celestial body in AU.

astro_func_result_t

A real value returned by a function whose ascending root is to be found.

When calling Astronomy_Search, the caller must pass in a callback function compatible with the function-pointer type astro_search_func_t whose ascending root is to be found. That callback function must return astro_func_result_t. If the function call is successful, it will set status to ASTRO_SUCCESS and value to the numeric value appropriate for the given date and time. If the call fails for some reason, it should set status to an appropriate error value other than ASTRO_SUCCESS; in the error case, to guard against any possible misuse of value, it is recommended to set value to NAN, though this is not strictly necessary.

Type Member Description
astro_status_t status ASTRO_SUCCESS if this struct is valid; otherwise an error code.
double value The value returned by a function whose ascending root is to be found.

astro_horizon_t

Coordinates of a celestial body as seen by a topocentric observer.

Contains horizontal and equatorial coordinates seen by an observer on or near the surface of the Earth (a topocentric observer). Optionally corrected for atmospheric refraction.

Type Member Description
double azimuth Compass direction around the horizon in degrees. 0=North, 90=East, 180=South, 270=West.
double altitude Angle in degrees above (positive) or below (negative) the observer's horizon.
double ra Right ascension in sidereal hours.
double dec Declination in degrees.

astro_hour_angle_t

Information about a celestial body crossing a specific hour angle.

Returned by the function Astronomy_SearchHourAngle to report information about a celestial body crossing a certain hour angle as seen by a specified topocentric observer.

Type Member Description
astro_status_t status ASTRO_SUCCESS if this struct is valid; otherwise an error code.
astro_time_t time The date and time when the body crosses the specified hour angle.
astro_horizon_t hor Apparent coordinates of the body at the time it crosses the specified hour angle.

astro_illum_t

Information about the brightness and illuminated shape of a celestial body.

Returned by the functions Astronomy_Illumination and Astronomy_SearchPeakMagnitude to report the visual magnitude and illuminated fraction of a celestial body at a given date and time.

Type Member Description
astro_status_t status ASTRO_SUCCESS if this struct is valid; otherwise an error code.
astro_time_t time The date and time of the observation.
double mag The visual magnitude of the body. Smaller values are brighter.
double phase_angle The angle in degrees between the Sun and the Earth, as seen from the body. Indicates the body's phase as seen from the Earth.
double helio_dist The distance between the Sun and the body at the observation time.
double ring_tilt For Saturn, the tilt angle in degrees of its rings as seen from Earth. For all other bodies, 0.

astro_moon_quarter_t

A lunar quarter event (new moon, first quarter, full moon, or third quarter) along with its date and time.

Type Member Description
astro_status_t status ASTRO_SUCCESS if this struct is valid; otherwise an error code.
int quarter 0=new moon, 1=first quarter, 2=full moon, 3=third quarter.
astro_time_t time The date and time of the lunar quarter.

astro_observer_t

The location of an observer on (or near) the surface of the Earth.

This structure is passed to functions that calculate phenomena as observed from a particular place on the Earth.

You can create this structure directly, or you can call the convenience function Astronomy_MakeObserver# to create one for you.

Type Member Description
double latitude Geographic latitude in degrees north (positive) or south (negative) of the equator.
double longitude Geographic longitude in degrees east (positive) or west (negative) of the prime meridian at Greenwich, England.
double height The height above (positive) or below (negative) sea level, expressed in meters.

astro_search_result_t

The result of a search for an astronomical event.

Type Member Description
astro_status_t status ASTRO_SUCCESS if this struct is valid; otherwise an error code.
astro_time_t time The time at which a searched-for event occurs.

astro_seasons_t

The dates and times of changes of season for a given calendar year. Call Astronomy_Seasons to calculate this data structure for a given year.

Type Member Description
astro_status_t status ASTRO_SUCCESS if this struct is valid; otherwise an error code.
astro_time_t mar_equinox The date and time of the March equinox for the specified year.
astro_time_t jun_solstice The date and time of the June soltice for the specified year.
astro_time_t sep_equinox The date and time of the September equinox for the specified year.
astro_time_t dec_solstice The date and time of the December solstice for the specified year.

astro_time_t

A date and time used for astronomical calculations.

This type is of fundamental importance to Astronomy Engine. It is used to represent dates and times for all astronomical calculations. It is also included in the values returned by many Astronomy Engine functions.

To create a valid astro_time_t value from scratch, call Astronomy_MakeTime (for a given calendar date and time) or Astronomy_CurrentTime (for the system's current date and time).

To adjust an existing astro_time_t by a certain real number of days, call Astronomy_AddDays.

The astro_time_t type contains ut to represent Universal Time (UT1/UTC) and tt to represent Terrestrial Time (TT, also known as ephemeris time). The difference tt-ut is known as ΔT, and is obtained from a model provided by the United States Naval Observatory.

Both tt and ut are necessary for performing different astronomical calculations. Indeed, certain calculations (such as rise/set times) require both time scales. See the documentation for the ut and tt fields for more detailed information.

In cases where astro_time_t is included in a structure returned by a function that can fail, the astro_status_t field status will contain a value other than ASTRO_SUCCESS; in that case the ut and tt will hold NAN (not a number). In general, when there is an error code stored in a struct field status, the caller should ignore all other values in that structure, including the ut and tt inside astro_time_t.

Type Member Description
double ut UT1/UTC number of days since noon on January 1, 2000. The floating point number of days of Universal Time since noon UTC January 1, 2000. Astronomy Engine approximates UTC and UT1 as being the same thing, although they are not exactly equivalent; UTC and UT1 can disagree by up to ±0.9 seconds. This approximation is sufficient for the accuracy requirements of Astronomy Engine. Universal Time Coordinate (UTC) is the international standard for legal and civil timekeeping and replaces the older Greenwich Mean Time (GMT) standard. UTC is kept in sync with unpredictable observed changes in the Earth's rotation by occasionally adding leap seconds as needed. UT1 is an idealized time scale based on observed rotation of the Earth, which gradually slows down in an unpredictable way over time, due to tidal drag by the Moon and Sun, large scale weather events like hurricanes, and internal seismic and convection effects. Conceptually, UT1 drifts from atomic time continuously and erratically, whereas UTC is adjusted by a scheduled whole number of leap seconds as needed. The value in ut is appropriate for any calculation involving the Earth's rotation, such as calculating rise/set times, culumination, and anything involving apparent sidereal time. Before the era of atomic timekeeping, days based on the Earth's rotation were often known as mean solar days.
double tt Terrestrial Time days since noon on January 1, 2000. Terrestrial Time is an atomic time scale defined as a number of days since noon on January 1, 2000. In this system, days are not based on Earth rotations, but instead by the number of elapsed SI seconds divided by 86400. Unlike ut, tt increases uniformly without adjustments for changes in the Earth's rotation. The value in tt is used for calculations of movements not involving the Earth's rotation, such as the orbits of planets around the Sun, or the Moon around the Earth. Historically, Terrestrial Time has also been known by the term Ephemeris Time (ET).

astro_utc_t

A calendar date and time expressed in UTC.

Type Member Description
int year The year value, e.g. 2019.
int month The month value: 1=January, 2=February, ..., 12=December.
int day The day of the month in the range 1..31.
int hour The hour of the day in the range 0..23.
int minute The minute of the hour in the range 0..59.
double second The floating point number of seconds in the range [0,60).

astro_vector_t

A 3D Cartesian vector whose components are expressed in Astronomical Units (AU).

Type Member Description
astro_status_t status ASTRO_SUCCESS if this struct is valid; otherwise an error code.
double x The Cartesian x-coordinate of the vector in AU.
double y The Cartesian y-coordinate of the vector in AU.
double z The Cartesian z-coordinate of the vector in AU.
astro_time_t t The date and time at which this vector is valid.

Type Definitions

astro_search_func_t

typedef astro_func_result_t(* astro_search_func_t) (void *context, astro_time_t time);

A pointer to a function that is to be passed as a callback to Astronomy_Search.

The function Astronomy_Search numerically solves for the time that a given event occurs. An event is defined as the time when an arbitrary function transitions between having a negative value and a non-negative value. This transition is called an ascending root.

The type astro_search_func_t represents such a callback function that accepts a custom context pointer and an astro_time_t representing the time to probe. The function returns an astro_func_result_t that contains either a real number in value or an error code in status that aborts the search.

The context points to some data whose type varies depending on the callback function. It can contain any auxiliary parameters (other than time) needed to evaluate the function. For example, a function may pertain to a specific celestial body, in which case context may point to a value of type astro_body_t. The context parameter is supplied by the caller of Astronomy_Search, which passes it along to every call to the callback function. If the caller of Astronomy_Search knows that the callback function does not need a context, it is safe to pass NULL as the context pointer.

Reference in New Issue View Git Blame Copy Permalink