create/src/Base/Rotation.h

/***************************************************************************
 *   Copyright (c) 2006 Werner Mayer <wmayer[at]users.sourceforge.net>     *
 *                                                                         *
 *   This file is part of the FreeCAD CAx development system.              *
 *                                                                         *
 *   This library is free software; you can redistribute it and/or         *
 *   modify it under the terms of the GNU Library General Public           *
 *   License as published by the Free Software Foundation; either          *
 *   version 2 of the License, or (at your option) any later version.      *
 *                                                                         *
 *   This library  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 Library General Public License for more details.                  *
 *                                                                         *
 *   You should have received a copy of the GNU Library General Public     *
 *   License along with this library; see the file COPYING.LIB. If not,    *
 *   write to the Free Software Foundation, Inc., 59 Temple Place,         *
 *   Suite 330, Boston, MA  02111-1307, USA                                *
 *                                                                         *
 ***************************************************************************/


#ifndef BASE_ROTATION_H
#define BASE_ROTATION_H

#include "Vector3D.h"
#ifndef FC_GLOBAL_H
#include <FCGlobal.h>
#endif

namespace Base {

// forward declarations
class Matrix4D;

class BaseExport Rotation
{
public:
    /** Construction. */
    //@{
    Rotation();
    Rotation(const Vector3d& axis, const double fAngle);
    Rotation(const Matrix4D& matrix);
    Rotation(const double q[4]);
    Rotation(const double q0, const double q1, const double q2, const double q3);
    Rotation(const Vector3d& rotateFrom, const Vector3d& rotateTo);
    Rotation(const Rotation& rot);
    //@}

    /** Methods to get or set rotations. */
    //@{
    const double * getValue() const;
    void getValue(double & q0, double & q1, double & q2, double & q3) const;
    void setValue(const double q0, const double q1, const double q2, const double q3);
    /// If not a null quaternion then \a axis will be normalized
    void getValue(Vector3d & axis, double & rfAngle) const;
    /// Does the same as the method above unless normalizing the axis.
    void getRawValue(Vector3d & axis, double & rfAngle) const;
    void getValue(Matrix4D & matrix) const;
    void setValue(const double q[4]);
    void setValue(const Matrix4D& matrix);
    void setValue(const Vector3d & axis, const double fAngle);
    void setValue(const Vector3d & rotateFrom, const Vector3d & rotateTo);
    /// Euler angles in yaw,pitch,roll notation
    void setYawPitchRoll(double y, double p, double r);
    /// Euler angles in yaw,pitch,roll notation
    void getYawPitchRoll(double& y, double& p, double& r) const;

    enum EulerSequence
    {
        Invalid,

        //! Classic Euler angles, alias to Intrinsic_ZXZ
        EulerAngles,

        //! Yaw Pitch Roll (or nautical) angles, alias to Intrinsic_ZYX
        YawPitchRoll,

        // Tait-Bryan angles (using three different axes)
        Extrinsic_XYZ,
        Extrinsic_XZY,
        Extrinsic_YZX,
        Extrinsic_YXZ,
        Extrinsic_ZXY,
        Extrinsic_ZYX,

        Intrinsic_XYZ,
        Intrinsic_XZY,
        Intrinsic_YZX,
        Intrinsic_YXZ,
        Intrinsic_ZXY,
        Intrinsic_ZYX,

        // Proper Euler angles (using two different axes, first and third the same)
        Extrinsic_XYX,
        Extrinsic_XZX,
        Extrinsic_YZY,
        Extrinsic_YXY,
        Extrinsic_ZYZ,
        Extrinsic_ZXZ,

        Intrinsic_XYX,
        Intrinsic_XZX,
        Intrinsic_YZY,
        Intrinsic_YXY,
        Intrinsic_ZXZ,
        Intrinsic_ZYZ,

        EulerSequenceLast,
    };
    static const char *eulerSequenceName(EulerSequence seq);
    static EulerSequence eulerSequenceFromName(const char *name);
    void getEulerAngles(EulerSequence seq, double &alpha, double &beta, double &gamma) const;
    void setEulerAngles(EulerSequence seq, double alpha, double beta, double gamma);
    bool isIdentity() const;
    bool isNull() const;
    //@}

    /** Invert rotations. */
    //@{
    Rotation & invert();
    Rotation inverse() const;
    //@}

    /** Operators. */
    //@{
    Rotation & operator*=(const Rotation & q);
    Rotation operator *(const Rotation & q) const;
    bool operator==(const Rotation & q) const;
    bool operator!=(const Rotation & q) const;
    double & operator [] (unsigned short usIndex){return quat[usIndex];}
    const double & operator [] (unsigned short usIndex) const{return quat[usIndex];}
    void operator = (const Rotation&);

    Rotation& multRight(const Base::Rotation& q);
    Rotation& multLeft(const Base::Rotation& q);

    void multVec(const Vector3d & src, Vector3d & dst) const;
    Vector3d multVec(const Vector3d & src) const;
    void multVec(const Vector3f & src, Vector3f & dst) const;
    Vector3f multVec(const Vector3f & src) const;
    void scaleAngle(const double scaleFactor);
    bool isSame(const Rotation&) const;
    bool isSame(const Rotation&, double tol) const;
    //@}

    /** Specialty constructors */
    static Rotation slerp(const Rotation & rot0, const Rotation & rot1, double t);
    static Rotation identity();

    /**
     * @brief makeRotationByAxes(xdir, ydir, zdir, priorityOrder): creates a rotation
     * that converts a vector in local cs with axes given as arguments, into a
     * vector in global cs.
     * @param xdir is wanted direction of local X axis
     * @param ydir ...
     * @param zdir
     * @param priorityOrder sets which directions are followed. It is a string
     * like "ZXY". This means, Z direction is followed precisely; X direction is
     * corrected to be perpendicular to Z direction, and used; Y direction
     * argument is ignored altogether (Y direction is generated from Z and X).
     *
     * If only one vector provided is nonzero, the other two directions are picked automatically.
     */
    static Rotation makeRotationByAxes(Vector3d xdir, Vector3d ydir, Vector3d zdir, const char* priorityOrder = "ZXY");

private:
    void normalize();
    void evaluateVector ();
    double quat[4];
    Vector3d _axis; // the axis kept not to lose direction when angle is 0
    double _angle; // this angle to keep the angle chosen by the user
};

}

#endif // BASE_ROTATION_H