1 /*
2 
3 -Procedure vproj_c ( Vector projection, 3 dimensions )
4 
5 -Abstract
6 
7    vproj_c finds the projection of one vector onto another vector.
8    All vectors are 3-dimensional.
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    VECTOR
42 
43 */
44 
45    #include "SpiceUsr.h"
46    #include "SpiceZmc.h"
47    #undef  vproj_c
48 
vproj_c(ConstSpiceDouble a[3],ConstSpiceDouble b[3],SpiceDouble p[3])49    void vproj_c ( ConstSpiceDouble   a[3],
50                   ConstSpiceDouble   b[3],
51                   SpiceDouble        p[3] )
52 
53 /*
54 
55 -Brief_I/O
56 
57    VARIABLE  I/O  DESCRIPTION
58    --------  ---  --------------------------------------------------
59     a         I    The vector to be projected.
60     b         I    The vector onto which a is to be projected.
61     p         O    The projection of a onto b.
62 
63 -Detailed_Input
64 
65    a     is a double precision, 3-dimensional vector.  This
66           vector is to be projected onto the vector b.
67 
68    b     is a double precision, 3-dimensional vector.  This
69           vector is the vector which receives the projection.
70 
71 -Detailed_Output
72 
73    p     is a double precision, 3-dimensional vector containing
74           the projection of a onto b.  p may overwrite either
75           a or b.  (p is necessarily parallel to b.)  If b is
76           the zero vector then p will be returned as the zero vector.
77 
78 -Parameters
79 
80    None.
81 
82 -Particulars
83 
84    The given any vectors a and b there is a unique decomposition
85    of a as a sum v + p such that v  the dot product of v and b
86    is zero, and the dot product of p with b is equal the product
87    of the lengths of p and b.  p is called the projection of
88    a onto b.  It can be expressed mathematically as
89 
90           dot(a,b)
91           -------- * b
92           dot(b,b)
93 
94    (This is not necessarily the prescription used to compute
95    the projection. It is intended only for descriptive purposes.)
96 
97 -Examples
98 
99    The following table gives sample inputs and results from calling
100    vproj_c.
101 
102     a                   b                        p
103     --------------------------------------------------
104     (6, 6, 6)      ( 2, 0, 0)                (6, 0, 0)
105     (6, 6, 6)      (-3, 0, 0)                (6, 0, 0)
106     (6, 6, 0)      ( 0, 7, 0)                (0, 6, 0)
107     (6, 0, 0)      ( 0, 0, 9)                (0, 0, 0)
108 
109 -Restrictions
110 
111    None.
112 
113 -Exceptions
114 
115    Error free.
116 
117 -Files
118 
119    None.
120 
121 -Author_and_Institution
122 
123    W.L. Taber      (JPL)
124 
125 -Literature_References
126 
127    REFERENCE: Any reasonable calculus text (for example Thomas)
128 
129 -Version
130 
131    -CSPICE Version 1.0.0, 08-FEB-1998   (EDW)
132 
133 -Index_Entries
134 
135    3-dimensional vector projection
136 
137 -&
138 */
139 
140 { /* Begin vproj_c */
141 
142 
143    /*
144    Local variables
145    */
146 
147    SpiceDouble     biga;
148    SpiceDouble     bigb;
149    SpiceDouble     r[3];
150    SpiceDouble     t[3];
151    SpiceDouble     scale;
152 
153 
154    biga = MaxAbs ( a[0] ,MaxAbs ( a[1], a[2] ) );
155    bigb = MaxAbs ( b[0] ,MaxAbs ( b[1], b[2] ) );
156 
157 
158    /*
159    If a or b is zero, return the zero vector.
160    */
161 
162    if ( biga == 0 || bigb == 0 )
163       {
164       p[0] = 0.0;
165       p[1] = 0.0;
166       p[2] = 0.0;
167       return;
168       }
169 
170 
171    vscl_c ( 1./biga, a, t );
172    vscl_c ( 1./bigb, b, r );
173 
174    scale = vdot_c (t,r) * biga  / vdot_c (r,r);
175 
176    vscl_c ( scale, r, p );
177 
178 
179 } /* End vproj_c */
180