Main Page | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Class Members | File Members | Related Pages

vnl_quaternion< T > Class Template Reference

#include <vnl_quaternion.h>

Inheritance diagram for vnl_quaternion< T >:

vnl_vector_fixed< T, 4 > List of all members.

Detailed Description

template<class T>
class vnl_quaternion< T >

4-element vector that represents rotation in 3D.

vnl_quaternion is a 4-element vector with 1 real and 3 imaginary components: 

    q = r + (i*x + j*y + k*z)
    r = cos(theta/2)
    (x, y, z) = sin(theta/2) (kx, ky, kz)
where theta and k are respectively the angle and axis of rotation. 3D vectors can be thought of as imaginary quaternions, and so a quaternion is represented as a vnl_vector_fixed<T,4> with the imaginary part before the real part for 1-1 alignment.

Unit quaternions provide a more efficient representation for rotation, than the usual orthonormal matrix that has nine parameters and six orthonormal constraints. The unit quaternion has only one unit magnitude constraint. Composing rotations with quaternions results in fewer multiplications and less error. To insure valid rotation results, the nearest unit quaternion is computed, and this is much easier than finding the nearest orthonormal matrix. Transforming vectors with a quaternion requires more operations compared to multiplication with the equivalent orthonormal matrix.

See also:
vnl_vector_fixed and vnl_matrix_fixed for basic operations on vectors and matrices.

Envelope for envelope-letter scheme that avoids deep copy on return by value in arithmetic expressions like: q1 * q2 * q3 *...

Definition at line 60 of file vnl_quaternion.h.

Public Types

typedef vnl_vector_fixed<
T, n > 		self
typedef unsigned int size_type
typedef T element_type
 Type defs for iterators.
typedef T * iterator
 Type defs for iterators.
typedef Tconst * const_iterator
 Const iterator type.
typedef vnl_c_vector< T
>::abs_t 		abs_t

Public Member Functions

 vnl_quaternion ()
 Constructor for null quaternion.
 vnl_quaternion (T x, T y, T z, T r)
 Construct quaternion from components x,y,z,r.
 vnl_quaternion (T theta_X, T theta_Y, T theta_Z)
 Construct quaternion from Euler Angles,.
 vnl_quaternion (vnl_vector_fixed< T, 3 > const &axis, T angle)
 Construct quaternion from axis and angle of rotation.
 vnl_quaternion (vnl_matrix_fixed< T, 3, 3 > const &transform)
 Construct quaternion from from 3x3 row-major matrix.
 vnl_quaternion (vnl_vector_fixed< T, 3 > const &vec)
 Construct quaternion from a 3D vector.
 vnl_quaternion (vnl_vector_fixed< T, 4 > const &vec)
 Construct quaternion from a 4D vector.
 vnl_quaternion (vnl_quaternion< T > const &from)
 Copy constructor -- Creates a copy of from quaternion.
 ~vnl_quaternion ()
 Free internal array.
vnl_quaternion & operator= (vnl_quaternion< T > const &rhs)
 Overloads assignment operator to copy rhs quaternion into lhs quaternion.
T & x ()
 Imaginary component, parallel to axis of rotation.
T & y ()
 Imaginary component, parallel to axis of rotation.
T & z ()
 Imaginary component, parallel to axis of rotation.
T & r ()
 Real component.
T x () const
 Imaginary component, parallel to axis of rotation.
T y () const
 Imaginary component, parallel to axis of rotation.
T z () const
 Imaginary component, parallel to axis of rotation.
T r () const
 Real component.
T real () const
 Copies and returns the real part.
vnl_vector_fixed< T, 3 > imaginary () const
 Copies and returns the imaginary part.
vnl_vector_fixed< T, 3 > axis () const
 Axis of rotation.
T angle () const
 Angle of rotation.
vnl_matrix_fixed< T, 3, 3 > rotation_matrix_transpose () const
 3x3 rotation matrix.
vnl_matrix_fixed< T, 4, 4 > rotation_matrix_transpose_4 () const
 4x4 rotation matrix.
vnl_quaternion< T > conjugate () const
 Same real, opposite img part.
vnl_quaternion< T > inverse () const
 Inverse for nonzero quat.
