LAL  7.1.7.1-56c71ae
SkyCoordinates.h
Go to the documentation of this file.
1 /*
2 * Copyright (C) 2007 Jolien Creighton, Reinhard Prix, Teviet Creighton
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with with program; see the file COPYING. If not, write to the
16 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
17 * MA 02110-1301 USA
18 */
19 
20 #ifndef _SKYCOORDINATES_H
21 #define _SKYCOORDINATES_H
22 
23 #include <lal/LALStdlib.h>
24 
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28 
29 /**
30  * \addtogroup SkyCoordinates_h
31  * @{
32  */
33 
34 /** \name Error codes */
35 /** @{ */
36 #define SKYCOORDINATESH_ENUL 1 /**< Unexpected null pointer in arguments */
37 #define SKYCOORDINATESH_ESYS 2 /**< Wrong coordinate system in input */
38 #define SKYCOORDINATESH_EZERO 3 /**< Angular coordinates undefined at origin */
39 #define SKYCOORDINATESH_ESING 4 /**< Point is inside singular ellipsoid */
40 /** @} */
41 
42 /** \cond DONT_DOXYGEN */
43 #define SKYCOORDINATESH_MSGENUL "Unexpected null pointer in arguments"
44 #define SKYCOORDINATESH_MSGESYS "Wrong coordinate system in input"
45 #define SKYCOORDINATESH_MSGEZERO "Angular coordinates undefined at origin"
46 #define SKYCOORDINATESH_MSGESING "Point is inside singular ellipsoid"
47 /** \endcond */
48 
49 
50 /*---------- exported types ---------- */
51 
52 /**
53  * This enumerated type is used to identify data as being in one of the
54  * coordinate systems discussed in \ref SkyCoordinates_h.
55  */
56 typedef enum tagCoordinateSystem {
57  COORDINATESYSTEM_HORIZON, /**< A horizon coordinate system. */
58  COORDINATESYSTEM_GEOGRAPHIC, /**< The Earth-fixed geographic coordinate system. */
59  COORDINATESYSTEM_EQUATORIAL, /**< The sky-fixed equatorial coordinate system. */
60  COORDINATESYSTEM_ECLIPTIC, /**< The ecliptic coordinate system. */
61  COORDINATESYSTEM_GALACTIC /**< The galactic coordinate system. */
63 
64 /**
65  * This structure stores the two spherical coordinates of a sky position;
66  * ie a generic latitude and longitude; the structure is not defined
67  * specific to a particular coordinate system, but maintains a tag
68  * indicating which coordinate system it is expressed in.
69  */
70 typedef struct tagSkyPosition {
71  REAL8 longitude; /**< The longitudinal coordinate (in radians), as defined above.*/
72  REAL8 latitude; /**< The latitudinal coordinate (in radians), as defined above. */
73  CoordinateSystem system; /**< The coordinate system in which latitude/longitude are expressed. */
74 } SkyPosition;
75 
76 /**
77  * This structure stores the location of a point on (or near) the surface
78  * of the Earth in both geodetic and geocentric coordinates, as described
79  * in TerrestrialCoordinates.c .
80  */
81 typedef struct tagEarthPosition {
82  SkyPosition geodetic; /**< The geographic coordinates of the
83  * upward vertical direction from the point; that is, the point's
84  * <em>geodetic</em> latitude and longitude. */
85 
86  REAL8 elevation; /**< The vertical distance of the point above the reference ellipsoid,
87  * in metres.*/
88 
89  REAL8 x, y, z; /**< The Earth-fixed geocentric Cartesian coordinates of the point,
90  *in metres.*/
91 
92  REAL8 radius; /**< The distance of the point from the geocentre, in metres. */
93 
94  SkyPosition geocentric; /**< The geographic coordinates of the direction from the centre
95  * of the Earth through the point; that is, the point's
96  * <em>geocentric</em> latitude and longitude.*/
98 
99 
100 /**
101  * This structure stores parameters for the function <tt>LALConvertSkyPosition()</tt>.
102  */
103 typedef struct tagConvertSkyParams {
104  CoordinateSystem system; /**< The coordinate system to which one is transforming. */
105 
106  SkyPosition *zenith; /**< The position of the zenith of the horizon coordinate system;
107  * may be <tt>NULL</tt> if one is neither converting to nor from
108  * a horizon system. */
109 
110  LIGOTimeGPS *gpsTime; /**< The GPS time for conversions between Earth-fixed and
111  * sky-fixed coordinates; may be <tt>NULL</tt> if no such conversion
112  * is required (or if one is transforming to or from horizon
113  * coordinates and <tt>*zenith</tt> is given in the sky-fixed
114  * equatorial system). */
116 
117 /** @} */
118 
119 /* ---------- Function prototypes ---------- */
120 
121 void
123  SkyPosition *output,
124  SkyPosition *input );
125 
126 void
128  SkyPosition *output,
129  SkyPosition *input );
130 
131 void
133  SkyPosition *output,
134  SkyPosition *input );
135 
136 void
138  SkyPosition *output,
139  SkyPosition *input );
140 
141 void
143  SkyPosition *output,
144  SkyPosition *input,
145  LIGOTimeGPS *gpsTime );
146 
147 void
149  SkyPosition *output,
150  SkyPosition *input,
151  LIGOTimeGPS *gpsTime );
152 
153 void
155  SkyPosition *output,
156  SkyPosition *input,
157  const SkyPosition *zenith );
158 
159 void
161  SkyPosition *output,
162  SkyPosition *input,
163  const SkyPosition *zenith );
164 
165 void
167 
168 void
170 
171 void
173  SkyPosition *output,
174  SkyPosition *input,
175  ConvertSkyParams *params );
176 
177 void LALNormalizeSkyPosition (LALStatus *status, SkyPosition *posOut, const SkyPosition *posIn);
178 
179 #ifdef SWIG /* SWIG interface directives */
180 SWIGLAL(INOUT_SCALARS(double*, longitude, latitude));
181 #endif
182 
183 void XLALNormalizeSkyPosition ( double *_LAL_RESTRICT_ longitude, double *_LAL_RESTRICT_ latitude );
184 
185 #ifdef __cplusplus
186 }
187 #endif
188 
189 #endif /* _SKYCOORDINATES_H */
void LALGeodeticToGeocentric(LALStatus *, EarthPosition *location)
void LALEclipticToEquatorial(LALStatus *, SkyPosition *output, SkyPosition *input)
The galactic coordinate system.
#define _LAL_RESTRICT_
Definition: LALStddef.h:26
This structure stores parameters for the function LALConvertSkyPosition().
SkyPosition * zenith
The position of the zenith of the horizon coordinate system; may be NULL if one is neither converting...
Epoch relative to GPS epoch, see LIGOTimeGPS type for more details.
Definition: LALDatatypes.h:458
void LALEquatorialToGeographic(LALStatus *, SkyPosition *output, SkyPosition *input, LIGOTimeGPS *gpsTime)
REAL8 radius
The distance of the point from the geocentre, in metres.
The sky-fixed equatorial coordinate system.
REAL8 elevation
The vertical distance of the point above the reference ellipsoid, in metres.
REAL8 latitude
The latitudinal coordinate (in radians), as defined above.
void LALEquatorialToEcliptic(LALStatus *, SkyPosition *output, SkyPosition *input)
CoordinateSystem system
The coordinate system to which one is transforming.
void LALConvertSkyCoordinates(LALStatus *, SkyPosition *output, SkyPosition *input, ConvertSkyParams *params)
void LALGalacticToEquatorial(LALStatus *, SkyPosition *output, SkyPosition *input)
void LALNormalizeSkyPosition(LALStatus *status, SkyPosition *posOut, const SkyPosition *posIn)
SkyPosition geocentric
The geographic coordinates of the direction from the centre of the Earth through the point; that is...
This structure stores the two spherical coordinates of a sky position; ie a generic latitude and long...
CoordinateSystem system
The coordinate system in which latitude/longitude are expressed.
void LALGeographicToEquatorial(LALStatus *, SkyPosition *output, SkyPosition *input, LIGOTimeGPS *gpsTime)
void LALGeocentricToGeodetic(LALStatus *, EarthPosition *location)
The ecliptic coordinate system.
The Earth-fixed geographic coordinate system.
void LALEquatorialToGalactic(LALStatus *, SkyPosition *output, SkyPosition *input)
double REAL8
Double precision real floating-point number (8 bytes).
A horizon coordinate system.
LAL status structure, see The LALStatus structure for more details.
Definition: LALDatatypes.h:947
void LALHorizonToSystem(LALStatus *, SkyPosition *output, SkyPosition *input, const SkyPosition *zenith)
REAL8 longitude
The longitudinal coordinate (in radians), as defined above.
This structure stores the location of a point on (or near) the surface of the Earth in both geodetic ...
LIGOTimeGPS * gpsTime
The GPS time for conversions between Earth-fixed and sky-fixed coordinates; may be NULL if no such co...
SkyPosition geodetic
The geographic coordinates of the upward vertical direction from the point; that is, the point&#39;s geodetic latitude and longitude.
REAL8 z
The Earth-fixed geocentric Cartesian coordinates of the point, in metres.
void LALSystemToHorizon(LALStatus *, SkyPosition *output, SkyPosition *input, const SkyPosition *zenith)
CoordinateSystem
This enumerated type is used to identify data as being in one of the coordinate systems discussed in ...
void XLALNormalizeSkyPosition(double *_LAL_RESTRICT_ longitude, double *_LAL_RESTRICT_ latitude)