Quaternion Constructors
***********************

quaternion
==========

 -- Function File: Q = quaternion (W)
 -- Function File: Q = quaternion (X, Y, Z)
 -- Function File: Q = quaternion (W, X, Y, Z)
     Constructor for quaternions - create or convert to quaternion.

           q = w + x*i + y*j + z*k

     Arguments W, X, Y and Z can be scalars, matrices or n-dimensional arrays, but they must be real-valued and of equal size. If scalar part W or components X, Y and Z of the vector part are not specified, zero matrices of appropriate size are assumed.

     Example

           octave:1> q = quaternion (2)
           q = 2 + 0i + 0j + 0k

           octave:2> q = quaternion (3, 4, 5)
           q = 0 + 3i + 4j + 5k

           octave:3> q = quaternion (2, 3, 4, 5)
           q = 2 + 3i + 4j + 5k

           octave:4> w = [2, 6, 10; 14, 18, 22];
           octave:5> x = [3, 7, 11; 15, 19, 23];
           octave:6> y = [4, 8, 12; 16, 20, 24];
           octave:7> z = [5, 9, 13; 17, 21, 25];
           octave:8> q = quaternion (w, x, y, z)
           q.w =
               2    6   10
              14   18   22

           q.x =
               3    7   11
              15   19   23

           q.y =
               4    8   12
              16   20   24

           q.z =
               5    9   13
              17   21   25

           octave:9>

qi
==

 -- Function File: qi
     Create x-component of a quaternion's vector part.

           q = w + x*qi + y*qj + z*qk

     Example

           octave:1> q1 = quaternion (1, 2, 3, 4)
           q1 = 1 + 2i + 3j + 4k
           octave:2> q2 = 1 + 2*qi + 3*qj + 4*qk
           q2 = 1 + 2i + 3j + 4k
           octave:3>

qj
==

 -- Function File: qj
     Create y-component of a quaternion's vector part.

           q = w + x*qi + y*qj + z*qk

     Example

           octave:1> q1 = quaternion (1, 2, 3, 4)
           q1 = 1 + 2i + 3j + 4k
           octave:2> q2 = 1 + 2*qi + 3*qj + 4*qk
           q2 = 1 + 2i + 3j + 4k
           octave:3>

qk
==

 -- Function File: qk
     Create z-component of a quaternion's vector part.

           q = w + x*qi + y*qj + z*qk

     Example

           octave:1> q1 = quaternion (1, 2, 3, 4)
           q1 = 1 + 2i + 3j + 4k
           octave:2> q2 = 1 + 2*qi + 3*qj + 4*qk
           q2 = 1 + 2i + 3j + 4k
           octave:3>

Conversions
***********

q2rot
=====

 -- Function File: [AXIS, ANGLE] = q2rot (Q)
 -- Function File: [AXIS, ANGLE, QN] = q2rot (Q)
     Extract vector/angle form of a unit quaternion Q.

     Inputs

     q
          Unit quaternion describing the rotation. Quaternion Q can be a scalar or an array. In the latter case, Q is reshaped to a row vector and the return values AXIS and ANGLE are concatenated horizontally, accordingly.

     Outputs

     axis
          Eigenaxis as a 3-d unit vector [x; y; z]. If input argument Q is a quaternion array, AXIS becomes a matrix where AXIS(:,I) corresponds to Q(I).

     angle
          Rotation angle in radians.  The positive direction is determined by the right-hand rule applied to AXIS. The angle lies in the interval [0, 2*pi]. If input argument Q is a quaternion array, ANGLE becomes a row vector where ANGLE(I) corresponds to Q(I).

     qn
          Optional output of diagnostic nature. qn = reshape (q, 1, []) or, if needed, qn = reshape (unit (q), 1, []).

     Example

           octave:1> axis = [0; 0; 1]
           axis =

              0
              0
              1

           octave:2> angle = pi/4
           angle =  0.78540
           octave:3> q = rot2q (axis, angle)
           q = 0.9239 + 0i + 0j + 0.3827k
           octave:4> [vv, th] = q2rot (q)
           vv =

              0
              0
              1

           th =  0.78540
           octave:5> theta = th*180/pi
           theta =  45.000
           octave:6>