vnl_quaternion< T > operator * (vnl_quaternion< T > const &) const
 Returns the product of two quaternions.
vnl_vector_fixed< T, 3 > rotate (vnl_vector_fixed< T, 3 > const &) const
 Rotate 3D v.
vnl_vector_fixed< T, 3 > rotation_euler_angles () const
 Rotation representation in Euler angles.
 vnl_vector_fixed ()
 Construct an uninitialized n-vector.
 vnl_vector_fixed (const vnl_vector_fixed< T, n > &rhs)
 Copy constructor.
 vnl_vector_fixed (const vnl_vector< T > &rhs)
 Construct a fixed-n-vector copy of rhs.
 vnl_vector_fixed (const T &v)
 Constructs n-vector with all elements initialised to v.
 vnl_vector_fixed (const T *datablck)
 Construct an fixed-n-vector initialized from datablck.
 vnl_vector_fixed (const T &x0, const T &x1)
 Convenience constructor for 2-D vectors.
 vnl_vector_fixed (const T &x0, const T &x1, const T &x2)
 Convenience constructor for 3-D vectors.
 vnl_vector_fixed (const T &x0, const T &x1, const T &x2, const T &x3)
 Convenience constructor for 4-D vectors.
unsigned size () const
 Length of the vector.
void put (unsigned int i, Tconst &v)
 Put value at given position in vector.
T get (unsigned int i) const
 Get value at element i.
void fill (Tconst &v)
 Set all values to v.
void copy_in (Tconst *ptr)
 Sets elements to ptr[i].
void copy_out (T *ptr) const
 Copy elements to ptr[i].
void set (Tconst *ptr)
 Sets elements to ptr[i].
T & operator() (unsigned int i)
 Return reference to the element at specified index.
Tconst & operator() (unsigned int i) const
 Return reference to the element at specified index.
T & operator[] (unsigned int i)
 Return the i-th element.
const T & operator[] (unsigned int i) const
 Return the i-th element.
Tconst * data_block () const
 Access the contiguous block storing the elements in the vector.
T * data_block ()
 Access the contiguous block storing the elements in the vector.
vnl_vector_ref< T > as_ref ()
 Explicit conversion to a vnl_vector_ref.
const vnl_vector_ref< T > as_ref () const
 Explicit conversion to a vnl_vector_ref.
 operator const vnl_vector_ref () const
 Cheap conversion to vnl_vector_ref.
iterator begin ()
 Iterator pointing to start of data.
const_iterator begin () const
 Iterator pointing to start of data.
iterator end ()
 Iterator pointing to element beyond end of data.
const_iterator end () const
 Iterator pointing to element beyond end of data.
vnl_vector_fixed< T, n > apply (T(*f)(T))
 Apply f to each element.
vnl_vector_fixed< T, n > apply (T(*f)(const T &))
 Apply f to each element.
vnl_vector_fixed< T, n > & operator+= (Ts)
vnl_vector_fixed< T, n > & operator+= (const vnl_vector_fixed< T, n > &v)
vnl_vector_fixed< T, n > & operator+= (const vnl_vector< T > &v)
vnl_vector_fixed< T, n > & operator-= (Ts)
vnl_vector_fixed< T, n > & operator-= (const vnl_vector_fixed< T, n > &v)
vnl_vector_fixed< T, n > & operator-= (const vnl_vector< T > &v)
vnl_vector_fixed< T, n > & operator *= (Ts)
vnl_vector_fixed< T, n > & operator/= (Ts)
vnl_vector_fixed< T, n > operator- () const
vnl_vector< T > extract (unsigned int len, unsigned int start=0) const
 Returns a subvector specified by the start index and length. O(n).
vnl_vector< T > as_vector () const
 Convert to a vnl_vector.
vnl_vector_fixed & update (vnl_vector< T > const &, unsigned int start=0)
 Replaces elements with index beginning at start, by values of v. O(n).
abs_t squared_magnitude () const
 Return sum of squares of elements.
abs_t magnitude () const
 Return magnitude (length) of vector.
abs_t one_norm () const
 Return sum of absolute values of the elements.
abs_t two_norm () const
 Return sqrt of sum of squares of values of elements.
