astronomy/source/c

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.

---

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

---

astro_time_t Astronomy_AddDays(astro_time_t time, double days);

---

astro_angle_result_t Astronomy_AngleFromSun(astro_body_t body, astro_time_t time);

---

astro_body_t Astronomy_BodyCode(const char *name);

---

const char* Astronomy_BodyName(astro_body_t body);

---

astro_time_t Astronomy_CurrentTime(void);

---

astro_ecliptic_t Astronomy_Ecliptic(astro_vector_t equ);

---

astro_angle_result_t Astronomy_EclipticLongitude(astro_body_t body, astro_time_t time);

---

astro_elongation_t Astronomy_Elongation(astro_body_t body, astro_time_t time);

---

astro_equatorial_t Astronomy_Equator(astro_body_t body, astro_time_t time, astro_observer_t observer, int ofdate, int aberration);

---

astro_vector_t Astronomy_GeoMoon(astro_time_t time);

---

astro_vector_t Astronomy_GeoVector(astro_body_t body, astro_time_t time, int correct_aberration);

---

astro_vector_t Astronomy_HelioVector(astro_body_t body, astro_time_t time);

---

astro_horizon_t Astronomy_Horizon(astro_time_t time, astro_observer_t observer, double ra, double dec, astro_refraction_t refraction);

---

astro_illum_t Astronomy_Illumination(astro_body_t body, astro_time_t time);

---

astro_angle_result_t Astronomy_LongitudeFromSun(astro_body_t body, astro_time_t time);

---

astro_observer_t Astronomy_MakeObserver(double latitude, double longitude, double height);

---

astro_time_t Astronomy_MakeTime(int year, int month, int day, int hour, int minute, double second);

---

astro_angle_result_t Astronomy_MoonPhase(astro_time_t time);

---

astro_apsis_t Astronomy_NextLunarApsis(astro_apsis_t apsis);

---

astro_moon_quarter_t Astronomy_NextMoonQuarter(astro_moon_quarter_t mq);

---

astro_search_result_t Astronomy_Search(astro_search_func_t func, void *context, astro_time_t t1, astro_time_t t2, double dt_tolerance_seconds);

---

astro_hour_angle_t Astronomy_SearchHourAngle(astro_body_t body, astro_observer_t observer, double hourAngle, astro_time_t dateStart);

---

astro_apsis_t Astronomy_SearchLunarApsis(astro_time_t startTime);

---

astro_elongation_t Astronomy_SearchMaxElongation(astro_body_t body, astro_time_t startDate);

---

astro_search_result_t Astronomy_SearchMoonPhase(double targetLon, astro_time_t dateStart, double limitDays);

---

astro_moon_quarter_t Astronomy_SearchMoonQuarter(astro_time_t dateStart);

---

astro_illum_t Astronomy_SearchPeakMagnitude(astro_body_t body, astro_time_t startDate);

---

astro_search_result_t Astronomy_SearchRelativeLongitude(astro_body_t body, double targetRelLon, astro_time_t startDate);

---

astro_search_result_t Astronomy_SearchRiseSet(astro_body_t body, astro_observer_t observer, int direction, astro_time_t dateStart, double limitDays);

---

astro_search_result_t Astronomy_SearchSunLongitude(double targetLon, astro_time_t dateStart, double limitDays);

---

astro_seasons_t Astronomy_Seasons(int calendar_year);

---

astro_ecliptic_t Astronomy_SunPosition(astro_time_t time);

---

astro_time_t Astronomy_TimeFromUtc(astro_utc_t utc);

---

astro_utc_t Astronomy_UtcFromTime(astro_time_t time);

---

double Astronomy_VectorLength(astro_vector_t vector);

Enumerated Types

---

---

---

---

---

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.

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.

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.

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

---