rot2q
=====

 -- Function File: Q = rot2q (AXIS, ANGLE)
     Create unit quaternion Q which describes a rotation of ANGLE radians about the vector AXIS.  This function uses the active convention where the vector AXIS is rotated by ANGLE radians.  If the coordinate frame should be rotated by ANGLE radians, also called the passive convention, this is equivalent to rotating the AXIS by -ANGLE radians.

     Inputs

     axis
          Vector [x, y, z] or [x; y; z] describing the axis of rotation.

     angle
          Rotation angle in radians.  The positive direction is determined by the right-hand rule applied to AXIS. If ANGLE is a real-valued array, a quaternion array Q of the same size is returned.

     Outputs

     q
          Unit quaternion describing the rotation. If ANGLE is an array, Q(I,J) corresponds to the rotation angle ANGLE(I,J).

     Example

           octave:1> axis = [0, 0, 1];
           octave:2> angle = pi/4;
           octave:3> q = rot2q (axis, angle)
           q = 0.9239 + 0i + 0j + 0.3827k
           octave:4> v = quaternion (1, 1, 0)
           v = 0 + 1i + 1j + 0k
           octave:5> vr = q * v * conj (q)
           vr = 0 + 0i + 1.414j + 0k
           octave:6>

rotm2q
======

 -- Function File: Q = rotm2q (R)
     Convert 3x3 rotation matrix R to unit quaternion Q.

Quaternion Methods
******************

@quaternion/abs
===============

 -- Function File: QABS = abs (Q)
     Modulus of a quaternion.

           q = w + x*i + y*j + z*k
           abs (q) = sqrt (w.^2 + x.^2 + y.^2 + z.^2)

@quaternion/arg
===============

 -- Function File: THETA = arg (Q)
     Compute the argument or phase of quaternion Q in radians. THETA is defined as atan2 (sqrt (q.x.^2 + q.y.^2 + q.z.^2), q.w). The argument THETA lies in the range (0, pi).

@quaternion/blkdiag
===================

 -- Function File: Q = blkdiag (Q1, Q2, ...)
     Block-diagonal concatenation of quaternions.

@quaternion/cast
================

 -- Function File: Q = cast (Q, 'TYPE')
     Convert the components of quaternion Q to data type TYPE. Valid types are int8, uint8, int16, uint16, int32, uint32, int64, uint64, double, single and logical.

@quaternion/cat
===============

 -- Function File: Q = cat (DIM, Q1, Q2, ...)
     Concatenation of quaternions along dimension DIM.

@quaternion/ceil
================

 -- Function File: Q = ceil (Q)
     Round quaternion Q towards positive infinity.

@quaternion/columns
===================

 -- Function File: NC = columns (Q)
     Return number of columns NC of quaternion array Q.

@quaternion/conj
================

 -- Function File: Q = conj (Q)
     Return conjugate of a quaternion.

           q = w + x*i + y*j + z*k
           conj (q) = w - x*i - y*j - z*k

@quaternion/cumsum
==================

 -- Function File: Q = cumsum (Q)
 -- Function File: Q = cumsum (Q, DIM)
 -- Function File: Q = cumsum (..., 'NATIVE')
 -- Function File: Q = cumsum (..., 'DOUBLE')
 -- Function File: Q = cumsum (..., 'EXTRA')
     Cumulative sum of elements along dimension DIM.  If DIM is omitted, it defaults to the first non-singleton dimension. See help cumsum for more information.

@quaternion/diag
================

 -- Function File: Q = diag (V)
 -- Function File: Q = diag (V, K)
     Return a diagonal quaternion matrix with quaternion vector V on diagonal K. The second argument is optional. If it is positive, the vector is placed on the K-th super-diagonal. If it is negative, it is placed on the -K-th sub-diagonal. The default value of K is 0, and the vector is placed on the main diagonal. Given a matrix argument, instead of a vector, diag extracts the K-th diagonal of the matrix.

@quaternion/diff
================

 -- Function File: QDOT = diff (Q, OMEGA)
     Derivative of a quaternion.

     Let Q be a quaternion to transform a vector from a fixed frame to a rotating frame.  If the rotating frame is rotating about the [x, y, z] axes at angular rates [wx, wy, wz], then the derivative of Q is given by

           Q' = diff(Q, omega)

     If the passive convention is used (rotate the frame, not the vector), then

           Q' = diff(Q,-omega)