abs_t inf_norm () const
 Return largest absolute element value.
vnl_vector_fixed< T, n > & normalize ()
 Normalise by dividing through by the magnitude.
abs_t rms () const
 Root Mean Squares of values.
T min_value () const
 Smallest value.
T max_value () const
 Largest value.
T mean () const
 Mean of values in vector.
T sum () const
 Sum of values in a vector.
void flip ()
 Reverse the order of the elements.
void assert_size (unsigned sz) const
 Check that size()==sz if not, abort();.
void assert_finite () const
 Check that this is finite if not, abort();.
bool is_finite () const
 Return true if its finite.
bool is_zero () const
 Return true iff all the entries are zero.
bool empty () const
 Return true iff the size is zero.
bool operator_eq (vnl_vector_fixed< T, n > const &v) const
 Return true if *this == v.
bool operator_eq (vnl_vector< T > const &v) const
 Return true if *this == v.
bool read_ascii (vcl_istream &s)
 Read from text stream.
void print (vcl_ostream &s) const
 Display the vector.

Static Public Member Functions

static void add (const T *a, const T *b, T *r)
static void add (const T *a, Tb, T *r)
static void sub (const T *a, const T *b, T *r)
static void sub (const T *a, Tb, T *r)
static void sub (Ta, const T *b, T *r)
static void mul (const T *a, const T *b, T *r)
static void mul (const T *a, Tb, T *r)
static void div (const T *a, const T *b, T *r)
static void div (const T *a, Tb, T *r)

Protected Attributes

T data_ [n]

Private Types

typedef vnl_vector_fixed<
T, 4 > 		Base

Related Functions

(Note that these are not member functions.)

vcl_ostream & operator<< (vcl_ostream &os, vnl_quaternion< T > const &q)
 operator<<.

Member Typedef Documentation

typedef vnl_c_vector<T >::abs_t vnl_vector_fixed< T , n >::abs_t [inherited]
 

Definition at line 344 of file vnl_vector_fixed.h.

template<class T>
typedef vnl_vector_fixed<T,4> vnl_quaternion< T >::Base [private]
 

Definition at line 62 of file vnl_quaternion.h.

typedef T const* vnl_vector_fixed< T , n >::const_iterator [inherited]
 

Const iterator type.

Definition at line 279 of file vnl_vector_fixed.h.

typedef T vnl_vector_fixed< T , n >::element_type [inherited]
 

Type defs for iterators.

Definition at line 269 of file vnl_vector_fixed.h.

typedef T * vnl_vector_fixed< T , n >::iterator [inherited]
 

Type defs for iterators.

Definition at line 271 of file vnl_vector_fixed.h.

typedef vnl_vector_fixed<T ,n> vnl_vector_fixed< T , n >::self [inherited]
 

Definition at line 84 of file vnl_vector_fixed.h.

typedef unsigned int vnl_vector_fixed< T , n >::size_type [inherited]
 

Definition at line 85 of file vnl_vector_fixed.h.

Constructor & Destructor Documentation

template<class T>
vnl_quaternion< T >::vnl_quaternion (   )  [inline]
 

Constructor for null quaternion.

Definition at line 66 of file vnl_quaternion.h.

template<class T>
vnl_quaternion< T >::vnl_quaternion (  T  x,
T  y,
T  z,
T  r
) 
 

Construct quaternion from components x,y,z,r.

x, y, z denote the imaginary part, which are the coordinates of the rotation axis multiplied by the sine of half the angle of rotation. r denotes the real part, or the cosine of half the angle of rotation. Default is to create a null quaternion, corresponding to a null rotation or an identity transform, which has undefined rotation axis.

Definition at line 52 of file vnl_quaternion.txx.

template<class T>
vnl_quaternion< T >::vnl_quaternion (  T  theta_X,
T  theta_Y,
T  theta_Z
) 
 

Construct quaternion from Euler Angles,.

That is a rotation about the X axis, followed by Y, followed by the Z axis, using a fixed reference frame.

Definition at line 145 of file vnl_quaternion.txx.

template<class T>
vnl_quaternion< T >::vnl_quaternion (  vnl_vector_fixed< T, 3 > const &  axis,
T  angle
) 
 

