astronomy/hydrogen/c_prefix.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
• Functions
• Enumerated Types
• Structures
• Type Definitions

---

Topic Index

Dates and times

Function	Description
CurrentTime	Obtains the current date and time of the computer's clock in the form of an astro_time_t that can be used for astronomy calculations.
MakeTime	Converts a UTC calendar date and time given as separate numeric parameters into an astro_time_t that can be used for astronomy calculations.
AddDays	Adds or subtracts an amount of time to an astro_time_t to get another astro_time_t.
TimeFromUtc	Converts UTC calendar date and time from an astro_utc_t structure to an astro_time_t structure that can be used for astronomy calculations.
UtcFromTime	Converts an astronomical astro_time_t time value to an astro_utc_t structure that can be used for displaying a UTC calendar date and time.

Celestial bodies

Function	Description
BodyCode	Converts the English name of a celestial body to its equivalent astro_body_t enumeration value.
BodyName	Converts an astro_body_t enumeration value to its equivalent English name as a string.

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	Converts J2000 equatorial coordinates to J2000 ecliptic coordinates.
EclipticLongitude	Calculates ecliptic longitude of a body in the J2000 system.
Horizon	Calculates horizontal coordinates (azimuth, altitude) for a given observer on the Earth.
LongitudeFromSun	Calculates a body's apparent ecliptic longitude difference from the Sun, as seen by an 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.
SearchMoonPhase	Finds the next instance of the Moon reaching a specific ecliptic longitude separation from the Sun.
SearchMoonQuarter	Finds the first quarter moon phase after a given date and time.
NextMoonQuarter	Finds 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, finds 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	Finds oppositions and conjunctions of planets.

Equinoxes, solstices, and apparent solar motion

Function	Description
SearchSunLongitude	Finds the next time the Sun reaches a specified apparent ecliptic longitude in the true equator of date system.
Seasons	Finds the equinoxes and solstices for a given calendar year.
SunPosition	Calculates the Sun's apparent ecliptic coordinates as seen from the Earth.

Coordinate transforms

The following four orientation systems are supported. Astronomy Engine can convert a vector from any of these orientations to any of the others. It also allows converting from a vector to spherical (angular) coordinates and back, within a given orientation. Note the 3-letter codes for each of the orientation systems; these are used in function and type names.

• EQJ = Equatorial J2000: Uses the Earth's equator on January 1, 2000, at noon UTC.
• EQD = Equator of-date: Uses the Earth's equator on a given date and time, adjusted for precession and nutation.
• ECL = Ecliptic: Uses the mean plane of the Earth's orbit around the Sun. The x-axis is referenced against the J2000 equinox.
• HOR = Horizontal: Uses the viewpoint of an observer at a specific location on the Earth at a given date and time.

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.
VectorFromSphere	Converts spherical coordinates to Cartesian coordinates.
SphereFromVector	Converts Cartesian coordinates to spherical coordinates.
VectorFromEquator	Given angular equatorial coordinates, calculates equatorial vector.
EquatorFromVector	Given an equatorial vector, calculates equatorial angular coordinates.
VectorFromHorizon	Given apparent angular horizontal coordinates, calculates horizontal vector.
HorizonFromVector	Given a vector in horizontal orientation, calculates horizontal angular coordinates.
Rotation_EQD_EQJ	Calculates a rotation matrix from equatorial of-date (EQD) to equatorial J2000 (EQJ).
Rotation_EQD_ECL	Calculates a rotation matrix from equatorial of-date (EQD) to ecliptic J2000 (ECL).
Rotation_EQD_HOR	Calculates a rotation matrix from equatorial of-date (EQD) to horizontal (HOR).
Rotation_EQJ_EQD	Calculates a rotation matrix from equatorial J2000 (EQJ) to equatorial of-date (EQD).
Rotation_EQJ_ECL	Calculates a rotation matrix from equatorial J2000 (EQJ) to ecliptic J2000 (ECL).
Rotation_EQJ_HOR	Calculates a rotation matrix from equatorial J2000 (EQJ) to horizontal (HOR).
Rotation_ECL_EQD	Calculates a rotation matrix from ecliptic J2000 (ECL) to equatorial of-date (EQD).
Rotation_ECL_EQJ	Calculates a rotation matrix from ecliptic J2000 (ECL) to equatorial J2000 (EQJ).
Rotation_ECL_HOR	Calculates a rotation matrix from ecliptic J2000 (ECL) to horizontal (HOR).
Rotation_HOR_EQD	Calculates a rotation matrix from horizontal (HOR) to equatorial of-date (EQD).
Rotation_HOR_EQJ	Calculates a rotation matrix from horizontal (HOR) to J2000 equatorial (EQJ).
Rotation_HOR_ECL	Calculates a rotation matrix from horizontal (HOR) to ecliptic J2000 (ECL).

---