@quaternion/exp
===============

 -- Function File: QEXP = exp (Q)
     Exponential of a quaternion.

@quaternion/fix
===============

 -- Function File: Q = fix (Q)
     Round quaternion Q towards zero.

@quaternion/floor
=================

 -- Function File: Q = floor (Q)
     Round quaternion Q towards negative infinity.

@quaternion/full
================

 -- Function File: FQ = full (SQ)
     Return a full storage quaternion representation FQ from sparse or diagonal quaternion SQ.

@quaternion/get
===============

 -- Function File: get (Q)
 -- Function File: VALUE = get (Q, "KEY")
 -- Function File: [VAL1, VAL2, ...] = get (Q, "KEY1", "KEY2", ...)
     Access key values of quaternion objects.

     Keys

     w
          Return scalar part W of quaternion Q as a built-in type.

     x, y, z
          Return component X, Y or Z of the vector part of quaternion Q as a built-in type.

     s
          Return scalar part of quaternion Q.  The vector part of Q is set to zero.

     v
          Return vector part of quaternion Q.  The scalar part of Q is set to zero.

@quaternion/inv
===============

 -- Function File: QINV = inv (Q)
     Return inverse of a quaternion.

@quaternion/isempty
===================

 -- Function File: BOOL = isempty (Q)
     Return true if quaternion Q is empty and false otherwise.

@quaternion/isfinite
====================

 -- Function File: BOOL = isfinite (Q)
     Return a logical array which is true where the elements of Q are finite values and false where they are not.

@quaternion/isinf
=================

 -- Function File: BOOL = isinf (Q)
     Return a logical array which is true where the elements of Q are infinite and false where they are not.

@quaternion/isnan
=================

 -- Function File: BOOL = isnan (Q)
     Return a logical array which is true where the elements of Q are NaN values and false where they are not.

@quaternion/ispure
==================

 -- Function File: BOOL = ispure (Q)
     Return true if scalar part of quaternion is zero, otherwise return false.

@quaternion/isreal
==================

 -- Function File: BOOL = isreal (Q)
     Return true if the vector part of quaternion Q is zero and false otherwise.

@quaternion/length
==================

 -- Function File: L = length (Q)
     Return the "length" L of the quaternion array Q. For quaternion matrices, the length is the number of rows or columns, whichever is greater (this odd definition is used for compatibility with MATLAB).

@quaternion/log
===============

 -- Function File: QLOG = log (Q)
     Logarithmus naturalis of a quaternion.

@quaternion/mean
================

 -- Function File: Q = mean (Q)
 -- Function File: Q = mean (Q, DIM)
 -- Function File: Q = mean (Q, OPT)
 -- Function File: Q = mean (Q, DIM, OPT)
     Compute the mean of the elements of the quaternion array Q.

           mean (q) = mean (q.w) + mean (q.x)*i + mean (q.y)*j + mean (q.z)*k

     See help mean for more information and a description of the parameters DIM and OPT.

@quaternion/ndims
=================

 -- Function File: N = ndims (Q)
     Return the number of dimensions of quaternion Q. For any array, the result will always be larger than or equal to 2. Trailing singleton dimensions are not counted.

@quaternion/norm
================

 -- Function File: N = norm (Q)
     Norm of a quaternion.

@quaternion/numel
=================

 -- Function File: N = numel (Q)
 -- Function File: N = numel (Q, IDX1, IDX2, ...)
     For internal use only, use prod(size(q)) or numel (q.w) instead. For technical reasons, this method must return the number of elements which are returned from cs-list indexing, no matter whether it is called with one or more arguments.

@quaternion/repmat
==================

 -- Function File: QRET = repmat (Q, M)
 -- Function File: QRET = repmat (Q, M, N)
 -- Function File: QRET = repmat (Q, [M N])
 -- Function File: QRET = repmat (Q, [M N P ...])
     Form a block quaternion matrix QRET of size M by N, with a copy of quaternion matrix Q as each element. If N is not specified, form an M by M block matrix.