Construct quaternion from axis and angle of rotation.

Note:
If you specify an angle in [0, 2pi], then methods angle() and axis() will return the same values. However, if you specify an angle in [-2pi, 0], then methods angle() and axis() will return values with opposite signs.
See also:
vnl_quaternion::angle()

vnl_quaternion::axis()

Definition at line 63 of file vnl_quaternion.txx.

template<class T>
vnl_quaternion< T >::vnl_quaternion (  vnl_matrix_fixed< T, 3, 3 > const &  rot  )  [explicit]
 

Construct quaternion from from 3x3 row-major matrix.

Its orthonormal basis vectors are row-wise. WARNING: Takes the transpose of the rotation matrix...

Definition at line 100 of file vnl_quaternion.txx.

template<class T>
vnl_quaternion< T >::vnl_quaternion (  vnl_vector_fixed< T, 3 > const &  vec  ) 
 

Construct quaternion from a 3D vector.

3D vector is converted into an imaginary quaternion with same (x, y, z) components.

Definition at line 77 of file vnl_quaternion.txx.

template<class T>
vnl_quaternion< T >::vnl_quaternion (  vnl_vector_fixed< T, 4 > const &  vec  ) 
 

Construct quaternion from a 4D vector.

4D vector is assumed to be a 4-element quaternion, to provide casting between vector and quaternion

Definition at line 89 of file vnl_quaternion.txx.

template<class T>
vnl_quaternion< T >::vnl_quaternion (  vnl_quaternion< T > const &  from  )  [inline]
 

Copy constructor -- Creates a copy of from quaternion.

Definition at line 93 of file vnl_quaternion.h.

template<class T>
vnl_quaternion< T >::~vnl_quaternion (   )  [inline]
 

Free internal array.

Definition at line 96 of file vnl_quaternion.h.

Member Function Documentation

static void vnl_vector_fixed< T , n >::add (  const T *  a,
T   b,
T *  r
)  [inline, static, inherited]
 

Definition at line 445 of file vnl_vector_fixed.h.

static void vnl_vector_fixed< T , n >::add (  const T *  a,
const T *  b,
T *  r
)  [inline, static, inherited]
 

Definition at line 439 of file vnl_vector_fixed.h.

template<class T>
T vnl_quaternion< T >::angle (   )  const
 

Angle of rotation.

Note:
Returned angle lies in [0, 2*pi]

Definition at line 184 of file vnl_quaternion.txx.

vnl_vector_fixed<T ,n> vnl_vector_fixed< T , n >::apply (  T (*)(const T &)  f  )  [inherited]
 

Apply f to each element.

Returns a new vector with the result.

vnl_vector_fixed<T ,n> vnl_vector_fixed< T , n >::apply (  T (*)(T )  f  )  [inherited]
 

Apply f to each element.

Returns a new vector with the result.

const vnl_vector_ref<T > vnl_vector_fixed< T , n >::as_ref (   )  const [inline, inherited]
 

Explicit conversion to a vnl_vector_ref.

This is a cheap conversion for those functions that have an interface for vnl_vector but not for vnl_vector_fixed. There is also a conversion operator that should work most of the time.

See also:
vnl_vector_ref::non_const

Definition at line 258 of file vnl_vector_fixed.h.

vnl_vector_ref<T > vnl_vector_fixed< T , n >::as_ref (   )  [inline, inherited]
 

Explicit conversion to a vnl_vector_ref.

This is a cheap conversion for those functions that have an interface for vnl_vector but not for vnl_vector_fixed. There is also a conversion operator that should work most of the time.

See also:
vnl_vector_ref::non_const

Definition at line 251 of file vnl_vector_fixed.h.

vnl_vector<T > vnl_vector_fixed< T , n >::as_vector (   )  const [inline, inherited]
 

Convert to a vnl_vector.

Definition at line 338 of file vnl_vector_fixed.h.

void vnl_vector_fixed< T , n >::assert_finite (   )  const [inline, inherited]
 

Check that this is finite if not, abort();.

This function does or tests nothing if NDEBUG is defined

Definition at line 392 of file vnl_vector_fixed.h.

