1 /*
2 
3 -Procedure rav2xf_c ( Rotation and angular velocity to transform )
4 
5 -Abstract
6 
7    This routine determines a state transformation matrix
8    from a rotation matrix and the angular velocity of the
9    rotation.
10 
11 -Disclaimer
12 
13    THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE
14    CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S.
15    GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE
16    ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE
17    PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS"
18    TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY
19    WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A
20    PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC
21    SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE
22    SOFTWARE AND RELATED MATERIALS, HOWEVER USED.
23 
24    IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA
25    BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT
26    LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND,
27    INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS,
28    REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE
29    REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY.
30 
31    RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF
32    THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY
33    CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE
34    ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE.
35 
36 -Required_Reading
37 
38    None.
39 
40 -Keywords
41 
42    FRAMES
43 
44 */
45 
46    #include "SpiceUsr.h"
47    #undef rav2xf_c
48 
49 
rav2xf_c(ConstSpiceDouble rot[3][3],ConstSpiceDouble av[3],SpiceDouble xform[6][6])50    void rav2xf_c ( ConstSpiceDouble    rot   [3][3],
51                    ConstSpiceDouble    av    [3],
52                    SpiceDouble         xform [6][6]  )
53 
54 /*
55 
56 -Brief_I/O
57 
58    VARIABLE  I/O  DESCRIPTION
59    --------  ---  --------------------------------------------------
60    rot        I   Rotation matrix.
61    av         I   Angular velocity vector.
62    xform      O   State transformation associated with rot and av.
63 
64 -Detailed_Input
65 
66    rot         is a rotation that gives the transformation from
67                some frame frame1 to another frame frame2.
68 
69    av          is the angular velocity of the transformation.
70                In other words, if p is the position of a fixed
71                point in frame2, then from the point of view of
72                frame1,  p rotates (in a right handed sense) about
73                an axis parallel to av.  Moreover the rate of rotation
74                in radians per unit time is given by the length of
75                av.
76 
77                More formally, the velocity v of p in frame1 is
78                given by
79                                   t
80                    v  = av x ( rot * p )
81 
82 -Detailed_Output
83 
84    xform       is a state transformation matrix associated
85                with rot and av.  If s1 is the state of an object
86                with respect to frame1, then the state s2 of the
87                object with respect to frame2 is given by
88 
89                    s2  =  xform * s1
90 
91                where "*" denotes matrix-vector multiplication.
92 
93 
94 -Parameters
95 
96    None.
97 
98 -Exceptions
99 
100    Error free.
101 
102    1) No checks are performed on ROT to ensure that it is indeed
103       a rotation matrix.
104 
105 -Files
106 
107    None.
108 
109 -Particulars
110 
111    This routine is essentially a macro routine for converting
112    a rotation and angular velocity of the rotation to the
113    equivalent state transformation matrix.
114 
115    This routine is an inverse of xf2rav_c.
116 
117 -Examples
118 
119    Suppose that you wanted to determine state transformation
120    matrix from a platform frame to the J2000 frame.
121 
122       /.
123       The following call obtains the J2000-to-platform transformation
124       matrix and platform angular velocity at the time of interest.
125       The time value is expressed as encoded SCLK.
126       ./
127 
128       ckgpav_c ( ckid, time, tol, "J2000", rot, av, &clkout, &fnd );
129 
130       /.
131       Recall that rot and av are the rotation and angular velocity
132       of the transformation from J2000 to the platform frame.
133       ./
134 
135       if ( fnd )
136       {
137          /.
138          First get the state transformation from J2000 to the platform
139          frame.
140          ./
141 
142          rav2xf_c ( rot, av, j2plt );
143 
144          /.
145          Invert the state transformation matrix (using invstm_c) to
146          the desired state transformation matrix.
147          ./
148 
149          invstm_c ( j2plt, xform );
150       }
151 
152 -Restrictions
153 
154    None.
155 
156 -Literature_References
157 
158    None.
159 
160 -Author_and_Institution
161 
162    N.J. Bachman    (JPL)
163    W.L. Taber      (JPL)
164 
165 -Version
166 
167    -CSPICE Version 1.0.1, 12-APR-2007 (EDW)
168 
169       Edit to abstract.
170 
171    -CSPICE Version 1.0.0, 18-JUN-1999 (WLT) (NJB)
172 
173 -Index_Entries
174 
175   State transformation to rotation and angular velocity
176 
177 -&
178 */
179 
180    { /* Begin rav2xf_c */
181 
182 
183    /*
184    Local variables
185    */
186 
187    SpiceDouble             drdt   [3][3];
188    SpiceDouble             omegat [3][3];
189 
190    SpiceInt                i;
191    SpiceInt                j;
192 
193 
194 
195    /*
196    Error free:  no tracing required.
197 
198 
199    A state transformation matrix xform has the following form
200 
201 
202        [      |     ]
203        |  r   |  0  |
204        |      |     |
205        | -----+-----|
206        |  dr  |     |
207        |  --  |  r  |
208        [  dt  |     ]
209 
210 
211    where r is a rotation and dr/dt is the time derivative of that
212    rotation.  From this we can immediately fill in most of the
213    state transformation matrix.
214    */
215 
216 
217 
218    for ( i = 0;  i < 3;  i++ )
219       {
220       for ( j = 0;  j < 3;  j++ )
221          {
222          xform[i  ][j  ]  =  rot [i][j];
223          xform[i+3][j+3]  =  rot [i][j];
224          xform[i  ][j+3]  =  0.;
225          }
226       }
227 
228 
229 
230    /*
231    Now for the rest.
232 
233    Recall that rot is a transformation that converts positions
234    in some frame frame1 to positions in a second frame frame2.
235 
236    The angular velocity matrix omega (the cross product matrix
237    corresponding to av) has the following property.
238 
239    If p is the position of an object that is stationary with
240    respect to frame2 then the velocity v of that object in frame1
241    is given by:
242                         t
243        v  =  omega * rot  *  p
244 
245    But v is also given by
246 
247                   t
248              d rot
249        v =   -----  * p
250                dt
251 
252    So that
253                                 t
254                   t        d rot
255        omega * rot    =   -------
256                              dt
257 
258    Hence
259 
260         d rot                 t
261         -----   =  rot * omega
262           dt
263 
264 
265    From this discussion we can see that we need omega transpose.
266    Here it is.
267    */
268 
269    omegat[0][0] =  0.0;
270    omegat[1][0] = -av[2];
271    omegat[2][0] =  av[1];
272 
273    omegat[0][1] =  av[2];
274    omegat[1][1] =  0.0;
275    omegat[2][1] = -av[0];
276 
277    omegat[0][2] = -av[1];
278    omegat[1][2] =  av[0];
279    omegat[2][2] =  0.0;
280 
281 
282    mxm_c ( rot, omegat, drdt );
283 
284 
285    for ( i = 0;  i < 3;  i++ )
286       {
287       for ( j = 0;  j < 3;  j++ )
288          {
289          xform[i+3][j]  =  drdt [i][j];
290          }
291       }
292 
293 
294    } /* End rav2xf_c */
295 
296