% Quaternion Toolbox
% Version 1.0             14-December-2006
% ---------------------------------------------------------------------
% Copyright © 2005-6  Stephen J. Sangwine         (S.Sangwine@IEEE.org)
%                     Nicolas Le Bihan   (nicolas.le-bihan@lis.inpg.fr)
%                     See the file Copyright.m for further details.
% ---------------------------------------------------------------------
%
% quaternion is a Matlab class library designed to extend Matlab in as
% natural a way as possible to handle quaternions. Many standard Matlab
% features have been implemented, including standard operators such as
% the arithmetic operators, matrix and elementwise products, indexing
% and indexed assignment using the colon operator, concatenation, end
% indexing, transpose and conjugate transpose, raising to a power, etc.
%
% A major objective has been to make it possible to write code that can
% work unchanged for real, complex, quaternion, and even complexified
% quaternion arrays, and for this reason standard Matlab functions have
% been overloaded for quaternion arrays.
%
% A quaternion object, as implemented by this class, has a private
% implementation based on a structure array storing the four components
% of the quaternion. As with any standard Matlab type, a quaternion is by
% default a matrix. A single quaternion is simply a matrix of one element.
%
% Quaternions may be pure or full. Pure quaternions have no scalar part
% and operations that attempt to access the scalar part will result in an
% error. The quaternions in a vector or matrix are either all pure or all
% full -- it is not possible to construct a vector or matrix with a mix
% of the two. A full quaternion with a scalar part which is zero differs
% from a pure quaternion, which has no scalar part.
%
% Quaternion matrices can be constructed either by using a constructor
% function, like this:
%
% q = quaternion(eye(5,5), zeros(5,5), randn(5,5), ones(5,5))
%
% or by using the three quaternion operators, named q1, q2 and q3, (these
% three operators are also available under the names qi, qj and qk) like this:
%
% q = eye(5,5) + zeros(5,5) * q1 + randn(5,5) * q2 + ones(5,5) * q3
%
% The components of the quaternion so constructed will have a type determined
% by the type supplied for the components (e.g. double, uint8, int16 ....).
% The components may be REAL or COMPLEX. A complex quaternion can also be
% constructed like this:
%
% q = complex(quaternion(1,2,3,4), 3)
%
% or using the Matlab value i:
%
% q = quaternion(1,2,3,4) + quaternion(5,6,7,8) .* i
%
% The components of a quaternion can be extracted using the five functions:
%
%   scalar         - Scalar part of a quaternion.
%   vector, v      - Vector part of a quaternion (synonyms).
%   s, x, y, z     - Components of a quaternion.
%
%   real           - Real part of a (complex) quaternion.
%   imag           - Imaginary part of a (complex) quaternion.
%   complex        - Construct a complex quaternion from real quaternions.
%   quaternion     - Construct a quaternion from real or complex values.
%
% Other functions implemented are:
%
%   abs            - Modulus of a quaternion.
%   conj           - Conjugate (quaternion, complex or total).
%   unit           - Normalise a quaternion.
%   sign           - Equivalent to unit, cf Matlab sign.m.
%   inv            - Matrix and quaternion inverse.
%   axis           - Axis of a quaternion.
%   angle          - Angle or argument of a quaternion.
%
%   ceil, floor    - Round elements of quaternion towards plus or minus 
%   fix, round       infinity, zero, or nearest integer.
%
%   display        - Display array (does not show values)
%   disp           - Display without array name.
%   displayall     - Display components of quaternion.
%   show           - Shorter synonym for displayall.
%   char           - Convert quaternion to string.
%   fprintf        - Output quaternions to file.
%   write          - Write a quaternion array   to a text file.
%   read           - Read  a quaternion array from a text file.
%
%   convert        - Convert components of quaternion to a different type.
%
%   dot            - Dot product.
%   cross          - Vector product.
%
%   exp            - Exponential function.
%   log            - Natural logarithm.
%
%   sqrt           - Square root.
%
%   sin, cos, tan  - Trigonometric functions.
%   asin, acos,
%         atan     - Inverse trigonometric functions.
%   sinh, cosh,
%         tanh     - Hyperbolic functions.
%   asinh, acosh,
%          atanh   - Inverse hyperbolic functions.
%
%   diag           - Extract or construct a diagonal.
%   triu/tril      - Extract upper or lower triangular.
%   norm           - Vector and matrix norms.
%   sum            - Sum elements or columns.
%   mean           - Mean of elements or columns.
%
%   ispure         - Test whether a quaternion (array) is pure.
%   isempty        - Test whether a quaternion (array) is empty.
%   isfinite       - Test whether a quaternion (array) is finite.
%   isinf          - Test whether a quaternion (array) is infinite.
%   isnan          - Test whether a quaternion (array) is NaN.
%   isreal         - Test whether a quaternion (array) is real.
%   ishermitian    - Test whether a quaternion (array) is Hermitian.
%   isunitary      - Test whether a quaternion (array) is unitary.
%
%   length         - Length of a quaternion vector.
%   size           - Size of a quaternion array.
%   numel          - Number of elements in a quaternion array.
%   repmat         - Replicate and tile a quaternion array.
%   cat            - Concatenate arrays.
%
%   det            - Determinant.
%   svd            - Singular value decomposition.
%   eig            - Eigenvalue decomposition.
%
%   adjoint        - The complex adjoint of a quaternion array.
%   unadjoint      - Construct a quaternion array from an adjoint array.
%
%   conv, conv2    - Convolution.
%
%   fft            - One dimensional (default) quaternion Fourier transform.
%   fft2           - Two dimensional (default) quaternion Fourier transform.
%   qfft           - One dimensional left or right one-dimensional QFFT.
%   qdft           - One dimensional left or right one-dimensional QDFT.
%   qfft2          - Two dimensional left or right two-dimensional QFFT.
%   qdft2          - Two dimensional left or right two-dimensional QDFT.
%   fftshift       - Quaternion overloading of the standard Matlab function.
%   .............  - All of the above have inverses, prefixed with 'i'.
%
% The following builtin Matlab functions also work for quaternion arrays:
%
%   flipud, fliplr, rot90, ndims, trace, isequal, isvector
%
% The following Matlab functions also work for quaternion arrays:
%
%   cov, princomp, rank, var (there may be others)
%
% The following function is not yet usable: reshape.
%
% There are some auxiliary functions which are used to compute some of the
% more elaborate functions above, such as svd, eig and qdft. These are:
%
% change_basis, orthonormal_basis, orthogonal.
% householder_vector, householder_matrix, bidiagonalize, tridiagonalize.
%
% Some test code is provided in the directory 'test'. To run it set the
% working directory to 'test' and type 'test'. This runs all the test
% code.
%
% For more information, use help.
