1 /* twovxf.f -- translated by f2c (version 19980913).
2 You must link the resulting object file with the libraries:
3 -lf2c -lm (in that order)
4 */
5
6 #include "f2c.h"
7
8 /* $Procedure TWOVXF ( Two states defining a frame transformation ) */
twovxf_(doublereal * axdef,integer * indexa,doublereal * plndef,integer * indexp,doublereal * xform)9 /* Subroutine */ int twovxf_(doublereal *axdef, integer *indexa, doublereal *
10 plndef, integer *indexp, doublereal *xform)
11 {
12 extern /* Subroutine */ int chkin_(char *, ftnlen), zztwovxf_(doublereal *
13 , integer *, doublereal *, integer *, doublereal *);
14 doublereal xi[36] /* was [6][6] */;
15 extern /* Subroutine */ int chkout_(char *, ftnlen);
16 extern logical return_(void);
17 extern /* Subroutine */ int invstm_(doublereal *, doublereal *);
18
19 /* $ Abstract */
20
21 /* Find the state transformation from a base frame to the */
22 /* right-handed frame defined by two state vectors: one state */
23 /* vector defining a specified axis and a second state vector */
24 /* defining a specified coordinate plane. */
25
26 /* $ Disclaimer */
27
28 /* THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE */
29 /* CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. */
30 /* GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE */
31 /* ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE */
32 /* PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" */
33 /* TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY */
34 /* WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A */
35 /* PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC */
36 /* SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE */
37 /* SOFTWARE AND RELATED MATERIALS, HOWEVER USED. */
38
39 /* IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA */
40 /* BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT */
41 /* LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, */
42 /* INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, */
43 /* REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE */
44 /* REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. */
45
46 /* RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF */
47 /* THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY */
48 /* CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE */
49 /* ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. */
50
51 /* $ Required_Reading */
52
53 /* None. */
54
55 /* $ Keywords */
56
57 /* AXES */
58 /* FRAMES */
59 /* MATRIX */
60 /* TRANSFORMATION */
61
62 /* $ Declarations */
63 /* $ Brief_I/O */
64
65 /* VARIABLE I/O DESCRIPTION */
66 /* -------- --- ------------------------------------------------- */
67 /* AXDEF I State defining a principal axis. */
68 /* INDEXA I Principal axis number of AXDEF (X=1, Y=2, Z=3). */
69 /* PLNDEF I State defining (with AXDEF) a principal plane. */
70 /* INDEXP I Second axis number (with INDEXA) of principal */
71 /* plane. */
72 /* XFORM O Output state transformation matrix. */
73
74 /* $ Detailed_Input */
75
76 /* AXDEF is a "generalized" state vector defining one of the */
77 /* principal axes of a reference frame. This vector */
78 /* consists of three components of a vector-valued */
79 /* function of one independent variable t followed by */
80 /* the derivatives of the components with respect to that */
81 /* variable: */
82
83 /* ( a, b, c, da/dt, db/dt, dc/dt ) */
84
85 /* This routine treats the input states as unitless, but */
86 /* in most applications the input states represent */
87 /* quantities that have associated units. The first three */
88 /* components must have the same units, and the units of */
89 /* the last three components must be compatible with */
90 /* those of the first three: if the first three */
91 /* components of AXDEF */
92
93 /* ( a, b, c ) */
94
95 /* have units U and t has units T, then the units of */
96 /* AXDEF normally would be */
97
98 /* ( U, U, U, U/T, U/T, U/T ) */
99
100 /* Note that the direction and angular velocity defined */
101 /* by AXDEF are actually independent of U, so scaling */
102 /* AXDEF doesn't affect the output of this routine. */
103
104 /* AXDEF could represent position and velocity; it could */
105 /* also represent velocity and acceleration. AXDEF could */
106 /* for example represent the velocity and acceleration of */
107 /* a time-dependent position vector ( x(t), y(t), z(t) ), */
108 /* in which case AXDEF would be defined by */
109
110 /* a = dx/dt */
111 /* b = dy/dt */
112 /* c = dz/dt */
113
114 /* 2 2 */
115 /* da/dt = d x / dt */
116
117 /* 2 2 */
118 /* db/dt = d y / dt */
119
120 /* 2 2 */
121 /* dc/dt = d z / dt */
122
123 /* Below, we'll call the normalized (unit length) version */
124 /* of */
125
126 /* ( a, b, c ) */
127
128 /* the "direction" of AXDEF. */
129
130 /* We call the frame relative to which AXDEF is specified */
131 /* the "base frame." The input state PLNDEF must be */
132 /* specified relative to the same base frame. */
133
134
135 /* INDEXA is the index of the reference frame axis that is */
136 /* parallel to the direction of AXDEF. */
137
138 /* Value of INDEXA Axis */
139
140 /* 1 X */
141 /* 2 Y */
142 /* 3 Z */
143
144
145 /* PLNDEF is a state vector defining (with AXDEF) a principal */
146 /* plane of the reference frame. This vector consists */
147 /* of three components followed by their derivatives with */
148 /* respect to the independent variable t associated with */
149 /* AXDEF, so PLNDEF is */
150
151 /* ( e, f, g, de/dt, df/dt, dg/dt ) */
152
153 /* Below, we'll call the unitized version of */
154
155 /* ( e, f, g ) */
156
157 /* the "direction" of PLNDEF. */
158
159 /* The second axis of the principal plane containing the */
160 /* direction vectors of AXDEF and PLNDEF is perpendicular */
161 /* to the first axis and has positive dot product with */
162 /* the direction vector of PLNDEF. */
163
164 /* The first three components of PLNDEF must have the */
165 /* same units, and the units of the last three components */
166 /* must be compatible with those of the first three: if */
167 /* the first three components of PLNDEF */
168
169 /* ( e, f, g ) */
170
171 /* have units U2 and t has units T, then the units of */
172 /* PLNDEF normally would be */
173
174 /* ( U2, U2, U2, U2/T, U2/T, U2/T ) */
175
176 /* ***For meaningful results, the angular velocities */
177 /* defined by AXDEF and PLNDEF must both have units of */
178 /* 1/T.*** */
179
180 /* As with AXDEF, scaling PLNDEF doesn't affect the */
181 /* output of this routine. */
182
183 /* AXDEF and PLNDEF must be specified relative to a */
184 /* common reference frame, which we call the "base */
185 /* frame." */
186
187
188 /* INDEXP is the index of second axis of the principal frame */
189 /* determined by AXDEF and PLNDEF. The association of */
190 /* integer values and axes is the same as for INDEXA. */
191
192 /* $ Detailed_Output */
193
194 /* XFORM is the 6x6 matrix that transforms states from the */
195 /* frame relative to which AXDEF and PLNDEF are specified */
196 /* (the "base frame") to the frame whose axes and */
197 /* derivative are determined by AXDEF, PLNDEF, INDEXA and */
198 /* INDEXP. */
199
200 /* The matrix XFORM has the structure shown below: */
201
202 /* - - */
203 /* | : | */
204 /* | R : 0 | */
205 /* | ......:......| */
206 /* | : | */
207 /* | dR_dt : R | */
208 /* | : | */
209 /* - - */
210
211 /* where R is a rotation matrix that is a function of */
212 /* the independent variable associated with AXDEF and */
213 /* PLNDEF, and where dR_dt is the derivative of R */
214 /* with respect to that independent variable. */
215
216 /* $ Parameters */
217
218 /* None. */
219
220 /* $ Exceptions */
221
222 /* 1) If INDEXA or INDEXP is not in the set {1,2,3} the error */
223 /* SPICE(BADINDEX) will be signaled. */
224
225 /* 2) If INDEXA and INDEXP are the same the error */
226 /* SPICE(UNDEFINEDFRAME) will be signaled. */
227
228 /* 3) If the cross product of the vectors AXDEF and PLNDEF is zero, */
229 /* the error SPICE(DEPENDENTVECTORS) will be signaled. */
230
231 /* $ Files */
232
233 /* None. */
234
235 /* $ Particulars */
236
237 /* Given two linearly independent state vectors AXDEF and PLNDEF, */
238 /* define vectors DIR1 and DIR2 by */
239
240 /* DIR1 = ( AXDEF(1), AXDEF(2), AXDEF(3) ) */
241 /* DIR2 = ( PLNDEF(1), PLNDEF(2), PLNDEF(3) ) */
242
243 /* Then there is a unique right-handed reference frame F having: */
244
245 /* DIR1 lying along the INDEXA axis. */
246
247 /* DIR2 lying in the INDEXA-INDEXP coordinate plane, such that */
248 /* the dot product of DIR2 with the positive INDEXP axis is */
249 /* positive. */
250
251 /* This routine determines the 6x6 matrix that transforms states */
252 /* from the base frame used to represent the input vectors to the */
253 /* the frame F determined by AXDEF and PLNDEF. Thus a state vector */
254
255 /* S = ( x, y, z, dx/dt, dy/dt, dz/dt ) */
256 /* base */
257
258 /* in the input reference frame will be transformed to */
259
260 /* S = XFORM * S */
261 /* F base */
262
263 /* in the frame F determined by AXDEF and PLNDEF. */
264
265 /* $ Examples */
266
267 /* The time-dependent Sun-Canopus reference frame associated with a */
268 /* spacecraft uses the spacecraft-sun state to define the Z axis and */
269 /* the Canopus direction to define the X-Z plane. */
270
271 /* Define an approximate "state vector" for Canopus using the */
272 /* J2000-relative, unit direction vector toward Canopus at a */
273 /* specified time ET (time is needed to compute proper motion) as */
274 /* position and the zero vector as velocity. Call this state vector */
275 /* STCANO. Let STSUN be the J2000-relative state of the sun */
276 /* relative to the spacecraft at ET. */
277
278 /* Then the matrix XFISC that transforms states from J2000 to the */
279 /* Sun-Canopus reference frame at ET is returned by the call */
280
281 /* CALL TWOVXF ( STSUN, 3, STCANO, 1, XFISC ) */
282
283 /* $ Restrictions */
284
285 /* None. */
286
287 /* $ Author_and_Institution */
288
289 /* N.J. Bachman (JPL) */
290 /* W.M. Owen (JPL) */
291 /* W.L. Taber (JPL) */
292
293 /* $ Literature_References */
294
295 /* None. */
296
297 /* $ Version */
298
299 /* - SPICELIB Version 1.0.0, 18-DEC-2004 (NJB) (WMO) (WLT) */
300
301 /* -& */
302 /* $ Index_Entries */
303
304 /* define a state transformation matrix from two states */
305
306 /* -& */
307
308 /* SPICELIB functions */
309
310
311 /* Local Variables */
312
313
314 /* Standard SPICE error handling */
315
316 if (return_()) {
317 return 0;
318 }
319 chkin_("TWOVXF", (ftnlen)6);
320
321 /* Get the matrix XI that transforms states from the frame */
322 /* defined by AXDEF and PLNDEF to their base frame. */
323
324 zztwovxf_(axdef, indexa, plndef, indexp, xi);
325
326 /* Invert XI. */
327
328 invstm_(xi, xform);
329 chkout_("TWOVXF", (ftnlen)6);
330 return 0;
331 } /* twovxf_ */
332
333