1 /* 2 3 -Procedure eul2xf_c ( Euler angles and derivative to transformation) 4 5 -Abstract 6 7 This routine computes a state transformation from an Euler angle 8 factorization of a rotation and the derivatives of those Euler 9 angles. 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 ROTATION 39 40 -Keywords 41 42 ANGLES 43 STATE 44 DERIVATIVES 45 46 */ 47 48 #include "SpiceUsr.h" 49 #include "SpiceZfc.h" 50 #undef eul2xf_c 51 52 eul2xf_c(ConstSpiceDouble eulang[6],SpiceInt axisa,SpiceInt axisb,SpiceInt axisc,SpiceDouble xform[6][6])53 void eul2xf_c ( ConstSpiceDouble eulang[6], 54 SpiceInt axisa, 55 SpiceInt axisb, 56 SpiceInt axisc, 57 SpiceDouble xform [6][6] ) 58 /* 59 60 -Brief_I/O 61 62 VARIABLE I/O DESCRIPTION 63 -------- --- -------------------------------------------------- 64 eulang I An array of Euler angles and their derivatives. 65 axisa I Axis A of the Euler angle factorization. 66 axisb I Axis B of the Euler angle factorization. 67 axisc I Axis C of the Euler angle factorization. 68 xform O A state transformation matrix. 69 70 -Detailed_Input 71 72 73 eulang is the set of Euler angles corresponding to the 74 specified factorization. 75 76 If we represent r as shown here: 77 78 r = [ alpha ] [ beta ] [ gamma ] 79 axisa axisb axisc 80 81 then 82 83 84 eulang[0] = alpha 85 eulang[1] = beta 86 eulang[2] = gamma 87 eulang[3] = dalpha/dt 88 eulang[4] = dbeta/dt 89 eulang[5] = dgamma/dt 90 91 92 axisa are the axes desired for the factorization of r. 93 axisb All must be in the range from 1 to 3. Moreover 94 axisc it must be the case that axisa and axisb are distinct 95 and that axisb and axisc are distinct. 96 97 Every rotation matrix can be represented as a product 98 of three rotation matrices about the principal axes 99 of a reference frame. 100 101 r = [ alpha ] [ beta ] [ gamma ] 102 axisa axisb axisc 103 104 The value 1 corresponds to the X axis. 105 The value 2 corresponds to the Y axis. 106 The value 3 corresponds to the Z axis. 107 108 109 -Detailed_Output 110 111 xform is the state transformation corresponding r and dr/dt 112 as described above. Pictorially, 113 114 [ | ] 115 | r | 0 | 116 | | | 117 |-------+--------| 118 | | | 119 | dr/dt | r | 120 [ | ] 121 122 where r is a rotation that varies with respect to time 123 and dr/dt is its time derivative. 124 125 -Parameters 126 127 None. 128 129 -Exceptions 130 131 All erroneous inputs are diagnosed by routines in the call 132 tree to this routine. These include 133 134 1) If any of axisa, axisb, or axisc do not have values in 135 136 { 1, 2, 3 }, 137 138 then the error SPICE(INPUTOUTOFRANGE) is signaled. 139 140 -Files 141 142 None. 143 144 -Particulars 145 146 This function is intended to provide an inverse for the function 147 xf2eul_c. 148 149 150 A word about notation: the symbol 151 152 [ x ] 153 i 154 155 indicates a coordinate system rotation of x radians about the 156 ith coordinate axis. To be specific, the symbol 157 158 [ x ] 159 1 160 161 indicates a coordinate system rotation of x radians about the 162 first, or x-, axis; the corresponding matrix is 163 164 +- -+ 165 | 1 0 0 | 166 | | 167 | 0 cos(x) sin(x) |. 168 | | 169 | 0 -sin(x) cos(x) | 170 +- -+ 171 172 Remember, this is a COORDINATE SYSTEM rotation by x radians; this 173 matrix, when applied to a vector, rotates the vector by -x 174 radians, not x radians. Applying the matrix to a vector yields 175 the vector's representation relative to the rotated coordinate 176 system. 177 178 The analogous rotation about the second, or y-, axis is 179 represented by 180 181 [ x ] 182 2 183 184 which symbolizes the matrix 185 186 +- -+ 187 | cos(x) 0 -sin(x) | 188 | | 189 | 0 1 0 |, 190 | | 191 | sin(x) 0 cos(x) | 192 +- -+ 193 194 and the analogous rotation about the third, or z-, axis is 195 represented by 196 197 [ x ] 198 3 199 200 which symbolizes the matrix 201 202 +- -+ 203 | cos(x) sin(x) 0 | 204 | | 205 | -sin(x) cos(x) 0 |. 206 | | 207 | 0 0 1 | 208 +- -+ 209 210 211 The input matrix is assumed to be the product of three 212 rotation matrices, each one of the form 213 214 +- -+ 215 | 1 0 0 | 216 | | 217 | 0 cos(r) sin(r) | (rotation of r radians about the 218 | | x-axis), 219 | 0 -sin(r) cos(r) | 220 +- -+ 221 222 223 +- -+ 224 | cos(s) 0 -sin(s) | 225 | | 226 | 0 1 0 | (rotation of s radians about the 227 | | y-axis), 228 | sin(s) 0 cos(s) | 229 +- -+ 230 231 or 232 233 +- -+ 234 | cos(t) sin(t) 0 | 235 | | 236 | -sin(t) cos(t) 0 | (rotation of t radians about the 237 | | z-axis), 238 | 0 0 1 | 239 +- -+ 240 241 where the second rotation axis is not equal to the first or 242 third. Any rotation matrix can be factored as a sequence of 243 three such rotations, provided that this last criterion is met. 244 245 This routine is related to the routine eul2xf_c which produces 246 a state transformation from an input set of axes, Euler angles 247 and derivatives. 248 249 The two function calls shown here will not change xform except for 250 round off errors. 251 252 xf2eul_c ( xform, axisa, axisb, axisc, eulang, &unique ); 253 eul2xf_c ( eulang, axisa, axisb, axisc, xform ); 254 255 On the other hand the two calls 256 257 eul2xf_c ( eulang, axisa, axisb, axisc, xform ); 258 xf2eul_c ( xform, axisa, axisb, axisc, eulang, &unique ); 259 260 will leave eulang unchanged only if the components of eulang 261 are in the range produced by xf2eul_c and the Euler representation 262 of the rotation component of xform is unique within that range. 263 264 265 -Examples 266 267 Suppose you have a set of Euler angles and their derivatives 268 for a 3 1 3 rotation, and that you would like to determine 269 the equivalent angles and derivatives for a 1 2 3 rotation. 270 271 r = [alpha] [beta] [gamma] 272 3 1 3 273 274 r = [roll] [pitch] [yaw] 275 1 2 3 276 277 The following code fragment will perform the desired computation. 278 279 abgang[0] = alpha; 280 abgang[1] = beta; 281 abgang[2] = gamma; 282 abgang[3] = dalpha; 283 abgang[4] = dbeta; 284 abgang[5] = dgamma; 285 286 eul2xf_c ( abgang, 3, 1, 3, xform ); 287 xf2eul_c ( xform, 1, 2, 3, rpyang, &unique ); 288 289 roll = rpyang[0]; 290 pitch = rpyang[1]; 291 yaw = rpyang[2]; 292 droll = rpyang[3]; 293 dpitch = rpyang[4]; 294 dyaw = rpyang[5]; 295 296 297 -Restrictions 298 299 None. 300 301 -Literature_References 302 303 None. 304 305 -Author_and_Institution 306 307 N.J. Bachman (JPL) 308 W.L. Taber (JPL) 309 310 -Version 311 312 -CSPICE Version 2.0.1, 25-APR-2007 (EDW) 313 314 Corrected code in Examples section, example showed 315 a xf2eul_c call: 316 317 xf2eul_c( xform, 1, 2, 3, rpyang); 318 319 The proper form of the call: 320 321 xf2eul_c( xform, 1, 2, 3, rpyang, &unique ); 322 323 -CSPICE Version 2.0.0, 31-OCT-2005 (NJB) 324 325 Restriction that second axis must differ from the first 326 and third was removed. 327 328 -CSPICE Version 1.0.1, 03-JUN-2003 (EDW) 329 330 Correct typo in Procedure line. 331 332 -CSPICE Version 1.0.0, 18-MAY-1999 (WLT) (NJB) 333 334 -Index_Entries 335 336 State transformation from Euler angles and derivatives 337 338 -& 339 */ 340 341 342 343 { /* Begin xf2eul_c */ 344 345 346 /* 347 Participate in error tracing. 348 */ 349 chkin_c ( "eul2xf_c" ); 350 351 352 eul2xf_ ( ( doublereal * ) eulang, 353 ( integer * ) &axisa, 354 ( integer * ) &axisb, 355 ( integer * ) &axisc, 356 ( doublereal * ) xform ); 357 358 /* 359 Convert the output matrix to row-major order. 360 */ 361 xpose6_c ( xform, xform ); 362 363 364 chkout_c ( "eul2xf_c" ); 365 366 } /* End xf2eul_c */ 367 368