quaternion.h

// quaternion.h (based on the Quaternion class from eris)
//
//  The WorldForge Project
//  Copyright (C) 2002  The WorldForge Project
//
//  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 2 of the License, or
//  (at your option) 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, write to the Free Software
//  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
//
//  For information about WorldForge and its authors, please contact
//  the Worldforge Web Site at http://www.worldforge.org.
//

// Author: Ron Steinke

#ifndef WFMATH_QUATERNION_H
#define WFMATH_QUATERNION_H

#include <wfmath/vector.h>
#include <wfmath/rotmatrix.h>

namespace WFMath {

class Quaternion
{
 public:
  class Identity {};
  Quaternion(const Identity &) : m_w(1), m_vec(), m_valid(true), m_age(0) {
    m_vec.zero();
  }
  Quaternion () : m_w(0), m_vec(), m_valid(false), m_age(0) {}

  Quaternion (CoordType w_in, CoordType x_in, CoordType y_in, CoordType z_in);
  Quaternion (int axis, CoordType angle) : m_w(0), m_vec(), m_valid(false),
                                           m_age(0)
    {rotation(axis, angle);}
  Quaternion (const Vector<3>& axis, CoordType angle) : m_w(0), m_vec(),
                                                        m_valid(false),
                                                        m_age(0)
    {rotation(axis, angle);}

  explicit Quaternion (const Vector<3>& axis) : m_w(0), m_vec(),
                                                m_valid(false), m_age(0)
    {rotation(axis);} // angle == axis.mag()
  Quaternion (const Quaternion& p) : m_w(p.m_w), m_vec(p.m_vec),
                                     m_valid(p.m_valid), m_age(p.m_age) {}
  explicit Quaternion (const AtlasInType& a) : m_w(0), m_vec(),
                                               m_valid(false), m_age(0)
    {fromAtlas(a);}

  ~Quaternion() {}

  friend std::ostream& operator<<(std::ostream& os, const Quaternion& p);
  friend std::istream& operator>>(std::istream& is, Quaternion& p);

  AtlasOutType toAtlas() const;
  void fromAtlas(const AtlasInType& a);

  Quaternion& operator= (const Quaternion& rhs)
        {m_w = rhs.m_w; m_vec = rhs.m_vec; m_valid = rhs.m_valid; m_age = rhs.m_age; return *this;}

  // This regards q and -1*q as equal, since they give the
  // same RotMatrix<3>
  bool isEqualTo(const Quaternion &q, CoordType epsilon = numeric_constants<CoordType>::epsilon()) const;

  bool operator== (const Quaternion& rhs) const {return isEqualTo(rhs);}
  bool operator!= (const Quaternion& rhs) const {return !isEqualTo(rhs);}

  bool isValid() const {return m_valid;}

  Quaternion& identity() {m_w = 1; m_vec.zero(); m_valid = true; m_age = 0; return *this;} // Set to null rotation

  // Operators

  Quaternion& operator*= (const Quaternion& rhs);
  Quaternion& operator/= (const Quaternion& rhs);
  Quaternion operator* (const Quaternion& rhs) const {
    Quaternion out(*this);
    out *= rhs;
    return out;
  }
  Quaternion operator/ (const Quaternion& rhs) const {
    Quaternion out(*this);
    out /= rhs;
    return out;
  }

  // Functions

  // Returns "not_flip", similar to RotMatrix<>.toEuler()

  bool fromRotMatrix(const RotMatrix<3>& m);

  Quaternion inverse() const;

  Quaternion& rotate(const RotMatrix<3>&);

  Quaternion& rotate(const Quaternion& q) {return operator*=(q);}

  Quaternion& rotation(int axis, CoordType angle);
  Quaternion& rotation(const Vector<3>& axis, CoordType angle);

  Quaternion& rotation(const Vector<3>& axis); // angle == axis.mag()

  Quaternion& rotation(const Vector<3>& from, const Vector<3>& to);

  CoordType scalar() const              {return m_w;}
  const Vector<3>& vector() const       {return m_vec;}

  void normalize();
  unsigned age() const {return m_age;}

 private:
  Quaternion(bool valid) : m_w(0), m_vec(), m_valid(valid), m_age(1) {}
  void checkNormalization() {if(m_age >= WFMATH_MAX_NORM_AGE && m_valid) normalize();}
  CoordType m_w;
  Vector<3> m_vec;
  bool m_valid;
  unsigned m_age;
};

} // namespace WFMath

#endif  // WFMATH_QUATERNION_H