src/gp/gp_Quaternion.hxx

   1 // Created on: 2010-05-11
   2 // Created by: Kirill GAVRILOV
   3 // Copyright (c) 2010-2014 OPEN CASCADE SAS
   4 //
   5 // This file is part of Open CASCADE Technology software library.
   6 //
   7 // This library is free software; you can redistribute it and/or modify it under
   8 // the terms of the GNU Lesser General Public License version 2.1 as published
   9 // by the Free Software Foundation, with special exception defined in the file
  10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  11 // distribution for complete text of the license and disclaimer of any warranty.
  12 //
  13 // Alternatively, this file may be used under the terms of Open CASCADE
  14 // commercial license or contractual agreement.
  15
  16 #ifndef _gp_Quaternion_HeaderFile
  17 #define _gp_Quaternion_HeaderFile
  18
  19 #include <Standard.hxx>
  20 #include <Standard_DefineAlloc.hxx>
  21 #include <Standard_Handle.hxx>
  22
  23 #include <Standard_Real.hxx>
  24 #include <Standard_Boolean.hxx>
  25 #include <gp_EulerSequence.hxx>
  26 #include <gp_Vec.hxx>
  27 class gp_Vec;
  28 class gp_Mat;
  29
  30
  31 //! Represents operation of rotation in 3d space as queternion
  32 //! and implements operations with rotations basing on
  33 //! quaternion mathematics.
  34 //!
  35 //! In addition, provides methods for conversion to and from other
  36 //! representatons of rotation (3*3 matrix, vector and
  37 //! angle, Euler angles)
  38 class gp_Quaternion
  39 {
  40 public:
  41
  42   DEFINE_STANDARD_ALLOC
  43
  44
  45   //! Creates an identity quaternion
  46   gp_Quaternion();
  47
  48   //! Creates quaternion directly from component values
  49   gp_Quaternion(const Standard_Real x, const Standard_Real y, const Standard_Real z, const Standard_Real w);
  50
  51   //! Creates copy of another quaternion
  52   gp_Quaternion(const gp_Quaternion& theToCopy);
  53
  54   //! Creates quaternion representing shortest-arc rotation
  55   //! operator producing vector theVecTo from vector theVecFrom.
  56   gp_Quaternion(const gp_Vec& theVecFrom, const gp_Vec& theVecTo);
  57
  58   //! Creates quaternion representing shortest-arc rotation
  59   //! operator producing vector theVecTo from vector theVecFrom.
  60   //! Additional vector theHelpCrossVec defines preferred direction for
  61   //! rotation and is used when theVecTo and theVecFrom are directed
  62   //! oppositely.
  63   gp_Quaternion(const gp_Vec& theVecFrom, const gp_Vec& theVecTo, const gp_Vec& theHelpCrossVec);
  64
  65   //! Creates quaternion representing rotation on angle
  66   //! theAngle around vector theAxis
  67   gp_Quaternion(const gp_Vec& theAxis, const Standard_Real theAngle);
  68
  69   //! Creates quaternion from rotation matrix 3*3
  70   //! (which should be orthonormal skew-symmetric matrix)
  71   gp_Quaternion(const gp_Mat& theMat);
  72
  73   //! Simple equal test without precision
  74   Standard_EXPORT Standard_Boolean IsEqual (const gp_Quaternion& theOther) const;
  75
  76   //! Sets quaternion to shortest-arc rotation producing
  77   //! vector theVecTo from vector theVecFrom.
  78   //! If vectors theVecFrom and theVecTo are opposite then rotation
  79   //! axis is computed as theVecFrom ^ (1,0,0) or theVecFrom ^ (0,0,1).
  80   Standard_EXPORT void SetRotation (const gp_Vec& theVecFrom, const gp_Vec& theVecTo);
  81
  82   //! Sets quaternion to shortest-arc rotation producing
  83   //! vector theVecTo from vector theVecFrom.
  84   //! If vectors theVecFrom and theVecTo are opposite then rotation
  85   //! axis is computed as theVecFrom ^ theHelpCrossVec.
  86   Standard_EXPORT void SetRotation (const gp_Vec& theVecFrom, const gp_Vec& theVecTo, const gp_Vec& theHelpCrossVec);
  87
  88   //! Create a unit quaternion from Axis+Angle representation
  89   Standard_EXPORT void SetVectorAndAngle (const gp_Vec& theAxis, const Standard_Real theAngle);
  90
  91   //! Convert a quaternion to Axis+Angle representation,
  92   //! preserve the axis direction and angle from -PI to +PI
  93   Standard_EXPORT void GetVectorAndAngle (gp_Vec& theAxis, Standard_Real& theAngle) const;
  94
  95   //! Create a unit quaternion by rotation matrix
  96   //! matrix must contain only rotation (not scale or shear)
  97   //!
  98   //! For numerical stability we find first the greatest component of quaternion
  99   //! and than search others from this one
 100   Standard_EXPORT void SetMatrix (const gp_Mat& theMat);
 101
 102   //! Returns rotation operation as 3*3 matrix
 103   Standard_EXPORT gp_Mat GetMatrix() const;
 104
 105   //! Create a unit quaternion representing rotation defined
 106   //! by generalized Euler angles
 107   Standard_EXPORT void SetEulerAngles (const gp_EulerSequence theOrder, const Standard_Real theAlpha, const Standard_Real theBeta, const Standard_Real theGamma);
 108
 109   //! Returns Euler angles describing current rotation
 110   Standard_EXPORT void GetEulerAngles (const gp_EulerSequence theOrder, Standard_Real& theAlpha, Standard_Real& theBeta, Standard_Real& theGamma) const;
 111
 112   void Set (const Standard_Real x, const Standard_Real y, const Standard_Real z, const Standard_Real w);
 113
 114   void Set (const gp_Quaternion& theQuaternion);
 115
 116   Standard_Real X() const;
 117
 118   Standard_Real Y() const;
 119
 120   Standard_Real Z() const;
 121
 122   Standard_Real W() const;
 123
 124   //! Make identity quaternion (zero-rotation)
 125   void SetIdent();
 126
 127   //! Reverse direction of rotation (conjugate quaternion)
 128   void Reverse();
 129
 130   //! Return rotation with reversed direction (conjugated quaternion)
 131   gp_Quaternion Reversed() const;
 132
 133   //! Inverts quaternion (both rotation direction and norm)
 134   void Invert();
 135
 136   //! Return inversed quaternion q^-1
 137   gp_Quaternion Inverted() const;
 138
 139   //! Returns square norm of quaternion
 140   Standard_Real SquareNorm() const;
 141
 142   //! Returns norm of quaternion
 143   Standard_Real Norm() const;
 144
 145   //! Scale all components by quaternion by theScale; note that
 146   //! rotation is not changed by this operation (except 0-scaling)
 147   void Scale (const Standard_Real theScale);
 148 void operator *= (const Standard_Real theScale)
 149 {
 150   Scale(theScale);
 151 }
 152
 153   //! Returns scaled quaternion
 154   gp_Quaternion Scaled (const Standard_Real theScale) const;
 155 gp_Quaternion operator * (const Standard_Real theScale) const
 156 {
 157   return Scaled(theScale);
 158 }
 159
 160   //! Stabilize quaternion length within 1 - 1/4.
 161   //! This operation is a lot faster than normalization
 162   //! and preserve length goes to 0 or infinity
 163   Standard_EXPORT void StabilizeLength();
 164
 165   //! Scale quaternion that its norm goes to 1.
 166   //! The appearing of 0 magnitude or near is a error,
 167   //! so we can be sure that can divide by magnitude
 168   Standard_EXPORT void Normalize();
 169
 170   //! Returns quaternion scaled so that its norm goes to 1.
 171   gp_Quaternion Normalized() const;
 172
 173   //! Returns quaternion with all components negated.
 174   //! Note that this operation does not affect neither
 175   //! rotation operator defined by quaternion nor its norm.
 176   gp_Quaternion Negated() const;
 177 gp_Quaternion operator -() const
 178 {
 179   return Negated();
 180 }
 181
 182   //! Makes sum of quaternion components; result is "rotations mix"
 183   gp_Quaternion Added (const gp_Quaternion& theOther) const;
 184 gp_Quaternion operator + (const gp_Quaternion& theOther) const
 185 {
 186   return Added(theOther);
 187 }
 188
 189   //! Makes difference of quaternion components; result is "rotations mix"
 190   gp_Quaternion Subtracted (const gp_Quaternion& theOther) const;
 191 gp_Quaternion operator - (const gp_Quaternion& theOther) const
 192 {
 193   return Subtracted(theOther);
 194 }
 195
 196   //! Multiply function - work the same as Matrices multiplying.
 197   //! qq' = (cross(v,v') + wv' + w'v, ww' - dot(v,v'))
 198   //! Result is rotation combination: q' than q (here q=this, q'=theQ).
 199   //! Notices than:
 200   //! qq' != q'q;
 201   //! qq^-1 = q;
 202   gp_Quaternion Multiplied (const gp_Quaternion& theOther) const;
 203 gp_Quaternion operator * (const gp_Quaternion& theOther) const
 204 {
 205   return Multiplied(theOther);
 206 }
 207
 208   //! Adds componnets of other quaternion; result is "rotations mix"
 209   void Add (const gp_Quaternion& theOther);
 210 void operator += (const gp_Quaternion& theOther)
 211 {
 212   Add(theOther);
 213 }
 214
 215   //! Subtracts componnets of other quaternion; result is "rotations mix"
 216   void Subtract (const gp_Quaternion& theOther);
 217 void operator -= (const gp_Quaternion& theOther)
 218 {
 219   Subtract(theOther);
 220 }
 221
 222   //! Adds rotation by multiplication
 223   void Multiply (const gp_Quaternion& theOther);
 224 void operator *= (const gp_Quaternion& theOther)
 225 {
 226   Multiply(theOther);
 227 }
 228
 229   //! Computes inner product / scalar product / Dot
 230   Standard_Real Dot (const gp_Quaternion& theOther) const;
 231
 232   //! Return rotation angle from -PI to PI
 233   Standard_EXPORT Standard_Real GetRotationAngle() const;
 234
 235   //! Rotates vector by quaternion as rotation operator
 236   Standard_EXPORT gp_Vec Multiply (const gp_Vec& theVec) const;
 237 gp_Vec operator * (const gp_Vec& theVec) const
 238 {
 239   return Multiply(theVec);
 240 }
 241
 242
 243
 244
 245 protected:
 246
 247
 248
 249
 250
 251 private:
 252
 253
 254
 255   Standard_Real x;
 256   Standard_Real y;
 257   Standard_Real z;
 258   Standard_Real w;
 259
 260
 261 };
 262
 263
 264 #include <gp_Quaternion.lxx>
 265
 266
 267
 268
 269
 270 #endif // _gp_Quaternion_HeaderFile