%% Copyright (c) 2011 Juan Pablo Carbajal <carbajal@ifi.uzh.ch>
%%
%%    This program is free software: you can redistribute it and/or modify
%%    it under the terms of the GNU General Public License as published by
%%    the Free Software Foundation, either version 3 of the License, or
%%    any later version.
%%
%%    This program is distributed in the hope that it will be useful,
%%    but WITHOUT ANY WARRANTY; without even the implied warranty of
%%    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%%    GNU General Public License for more details.
%%
%%    You should have received a copy of the GNU General Public License
%%    along with this program. If not, see <http://www.gnu.org/licenses/>.

=== Robotics Toolbox Port to Octave ===
http://petercorke.com/Robotics_Toolbox.html
With the objective of porting the robotics toolbox version 9 to octave forge
we list the classes relate to quaternions.

The idea is to see when this class has been fully ported, that is:
   For a method x of the quaternion class, there is a method y in the
   quaterions_oo package that
   1.Method y produces output isomorphic to output of x.
   2.Method y receives input isomorphic to input of method y.

   When the method y exist such that fullfils 1. and 2.; we say there is
   an equivalent method in the packages quaternions_oo.

   If additonally the method y in the quaternions_oo package has the same name,
   then we say that the method x exists in the package.

The naming of the methods is not important, since the Robotics Toolbox for octave
will have a wrapper class quaternion. This class will emulate the API.


object.method(args)

using the trick used here
[ http://octave.svn.sf.net/viewvc/octave/trunk/octave-forge/main/geometry/inst/io/%40svg/subsref.m?revision=8974&view=markup ]

= Marking convention =
In the [] field of each method/operator/property add

   e  - There is an isomorphic method (equivalent).
   x  - There is an isomorphic method with the same name (exist).
   *  - There is an exact equal method in the package (same input, output and name).
   b+ - Benchmarked, slower than current method in quaternions_oo.
   b- - Benchmarked, faster than current

   c  - There is a method with the same name but not isomorphic (conflict).

Example 1:
A method qc = qconj(q) exist in quaternions_oo that calculates the inverse of a quaternion.
Then we mark inv as follows

 [e] inv

  - Example 2:
      A method [h a] = dosomething(q) from in quaternions_oo to calculate something.
      The method [h] = somethingtodo(q) from  Robotics toolbox to calculate the same.

       [e] somethingtodo

      Since the first argument is the same.
      The same holds ff [a h] = dosomething(q). Since we need just to swap output arguemnts.

  - Example 3:
    A method [h] = dosomething(q) from in quaternions_oo to calculate something.
    The method [h a] = somethingtodo(q) from  Robotics toolbox to calculate the same.

     [ ] somethingtodo

    Since we need to check how to calculate the output a.

  - Example 4:
    A method [h] = dosomething(q) from in quaternions_oo to calculate something.
    The method [h a] = somethingtodo(q) from  Robotics toolbox to calculate the same.
    And you benchmarked the methods givin a positive result for the quaternions_oo.

     [b+] somethingtodo

    The b flag indicates that there is a point of comparision but the methods may not be equivalent.

  - Example 4:
    A method [h] = dosomething(q) from in quaternions_oo to calculate something.
    The method [h] = dosomething(q) from  Robotics toolbox to calculate the same.
    And you benchmarked the methods givin a positive result for the robotics toolbox.

     [*b-] dosomething

    just concatenate flags.

We hope not to run into the c tag.

== Quaternion ==
DONE  Q = Quaternion() is the identitity quaternion 1<0,0,0> representing a null rotation.

DONE  Q = Quaternion(Q1) is a copy of the quaternion Q1

DONE  Q = Quaternion([S V1 V2 V3]) is a quaternion formed by specifying directly its 4 elements

DONE  Q = Quaternion(S) is a quaternion formed from the scalar S and zero vector part: S<0,0,0>

DONE  Q = Quaternion(V) is a pure quaternion with the specified vector part: 0<V>

DONE  Q = Quaternion(TH, V) is a unit quaternion corresponding to rotation of TH about the vector V.

DONE  Q = Quaternion(R) is a unit quaternion corresponding to the orthonormal rotation matrix R.

DONE  Q = Quaternion(T) is a unit quaternion equivalent to the rotational

= methods =
DONE [c] inv       return inverse of quaterion
DONE [e] norm:  Wraps abs from quaternions_oo
DONE [x] dot  derivative of quaternion with angular velocity w
DONE [c] display
DONE [] q2tr
DONE [*] unit      return unit quaternion

[] plot      same options as trplot()
[] interp    interpolation (slerp) between q and q2, 0<=s<=1
[] scale     interpolation (slerp) between identity and q, 0<=s<=1

= Operators =
DONE [*] q+q2      return elementwise sum of quaternions
DONE [*] q-q2      return elementwise difference of quaternions
DONE [*] q*q2      return quaternion product
DONE [*] q/q2      return q*q2.inv

[*] q*v       rotate vector by quaternion, v is 3x1
DONE [*] q^n       return q to power n (real)

= Properties (read only)=
DONE [] s         real part
DONE [] v         vector part
DONE [] R         3x3 rotation matrix
DONE [] T         4x4 homogeneous transform matrix
