1 /*
2 
3 -Procedure recrad_c ( Rectangular coordinates to RA and DEC )
4 
5 -Abstract
6 
7    Convert rectangular coordinates to range, right ascension, and
8    declination.
9 
10 -Disclaimer
11 
12    THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE
13    CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S.
14    GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE
15    ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE
16    PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS"
17    TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY
18    WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A
19    PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC
20    SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE
21    SOFTWARE AND RELATED MATERIALS, HOWEVER USED.
22 
23    IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA
24    BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT
25    LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND,
26    INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS,
27    REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE
28    REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY.
29 
30    RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF
31    THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY
32    CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE
33    ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE.
34 
35 -Required_Reading
36 
37    None.
38 
39 -Keywords
40 
41    CONVERSION,  COORDINATES
42 
43 */
44 
45    #include "SpiceUsr.h"
46    #undef    recrad_c
47 
48 
recrad_c(ConstSpiceDouble rectan[3],SpiceDouble * range,SpiceDouble * ra,SpiceDouble * dec)49    void recrad_c ( ConstSpiceDouble    rectan[3],
50                    SpiceDouble       * range,
51                    SpiceDouble       * ra,
52                    SpiceDouble       * dec      )
53 
54 /*
55 
56 -Brief_I/O
57 
58    VARIABLE  I/O  DESCRIPTION
59    --------  ---  --------------------------------------------------
60    rectan     I   Rectangular coordinates of a point.
61    range      O   Distance of the point from the origin.
62    ra         O   Right ascension in radians.
63    dec        O   Declination in radians.
64 
65 -Detailed_Input
66 
67    rectan     The rectangular coordinates of a point.
68 
69 -Detailed_Output
70 
71    range      is the distance of the point `rectan' from the origin.
72 
73               The units associated with `range' are those associated
74               with the input `rectan'.
75 
76    ra         is the right ascension of `rectan'.  This is the angular
77               distance measured toward the east from the prime meridian
78               to the meridian containing the input point. The direction
79               of increasing right ascension is from the +X axis towards
80               the +Y axis.
81 
82               `ra' is output in radians.  The range of `ra' is [0, 2*pi].
83 
84 
85    dec        is the declination of `rectan'.  This is the angle from
86               the XY plane of the ray from the origin through the
87               point.
88 
89               `dec' is output in radians.  The range of `dec' is
90               [-pi/2, pi/2].
91 
92 -Parameters
93 
94    None.
95 
96 -Exceptions
97 
98    Error free.
99 
100    1) If the X and Y components of `rectan' are both zero, the
101       right ascension is set to zero.
102 
103    2) If `rectan' is the zero vector, right ascension and declination
104       are both set to zero.
105 
106 -Files
107 
108    None.
109 
110 -Particulars
111 
112    None.
113 
114 -Examples
115 
116    The following code fragment converts right ascension and
117    declination from the B1950 reference frame to the J2000 frame.
118 
119       #include "SpiceUsr.h"
120 
121       SpiceDouble      ra;
122       SpiceDouble      dec;
123       SpiceDouble      r;
124       SpiceDouble      mtrans  [ 3 ][ 3 ];
125       SpiceDouble      v1950   [ 3 ];
126       SpiceDouble      v2000   [ 3 ];
127 
128       /.
129       Convert RA and DEC to a 3-vector expressed in the B1950 frame.
130       ./
131       radrec_c ( 1.0, ra, dec, v1950 );
132 
133       /.
134       We use the CSPICE routine pxform_c to obtain the transformation
135       matrix for converting vectors between the B1950 and J2000
136       reference frames.  Since both frames are inertial, the input time
137       value we supply to pxform_c is arbitrary.  We choose zero seconds
138       past the J2000 epoch as the input value.
139       ./
140       pxform_c ( "B1950", "J2000", 0.0, mtrans );
141 
142       /.
143       Transform the vector to the J2000 frame.
144       ./
145       mxv_c    ( mtrans, v1950, v2000 );
146 
147       /.
148       Find the RA and DEC of the J2000-relative vector.
149       ./
150       recrad_c ( v2000, &r, &ra, &dec );
151 
152 
153 -Restrictions
154 
155    None.
156 
157 -Author_and_Institution
158 
159    N.J. Bachman    (JPL)
160    H.A. Neilan     (JPL)
161    E.D. Wright     (JPL)
162 
163 -Literature_References
164 
165    None.
166 
167 -Version
168 
169    -CSPICE Version 1.1.2, 30-JUL-2003 (NJB)
170 
171        Various header corrections were made.
172 
173    -CSPICE Version 1.1.0, 22-OCT-1998 (NJB)
174 
175       Made input vector const.
176 
177    -CSPICE Version 1.0.0, 08-FEB-1998 (EDW)
178 
179 -Index_Entries
180 
181    rectangular coordinates to ra and dec
182    rectangular to right_ascension and declination
183 
184 -&
185 */
186 
187 { /* Begin recrad_c */
188 
189    /*
190    Call reclat_c to perform the conversion to angular terms.
191    */
192 
193    reclat_c ( rectan, range, ra, dec );
194 
195 
196    /*
197    Right ascension is always in the domain [0, 2Pi].  Rectan_c returns
198    ra in the domain [ -Pi, Pi ].  If ra is negative, add 2 Pi to map the
199    value to the correct domain
200    */
201 
202    if ( *ra < 0. )
203       {
204       *ra = *ra + twopi_c();
205       }
206 
207 
208 
209 } /* End recrad_c */
210