1 /*
2 
3 -Procedure  vhat_c ( "V-Hat", unit vector along V, 3 dimensions )
4 
5 -Abstract
6 
7    Find the unit vector along a double precision 3-dimensional vector.
8 
9 -Disclaimer
10 
11    THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE
12    CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S.
13    GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE
14    ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE
15    PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS"
16    TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY
17    WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A
18    PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC
19    SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE
20    SOFTWARE AND RELATED MATERIALS, HOWEVER USED.
21 
22    IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA
23    BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT
24    LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND,
25    INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS,
26    REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE
27    REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY.
28 
29    RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF
30    THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY
31    CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE
32    ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE.
33 
34 -Required_Reading
35 
36    None.
37 
38 -Keywords
39 
40    VECTOR
41 
42 */
43 
44    #include <math.h>
45    #include "SpiceUsr.h"
46    #undef    vhat_c
47 
48 
vhat_c(ConstSpiceDouble v1[3],SpiceDouble vout[3])49    void vhat_c ( ConstSpiceDouble  v1  [3],
50                  SpiceDouble       vout[3] )
51 /*
52 
53 -Brief_I/O
54 
55    VARIABLE  I/O  DESCRIPTION
56    --------  ---  --------------------------------------------------
57    v1         I   Vector to be unitized.
58    vout       O   Unit vector v1 / |v1|.
59 
60 -Detailed_Input
61 
62     v1            This is any double precision, 3-dimensional vector.
63 
64 -Detailed_Output
65 
66     vout          vout contains the unit vector in the direction of v1.
67                   If v1 represents the zero vector, then vout will also
68                   be the zero vector.  vout may overwrite v1.
69 
70 -Parameters
71 
72    None.
73 
74 -Exceptions
75 
76    Error free.
77 
78    If v1 represents the zero vector, then vout will also be the zero
79    vector.
80 
81 -Files
82 
83    None.
84 
85 -Particulars
86 
87    vhat_c determines the magnitude of v1 and then divides each
88    component of v1 by the magnitude.  This process is highly stable
89    over the whole range of 3-dimensional vectors.
90 
91 -Examples
92 
93    The following table shows how v1 maps to vout.
94 
95    v1                        vout
96    ------------------        ------------------
97    ( 5,     12,    0     )   ( 5/13, 12/13, 0   )
98    ( 1.e-7, 2.e-7, 2.e-7 )   ( 1/3,  2/3,   2/3 )
99 
100 
101 -Restrictions
102 
103    None.
104 
105    There is no known case whereby floating point overflow may occur.
106    Thus, no error recovery or reporting scheme is incorporated
107    into this subroutine.
108 
109 -Literature_References
110 
111    None.
112 
113 -Author_and_Institution
114 
115    N.J. Bachman       (JPL)
116    W.L. Taber         (JPL)
117    W.M. Owen          (JPL)
118 
119 -Version
120 
121    -CSPICE Version 1.0.2, 16-JAN-2008   (EDW)
122 
123       Corrected typos in header titles:
124 
125       Detailed Input to Detailed_Input
126       Detailed Output to Detailed_Output
127 
128    -CSPICE Version 1.0.1, 12-NOV-2006 (EDW)
129 
130       Added Parameters section header.
131 
132    -CSPICE Version 1.0.0, 16-APR-1999 (EDW)
133 
134 -Index_Entries
135 
136    unitize a 3-dimensional vector
137 
138 -&
139 */
140 
141 {  /* Begin vhat_c */
142 
143 
144    /*
145    Local variables
146    */
147    SpiceDouble                        vmag;
148 
149 
150    /*
151    Obtain the magnitude of v1.
152    */
153    vmag = vnorm_c(v1);
154 
155    /*
156    If vmag is nonzero, then unitize.  Note that this process is
157    numerically stable: overflow could only happen if vmag were small,
158    but this could only happen if each component of v1 were small.
159    In fact, the magnitude of any vector is never less than the
160    magnitude of any component.
161    */
162 
163    if ( vmag > 0.0 )
164       {
165       vout[0] = v1[0] / vmag;
166       vout[1] = v1[1] / vmag;
167       vout[2] = v1[2] / vmag;
168       }
169    else
170       {
171       vout[0] = 0.0;
172       vout[1] = 0.0;
173       vout[2] = 0.0;
174       }
175 
176 
177 } /* End vhat_c */
178