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