void vnl_vector_fixed< T , n >::assert_size (  unsigned  sz  )  const [inline, inherited]
 

Check that size()==sz if not, abort();.

This function does or tests nothing if NDEBUG is defined

Definition at line 388 of file vnl_vector_fixed.h.

template<class T>
vnl_vector_fixed< T, 3 > vnl_quaternion< T >::axis (   )  const
 

Axis of rotation.

Note:
Axis not well defined for theta==0. In such a case (or if provided axis==(0,0,0)), this function returns (0,0,1).

Definition at line 193 of file vnl_quaternion.txx.

const_iterator vnl_vector_fixed< T , n >::begin (   )  const [inline, inherited]
 

Iterator pointing to start of data.

Definition at line 281 of file vnl_vector_fixed.h.

iterator vnl_vector_fixed< T , n >::begin (   )  [inline, inherited]
 

Iterator pointing to start of data.

Definition at line 273 of file vnl_vector_fixed.h.

template<class T>
vnl_quaternion< T > vnl_quaternion< T >::conjugate (   )  const
 

Same real, opposite img part.

Definition at line 245 of file vnl_quaternion.txx.

void vnl_vector_fixed< T , n >::copy_in (  T const *  ptr  )  [inline, inherited]
 

Sets elements to ptr[i].

Note: ptr[i] must be valid for i=0..size()-1

Definition at line 183 of file vnl_vector_fixed.h.

void vnl_vector_fixed< T , n >::copy_out (  T *  ptr  )  const [inline, inherited]
 

Copy elements to ptr[i].

Note: ptr[i] must be valid for i=0..size()-1

Definition at line 191 of file vnl_vector_fixed.h.

T * vnl_vector_fixed< T , n >::data_block (   )  [inline, inherited]
 

Access the contiguous block storing the elements in the vector.

O(1). data_block()[0] is the first element of the vector

Definition at line 236 of file vnl_vector_fixed.h.

T const* vnl_vector_fixed< T , n >::data_block (   )  const [inline, inherited]
 

Access the contiguous block storing the elements in the vector.

O(1). data_block()[0] is the first element of the vector

Definition at line 231 of file vnl_vector_fixed.h.

static void vnl_vector_fixed< T , n >::div (  const T *  a,
T   b,
T *  r
)  [inline, static, inherited]
 

Definition at line 487 of file vnl_vector_fixed.h.

static void vnl_vector_fixed< T , n >::div (  const T *  a,
const T *  b,
T *  r
)  [inline, static, inherited]
 

Definition at line 481 of file vnl_vector_fixed.h.

bool vnl_vector_fixed< T , n >::empty (   )  const [inline, inherited]
 

Return true iff the size is zero.

Definition at line 406 of file vnl_vector_fixed.h.

const_iterator vnl_vector_fixed< T , n >::end (   )  const [inline, inherited]
 

Iterator pointing to element beyond end of data.

Definition at line 283 of file vnl_vector_fixed.h.

iterator vnl_vector_fixed< T , n >::end (   )  [inline, inherited]
 

Iterator pointing to element beyond end of data.

Definition at line 276 of file vnl_vector_fixed.h.

vnl_vector<T > vnl_vector_fixed< T , n >::extract (  unsigned int  len,
unsigned int  start = 0
)  const [inherited]
 

Returns a subvector specified by the start index and length. O(n).

void vnl_vector_fixed< T , n >::fill (  T const &  v  )  [inline, inherited]
 

Set all values to v.

Definition at line 175 of file vnl_vector_fixed.h.

void vnl_vector_fixed< T , n >::flip (   )  [inherited]
 

Reverse the order of the elements.

Element i swaps with element size()-1-i

T vnl_vector_fixed< T , n >::get (  unsigned int  i  )  const [inline, inherited]
 

Get value at element i.

Definition at line 172 of file vnl_vector_fixed.h.

template<class T>
vnl_vector_fixed<T,3> vnl_quaternion< T >::imaginary (   )  const [inline]
 

Copies and returns the imaginary part.

Definition at line 131 of file vnl_quaternion.h.

abs_t vnl_vector_fixed< T , n >::inf_norm (   )  const [inline, inherited]
 

Return largest absolute element value.