@quaternion/reshape
===================

 -- Function File: Q = reshape (Q, M, N, ...)
 -- Function File: Q = reshape (Q, [M N ...])
 -- Function File: Q = reshape (Q, ..., [], ...)
 -- Function File: Q = reshape (Q, SIZE)
     Return a quaternion array with the specified dimensions (M, N, ...) whose elements are taken from the quaternion array Q.  The elements of the quaternion are accessed in column-major order (like Fortran arrays are stored).

@quaternion/round
=================

 -- Function File: Q = round (Q)
     Round the components of quaternion Q towards the nearest integers.

@quaternion/rows
================

 -- Function File: NR = rows (Q)
     Return number of rows NR of quaternion array Q.

@quaternion/set
===============

 -- Function File: set (Q)
 -- Function File: set (Q, "KEY", VALUE, ...)
 -- Function File: QRET = set (Q, "KEY", VALUE, ...)
     Set or modify properties of quaternion objects. If no return argument QRET is specified, the modified quaternion object is stored in input argument Q.  set can handle multiple keys in one call: set (q, 'key1', val1, 'key2', val2, 'key3', val3). set (q) prints a list of the object's key names.

     Keys

     w
          Assign real-valued array VAL to scalar part W of quaternion Q.

     x, y, z
          Assign real-valued array VAL to component X, Y or Z of the vector part of quaternion Q.

     s
          Assign scalar part of quaternion VAL to scalar part of quaternion Q. The vector part of Q is left untouched.

     v
          Assign vector part of quaternion VAL to vector part of quaternion Q. The scalar part of Q is left untouched.

@quaternion/size
================

 -- Function File: NVEC = size (Q)
 -- Function File: N = size (Q, DIM)
 -- Function File: [NX, NY, ...] = size (Q)
     Return size of quaternion arrays.

     Inputs

     q
          Quaternion object.

     dim
          If given a second argument, size will return the size of the corresponding dimension.

     Outputs

     nvec
          Row vector.  The first element is the number of rows and the second element the number of columns.  If Q is an n-dimensional array of quaternions, the n-th element of NVEC corresponds to the size of the n-th dimension of Q.

     n
          Scalar value.  The size of the dimension DIM.

     nx
          Number of rows.

     ny
          Number of columns.

     ...
          Sizes of the 3rd to n-th dimensions.

@quaternion/size_equal
======================

 -- Function File: BOOL = size_equal (A, B, ...)
     Return true if quaternions (and matrices) A, B, ... are of equal size and false otherwise.

@quaternion/sparse
==================

 -- Function File: SQ = sparse (FQ)
     Return a sparse quaternion representation SQ from full quaternion FQ.

@quaternion/squeeze
===================

 -- Function File: QRET = squeeze (Q)
     Remove singleton dimensions from quaternion Q and return the result. Note that for compatibility with MATLAB, all objects have a minimum of two dimensions and row vectors are left unchanged.

@quaternion/sum
===============

 -- Function File: Q = sum (Q)
 -- Function File: Q = sum (Q, DIM)
 -- Function File: Q = sum (..., 'NATIVE')
 -- Function File: Q = sum (..., 'DOUBLE')
 -- Function File: Q = sum (..., 'EXTRA')
     Sum of elements along dimension DIM.  If DIM is omitted, it defaults to the first non-singleton dimension. See help sum for more information.

@quaternion/tril
================

 -- Function File: Q = tril (Q)
 -- Function File: Q = tril (Q, K)
 -- Function File: Q = tril (Q, K, 'PACK')
     Return a new quaternion matrix formed by extracting the lower triangular part of the quaternion Q, and setting all other elements to zero.  The second argument K is optional, and specifies how many diagonals above or below the main diagonal should also be included.  Default value for K is zero. If the option "pack" is given as third argument, the extracted elements are not inserted into a matrix, but rather stacked column-wise one above other.

@quaternion/triu
================

 -- Function File: Q = triu (Q)
 -- Function File: Q = triu (Q, K)
 -- Function File: Q = triu (Q, K, 'PACK')
     Return a new quaternion matrix formed by extracting the upper triangular part of the quaternion Q, and setting all other elements to zero.  The second argument K is optional, and specifies how many diagonals above or below the main diagonal should also be included.  Default value for K is zero. If the option "pack" is given as third argument, the extracted elements are not inserted into a matrix, but rather stacked column-wise one above other.

