Table of contents
CSPICE_M2Q calculates a unit quaternion corresponding to a
specified rotation matrix.
Given:
r a rotation matri(x|ces).
[3,3] = size(r); double = class(r)
or
[3,3,n] = size(r); double = class(r)
the call:
[q] = cspice_m2q( r )
returns:
q an array of unit-length SPICE-style quaternion(s)
representing `r'.
If [3,3] = size(r) then [4,1] = size(q)
If [3,3,n] = size(r) then [4,n] = size(q)
double = class(q)
See the discussion of quaternion styles in -Particulars
below.
`q' is a 4-dimensional vector. If `r' rotates vectors
in the counterclockwise sense by an angle of theta
radians about a unit vector `a', where
0 < theta < pi
- -
then letting h = theta/2,
q = ( cos(h), sin(h)a , sin(h)a , sin(h)a ).
1 2 3
The restriction that theta must be in the range
[0, pi] determines the output quaternion `q'
uniquely except when theta = pi; in this special
case, both of the quaternions
q = ( 0, a , a , a )
1 2 3
and
q = ( 0, -a , -a , -a )
1 2 3
are possible outputs.
`q' returns with the same vectorization measure, N,
as `r' .
None.
Any numerical results shown for this example may differ between
platforms as the results depend on the SPICE kernels used as input
and the machine specific arithmetic implementation.
1) Create a 3-dimensional rotation matrix of 90 degrees about the
Z axis and convert it to a unit quaternion. Verify that the
norm of the quaternion is equal to 1.
Example code begins here.
function m2q_ex1()
%
% Create a rotation matrix of 90 degrees about the Z axis.
%
r = cspice_rotate( cspice_halfpi, 3);
fprintf('Rotation matrix:\n');
fprintf('%15.7f %15.7f %15.7f\n', r(1,:));
fprintf('%15.7f %15.7f %15.7f\n', r(2,:));
fprintf('%15.7f %15.7f %15.7f\n', r(3,:));
%
% Convert the matrix to a quaternion.
%
q = cspice_m2q( r );
fprintf('Unit quaternion:\n');
fprintf('%15.7f %15.7f %15.7f %15.7f\n', q);
% _
% Confirm || q || = 1.
%
fprintf( '\n|| q || = %15.7f\n', q' * q );
When this program was executed on a Mac/Intel/Octave6.x/64-bit
platform, the output was:
Rotation matrix:
0.0000000 1.0000000 0.0000000
-1.0000000 0.0000000 0.0000000
0.0000000 0.0000000 1.0000000
Unit quaternion:
0.7071068 0.0000000 0.0000000 -0.7071068
|| q || = 1.0000000
Note, the call sequence:
q = cspice_m2q( r );
r = cspice_q2m( q );
preserves `r' except for round-off error. Yet, the call sequence:
r = cspice_q2m( q );
q = cspice_m2q( r );
may preserve `q' or return `-q'.
About SPICE quaternions
=======================
There are (at least) two popular "styles" of quaternions; these
differ in the layout of the quaternion elements, the definition
of the multiplication operation, and the mapping between the set
of unit quaternions and corresponding rotation matrices.
SPICE-style quaternions have the scalar part in the first
component and the vector part in the subsequent components. The
SPICE convention, along with the multiplication rules for SPICE
quaternions, are those used by William Rowan Hamilton, the
inventor of quaternions.
Another common quaternion style places the scalar component
last. This style is often used in engineering applications.
1) If `r' is not a rotation matrix, the error SPICE(NOTAROTATION)
is signaled by a routine in the call tree of this routine.
2) If the input argument `r' is undefined, an error is signaled
by the Matlab error handling system.
3) If the input argument `r' is not of the expected type, or it
does not have the expected dimensions and size, an error is
signaled by the Mice interface.
None.
None.
MICE.REQ
ROTATION.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Mice Version 1.1.0, 24-AUG-2021 (EDW) (JDR)
Edited the header to comply with NAIF standard. Added
example's problem statement.
Added -Parameters, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections.
Eliminated use of "lasterror" in rethrow.
Removed reference to the function's corresponding CSPICE header from
-Required_Reading section.
-Mice Version 1.0.1, 09-MAR-2015 (EDW)
Edited -I/O section to conform to NAIF standard for Mice
documentation.
-Mice Version 1.0.0, 10-JAN-2006 (EDW)
matrix to quaternion
|