Module providing routines to convert among various sky coordinate systems.
Most of these routines are discussed in Sec. 5.1 of [15]; we reproduce here some of the essential elements of this discussion.
A general spatial coordinate system is shown in this figure. It is defined by six parameters: three positions specifying the location of the origin \(O\), two angles specifying the direction of the pole or \(z\)-axis, and one further angle specifying a reference meridian or \(x\)-axis orthogonal to the \(z\)-axis. A \(y\)-axis can also be defined such that \(x\), \(y\), and \(z\) form an orthogonal right-handed coordinate system; however, in astronomy it is more conventional to use spherical coordinates, defined as follows:
For any given point \(P\), define a plane (called its meridian) containing both the \(z\)-axis and the point in question. The longitude \(\lambda\) is the angle in the \(x\)- \(y\) plane from the \(x\)-axis to the line where the object's meridian crosses the \(x-y\) plane. The latitude \(\phi\) is the angle in the meridian plane between this line and the direction to the object. The distance \(r\) is simply measured in a straight line from the origin to the point. Longitude is defined to increase in the right-handed direction about the \(z\)-axis (i.e. the \(y\)-axis lies at positive \(\pi/2\) radians longitude), and is typically given in the range \([0,2\pi)\) radians. Latitude is defined to increase towards the \(z\)-axis (i.e. the \(z\)-axis lies at positive \(\pi/2\) radians latitude), and is typically given in the range \([-\pi/2,\pi/2]\) radians; a point with latitude \(\pm\pi/2\) radians has arbitrary (undefined) longitude. Distance should always be positive. This convention is shown in this figure.
In the routines in this module, we do not perform transformations between coordinate systems having different origins. By default, all coordinates are assumed to be centred on the observer; however, one may also consider coordinate systems that are geogentric (having their origin at the centre of the Earth), heliocentric (origin at the centre of the Sun), barycentric (origin at the centre of mass of the solar system), and Galactocentric (origin at the centre of our Galaxy). Since we ignore translations in the coordinate origin, distances remain unchanged, so these routines only consider transformations in latitude and longitude. To put it another way, these routines transform directions in space, not locations in space. These directions are generically stored in the SkyPosition
structure, defined below.
The coordinate systems that we consider are defined as follows:
The terms latitude'' and
longitude'' without qualification normally refer to geographic latitude and longitude. However, we emphasize once again that geographic latitude and longitude as defined above refer to directions in space, not to locations on the Earth's surface. This can lead to some confusion. The geodetic latitude and longitude of a point on the Earth's surface are the latitude and longitude of its vertical direction; this is the standard meaning used by cartographers, and relates directly to the horizon-based coordinate system above. However, one can also define a geocentric latitude and longitude for a point on the surface, which are the latitude and longitude of the direction from the geometric centre of the Earth through that point. These angles are not necessarily the same, due to the Earth's ellipticity, as shown in this figure in TerrestrialCoordinates.c.
Geographic coordinates are related to sky-fixed equatorial coordinates by specifying the counterclockwise angle to the prime meridian from the reference meridian \(\Upsilon\) of the sky-fixed coordinates, as defined below. This angle is called the Greenwich Mean Sidereal Time (GMST), and is often specified in hours, minutes, and seconds.
The equatorial and ecliptic coordinate systems are related by a single angle \(\epsilon\), called the obliquity of the ecliptic (that is, the inclination of the Earth's rotation axis relative to its orbital axis). Ecliptic latitude is normally denoted as \(\beta\) and ecliptic longitude as \(\lambda\).
The definition of the Galactic coordinate system is completely unrelated to any of the the other coordinate systems; thus, the relationship between Galactic and equatorial coodinates requires one to specify three arbitrary (but constant) angles. Two of these are the right ascension \(\alpha_\mathrm{NGP}\) and declination \(\delta_\mathrm{NPG}\) of the North Galactic Pole ( \(z\)-axis) in the equatorial coordinate system, the third is the Galactic longitude \(l_\mathrm{ascend}\) of the point where the Galactic plane ascends through the equatorial plane; i.e. the \(l\) value for the direction along the intersection of the Galactic and equatorial planes, such that right-handed rotation about the Galactic \(z\)-axis moves you from south to north through the equator.
Modules | |
Module CelestialCoordinates.c | |
Converts among Galactic, ecliptic, and equatorial coordinates. | |
Module TerrestrialCoordinates.c | |
Converts among equatorial, geographic, and horizon coordinates. | |
Module SkyCoordinates.c | |
Automatically converts among sky coordinate systems. | |
Data Structures | |
struct | SkyPosition |
This structure stores the two spherical coordinates of a sky position; ie a generic latitude and longitude; the structure is not defined specific to a particular coordinate system, but maintains a tag indicating which coordinate system it is expressed in. More... | |
struct | EarthPosition |
This structure stores the location of a point on (or near) the surface of the Earth in both geodetic and geocentric coordinates, as described in TerrestrialCoordinates.c . More... | |
struct | ConvertSkyParams |
This structure stores parameters for the function LALConvertSkyPosition() . More... | |
Enumerations | |
enum | CoordinateSystem { COORDINATESYSTEM_HORIZON , COORDINATESYSTEM_GEOGRAPHIC , COORDINATESYSTEM_EQUATORIAL , COORDINATESYSTEM_ECLIPTIC , COORDINATESYSTEM_GALACTIC } |
This enumerated type is used to identify data as being in one of the coordinate systems discussed in Header SkyCoordinates.h. More... | |
Files | |
file | GeocentricGeodeticTest.c |
Tests geocentric to geodetic conversion. | |
file | SkyCoordinatesTest.c |
Transforms coordinates among various systems. | |
Error codes | |
#define | SKYCOORDINATESH_ENUL 1 |
Unexpected null pointer in arguments. More... | |
#define | SKYCOORDINATESH_ESYS 2 |
Wrong coordinate system in input. More... | |
#define | SKYCOORDINATESH_EZERO 3 |
Angular coordinates undefined at origin. More... | |
#define | SKYCOORDINATESH_ESING 4 |
Point is inside singular ellipsoid. More... | |
enum CoordinateSystem |
This enumerated type is used to identify data as being in one of the coordinate systems discussed in Header SkyCoordinates.h.
Definition at line 56 of file SkyCoordinates.h.
#define SKYCOORDINATESH_ENUL 1 |
Unexpected null pointer in arguments.
Definition at line 36 of file SkyCoordinates.h.
#define SKYCOORDINATESH_ESYS 2 |
Wrong coordinate system in input.
Definition at line 37 of file SkyCoordinates.h.
#define SKYCOORDINATESH_EZERO 3 |
Angular coordinates undefined at origin.
Definition at line 38 of file SkyCoordinates.h.
#define SKYCOORDINATESH_ESING 4 |
Point is inside singular ellipsoid.
Definition at line 39 of file SkyCoordinates.h.