rt_quaternion - construct/clone a quaternion object[view code]

Calling Sequence

q = rt_quaternion(qq)

q = rt_quaternion(v, theta)

q = rt_quaternion(R)

q = rt_quaternion(T)

q = rt_quaternion(ELEMS)

Parameters

• qq : quaternion object. The quaternion object to copy.
• v : 3-element vector. A rotation axis in space.
• theta : scalar. The angular displacement for rotation about v, in radians.
• R : 3-by-3 matrix. A rotation matrix.
• T : 4-by-4 matrix. A homogeneous transform.
• ELEMS : 4-element row vector. This vector is formed by stacking the scalar component and the vector part of the unit quaternion as follows ELEMS = [s, vx, vy, vz], where
  • s : scalar. The scalar component of the quaternion.
  • vx : scalar. The X-component of the quaternion's vector part.
  • vy : scalar. The Y-component of the quaternion's vector part.
  • vz : scalar. The Z-component of the quaternion's vector part.
• q : quaternion object. The quaternion object created.

Description

This function is the constructor for a quaternion object. The quaternion object has type quat.

The first form returns a new object with the same value as its argument.

The second form initializes the quaternion to a rotation of theta radians about the vector v.

The third and the fourth forms set the quaternion to a rotation equivalent to the given rotation matrix R, or to the rotation submatrix of the given homogeneous transform T, respectively.

The fifth form sets the four quaternion elements directly.

All forms, except the last, return a unit quaternion, i.e. one whose magnitude is unity.

Since Scilab does not support the concept of public class, variables methods have been written to allow quaternion object parameters to be referenced (r) or assigned (a) as given by the following table:

Method	Operation	Returns	Type
quat.d	r	the vector formed by stacking of quaternion elements	4-element vector
quat.s	r	the scalar component of the quaternion	scalar
quat.v	r	the vector part of the quaternion	3-element vector
quat.t	r	the equivalent homogeneous transform matrix	4-by-4 matrix
quat.r	r	the equivalent orthonormal rotation matrix	3-by-3 matrix

Overloaded Operators and Functions

In Scilab variable display and operators may be defined for new objects using Scilab-coded functions. The following is a list of all overloaded operators for the new Scilab object, the quaternion:

q1 * q2: returns quaternion product or compounding

q * v: returns a quaternion vector product, that is the vector v (a 3-element vector) is rotated by the quaternion

q1 / q2: returns quaternion division, that is q1 * (q2)^(-1)

q / s: divide quaternion by scalar

q ^ (j): raise quaternion to integer power (j is an integer exponent). For j > 0 the result is obtained by repeated multiplication. For j < 0 the final result is inverted

In Scilab some basic primitive functions may be overloaded for new data types. The following is a list of all overloaded functions for the new Scilab object, the quaternion:

disp(q): displays the quaternion as one-line summary of its scalar component and vector part

double(q): returns the quaternion coefficients as a 4-element row vector

inv(q): returns the quaternion inverse

norm(q): returns the quaternion magnitude

rt_plot(q): displays a 3D plot showing the standard coordinate frame after rotation by q

rt_unit(q): returns the corresponding unit quaternion

Examples

   // set the four quaternion elements directly
   rt_quaternion([1, 1, 0, 0]),

   // a quaternion obtained from a rotation matrix
   rt_quaternion(rt_tr2rot(rt_rotx(1))),

   // The following example shows how to use the public class variables
   // methods
   T = rt_rotx(0.2),                    // A rotation of 0.2rads about the
                                        // X-axis (homogeneous transform)

   q1 = rt_quaternion(T),               // set q1 from a homog. transform

   q1.r,                                // get the equivalent orthonormal
                                        // rotation matrix

   q1.t,                                // returns T

   q1.s,                                // the scalar component
   q1.v,                                // the vector part

   q1.d,                                // the 4-element vector [q1.s, q1.v]

   q1.s = 1,                            // error! all methods can be
   q1.v = [1, 0, 0],                    // only referenced

   // Playing with overloaded operators and functions...
   q2 = rt_quaternion(rt_roty(0.3)),    // another quaternion

   q1*q2,                               // quaternion product

   q1*q1,                               // square quaternion
   q1^2,

   q1 * inv(q1),                        // invert quaternion
   q1/q1,

   q1/q2,                               // quaternion division
   q1 * q2^(-1),

   // Get the type of a quaternion object
   typeof(q1) == "quat",                // returns %T (true)
   typeof(q1) == "quaternion",          // returns %F (false)

  

Cautionary

At the moment vectors or arrays of quaternions are not supported. You can however use Scilab lists to hold a number of quaternions.

See Also

quaternion/rt_plot,  

Authors

original Matlab version by

Peter I. Corke CSIRO Manufacturing Science and Technology

Scilab implementation by

Matteo Morelli Interdepartmental Research Center "E. Piaggio", University of Pisa

Bibliography

Corke, P.I. "A Robotics Toolbox for MATLAB", IEEE Robotics and Automation Magazine, Volume 3(1), March 1996, pp. 24-32

K. Shoemake, "Animating rotation with quaternion curves", in Proceedings of ACM SIGGRAPH, (San Francisco), pp. 245-254, The Singer Company, Link Flight Simulator Division, 1985.