@quaternion/unit
================

 -- Function File: QN = unit (Q)
     Normalize quaternion to length 1 (unit quaternion).

           q = w + x*i + y*j + z*k
           unit (q) = q ./ sqrt (w.^2 + x.^2 + y.^2 + z.^2)

Overloaded Quaternion Operators
*******************************

@quaternion/ctranspose
======================

Conjugate transpose of a quaternion.  Used by Octave for "q'".

@quaternion/end
===============

End indexing for quaternions. Used by Octave for "q(1:end)".

@quaternion/eq
==============

Equal to operator for two quaternions.  Used by Octave for "q1 == q2".

@quaternion/ge
==============

Greater-than-or-equal-to operator for two quaternions. Used by Octave for "q1 >= q2". The ordering is lexicographic.

@quaternion/gt
==============

Greater-than operator for two quaternions. Used by Octave for "q1 > q2". The ordering is lexicographic.

@quaternion/horzcat
===================

Horizontal concatenation of quaternions.  Used by Octave for "[q1, q2]".

@quaternion/ldivide
===================

Element-wise left division for quaternions.  Used by Octave for "q1 .\ q2".

@quaternion/le
==============

Less-than-or-equal-to operator for two quaternions. Used by Octave for "q1 <= q2". The ordering is lexicographic.

@quaternion/lt
==============

Less-than operator for two quaternions. Used by Octave for "q1 < q2". The ordering is lexicographic.

@quaternion/minus
=================

Subtraction of two quaternions.  Used by Octave for "q1 - q2".

@quaternion/mldivide
====================

Matrix left division for quaternions.  Used by Octave for "q1 \ q2".

@quaternion/mpower
==================

Matrix power operator of quaternions.  Used by Octave for "q^x".

@quaternion/mrdivide
====================

Matrix right division for quaternions.  Used by Octave for "q1 / q2".

@quaternion/mtimes
==================

Matrix multiplication of two quaternions. Used by Octave for "q1 * q2".

@quaternion/ne
==============

Not-equal-to operator for two quaternions.  Used by Octave for "q1 != q2".

@quaternion/plus
================

Addition of two quaternions.  Used by Octave for "q1 + q2".

@quaternion/power
=================

Power operator of quaternions.  Used by Octave for "q.^x". Exponent x can be scalar or of appropriate size.

@quaternion/rdivide
===================

Element-wise right division for quaternions.  Used by Octave for "q1 ./ q2".

@quaternion/subsasgn
====================

Subscripted assignment for quaternions. Used by Octave for "q.key = value".

Subscripts

q.w
     Assign real-valued array VAL to scalar part W of quaternion Q.

q.x, q.y, q.z
     Assign real-valued array VAL to component X, Y or Z of the vector part of quaternion Q.

q.s
     Assign scalar part of quaternion VAL to scalar part of quaternion Q. The vector part of Q is left untouched.

q.v
     Assign vector part of quaternion VAL to vector part of quaternion Q. The scalar part of Q is left untouched.

q(...)
     Assign VAL to certain elements of quaternion array Q, e.g. q(3, 2:end) = val.

@quaternion/subsref
===================

Subscripted reference for quaternions.  Used by Octave for "q.w".

Subscripts

q.w
     Return scalar part W of quaternion Q as a built-in type.

q.x, q.y, q.z
     Return component X, Y or Z of the vector part of quaternion Q as a built-in type.

q.s
     Return scalar part of quaternion Q.  The vector part of Q is set to zero.

q.v
     Return vector part of quaternion Q.  The scalar part of Q is set to zero.

q(...)
     Extract certain elements of quaternion array Q, e.g. q(3, 2:end).

@quaternion/times
=================

Element-wise multiplication of two quaternions.  Used by Octave for "q1 .* q2".

@quaternion/transpose
=====================

Transpose of a quaternion.  Used by Octave for "q.'".

@quaternion/uminus
==================

Unary minus of a quaternion.  Used by Octave for "-q".

@quaternion/uplus
=================

Unary plus of a quaternion.  Used by Octave for "+q".

@quaternion/vertcat
===================

Vertical concatenation of quaternions.  Used by Octave for "[q1; q2]".