Definition at line 359 of file vnl_vector_fixed.h.

template<class T>
vnl_quaternion< T > vnl_quaternion< T >::inverse (   )  const
 

Inverse for nonzero quat.

For unit quaternion representing rotation, the inverse is the same as the conjugate.

Definition at line 255 of file vnl_quaternion.txx.

bool vnl_vector_fixed< T , n >::is_finite (   )  const [inherited]
 

Return true if its finite.

bool vnl_vector_fixed< T , n >::is_zero (   )  const [inherited]
 

Return true iff all the entries are zero.

abs_t vnl_vector_fixed< T , n >::magnitude (   )  const [inline, inherited]
 

Return magnitude (length) of vector.

Definition at line 350 of file vnl_vector_fixed.h.

T vnl_vector_fixed< T , n >::max_value (   )  const [inline, inherited]
 

Largest value.

Definition at line 374 of file vnl_vector_fixed.h.

T vnl_vector_fixed< T , n >::mean (   )  const [inline, inherited]
 

Mean of values in vector.

Definition at line 377 of file vnl_vector_fixed.h.

T vnl_vector_fixed< T , n >::min_value (   )  const [inline, inherited]
 

Smallest value.

Definition at line 371 of file vnl_vector_fixed.h.

static void vnl_vector_fixed< T , n >::mul (  const T *  a,
T   b,
T *  r
)  [inline, static, inherited]
 

Definition at line 475 of file vnl_vector_fixed.h.

static void vnl_vector_fixed< T , n >::mul (  const T *  a,
const T *  b,
T *  r
)  [inline, static, inherited]
 

Definition at line 469 of file vnl_vector_fixed.h.

vnl_vector_fixed<T ,n>& vnl_vector_fixed< T , n >::normalize (   )  [inline, inherited]
 

Normalise by dividing through by the magnitude.

Definition at line 362 of file vnl_vector_fixed.h.

abs_t vnl_vector_fixed< T , n >::one_norm (   )  const [inline, inherited]
 

Return sum of absolute values of the elements.

Definition at line 353 of file vnl_vector_fixed.h.

template<class T>
vnl_quaternion< T > vnl_quaternion< T >::operator * (  vnl_quaternion< T > const &  rhs  )  const
 

Returns the product of two quaternions.

Multiplication of two quaternions is not symmetric and has fewer operations than multiplication of orthonormal matrices. If object is rotated by r1, then by r2, then the composed rotation (r2 o r1) is represented by the quaternion (q2 * q1), or by the matrix (m1 * m2). Note that matrix composition is reversed because matrices and vectors are represented row-wise.

Definition at line 272 of file vnl_quaternion.txx.

vnl_vector_fixed<T ,n>& vnl_vector_fixed< T , n >::operator *= (  T   s  )  [inline, inherited]
 

Definition at line 301 of file vnl_vector_fixed.h.

vnl_vector_fixed< T , n >::operator const vnl_vector_ref (   )  const [inline, inherited]
 

Cheap conversion to vnl_vector_ref.

Sometimes, such as with templated functions, the compiler cannot use this user-defined conversion. For those cases, use the explicit as_ref() method instead.

Definition at line 264 of file vnl_vector_fixed.h.

T const& vnl_vector_fixed< T , n >::operator() (  unsigned int  i  )  const [inline, inherited]
 

Return reference to the element at specified index.

There are assert style boundary checks - define NDEBUG to turn them off.

Definition at line 214 of file vnl_vector_fixed.h.

T & vnl_vector_fixed< T , n >::operator() (  unsigned int  i  )  [inline, inherited]
 

Return reference to the element at specified index.

There are assert style boundary checks - define NDEBUG to turn them off.

Definition at line 204 of file vnl_vector_fixed.h.

vnl_vector_fixed<T ,n>& vnl_vector_fixed< T , n >::operator+= (  const vnl_vector< T > &  v  )  [inline, inherited]
 

Definition at line 313 of file vnl_vector_fixed.h.

vnl_vector_fixed<T ,n>& vnl_vector_fixed< T , n >::operator+= (  const vnl_vector_fixed< T , n > &  v  )  [inline, inherited]
 

Definition at line 307 of file vnl_vector_fixed.h