1 // Created on: 2010-05-11
2 // Created by: Kirill GAVRILOV
3 // Copyright (c) 2010-2014 OPEN CASCADE SAS
5 // This file is part of Open CASCADE Technology software library.
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.
13 // Alternatively, this file may be used under the terms of Open CASCADE
14 // commercial license or contractual agreement.
16 #ifndef _gp_Quaternion_HeaderFile
17 #define _gp_Quaternion_HeaderFile
19 #include <Standard.hxx>
20 #include <Standard_DefineAlloc.hxx>
21 #include <Standard_Handle.hxx>
23 #include <Standard_Real.hxx>
24 #include <Standard_Boolean.hxx>
25 #include <gp_EulerSequence.hxx>
31 //! Represents operation of rotation in 3d space as queternion
32 //! and implements operations with rotations basing on
33 //! quaternion mathematics.
35 //! In addition, provides methods for conversion to and from other
36 //! representatons of rotation (3*3 matrix, vector and
37 //! angle, Euler angles)
45 //! Creates an identity quaternion
48 //! Creates quaternion directly from component values
49 Standard_EXPORT gp_Quaternion(const Standard_Real x, const Standard_Real y, const Standard_Real z, const Standard_Real w);
51 //! Creates copy of another quaternion
52 Standard_EXPORT gp_Quaternion(const gp_Quaternion& theToCopy);
54 //! Creates quaternion representing shortest-arc rotation
55 //! operator producing vector theVecTo from vector theVecFrom.
56 Standard_EXPORT gp_Quaternion(const gp_Vec& theVecFrom, const gp_Vec& theVecTo);
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
63 Standard_EXPORT gp_Quaternion(const gp_Vec& theVecFrom, const gp_Vec& theVecTo, const gp_Vec& theHelpCrossVec);
65 //! Creates quaternion representing rotation on angle
66 //! theAngle around vector theAxis
67 Standard_EXPORT gp_Quaternion(const gp_Vec& theAxis, const Standard_Real theAngle);
69 //! Creates quaternion from rotation matrix 3*3
70 //! (which should be orthonormal skew-symmetric matrix)
71 Standard_EXPORT gp_Quaternion(const gp_Mat& theMat);
73 //! Simple equal test without precision
74 Standard_EXPORT Standard_Boolean IsEqual (const gp_Quaternion& theOther) const;
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);
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);
88 //! Create a unit quaternion from Axis+Angle representation
89 Standard_EXPORT void SetVectorAndAngle (const gp_Vec& theAxis, const Standard_Real theAngle);
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;
95 //! Create a unit quaternion by rotation matrix
96 //! matrix must contain only rotation (not scale or shear)
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);
102 //! Returns rotation operation as 3*3 matrix
103 Standard_EXPORT gp_Mat GetMatrix() const;
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);
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;
112 Standard_EXPORT void Set (const Standard_Real x, const Standard_Real y, const Standard_Real z, const Standard_Real w);
114 Standard_EXPORT void Set (const gp_Quaternion& theQuaternion);
116 Standard_EXPORT Standard_Real X() const;
118 Standard_EXPORT Standard_Real Y() const;
120 Standard_EXPORT Standard_Real Z() const;
122 Standard_EXPORT Standard_Real W() const;
124 //! Make identity quaternion (zero-rotation)
125 Standard_EXPORT void SetIdent();
127 //! Reverse direction of rotation (conjugate quaternion)
128 Standard_EXPORT void Reverse();
130 //! Return rotation with reversed direction (conjugated quaternion)
131 Standard_EXPORT gp_Quaternion Reversed() const;
133 //! Inverts quaternion (both rotation direction and norm)
134 Standard_EXPORT void Invert();
136 //! Return inversed quaternion q^-1
137 Standard_EXPORT gp_Quaternion Inverted() const;
139 //! Returns square norm of quaternion
140 Standard_EXPORT Standard_Real SquareNorm() const;
142 //! Returns norm of quaternion
143 Standard_EXPORT Standard_Real Norm() const;
145 //! Scale all components by quaternion by theScale; note that
146 //! rotation is not changed by this operation (except 0-scaling)
147 Standard_EXPORT void Scale (const Standard_Real theScale);
148 void operator *= (const Standard_Real theScale)
153 //! Returns scaled quaternion
154 Standard_EXPORT gp_Quaternion Scaled (const Standard_Real theScale) const;
155 gp_Quaternion operator * (const Standard_Real theScale) const
157 return Scaled(theScale);
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();
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();
170 //! Returns quaternion scaled so that its norm goes to 1.
171 Standard_EXPORT gp_Quaternion Normalized() const;
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 Standard_EXPORT gp_Quaternion Negated() const;
177 gp_Quaternion operator -() const
182 //! Makes sum of quaternion components; result is "rotations mix"
183 Standard_EXPORT gp_Quaternion Added (const gp_Quaternion& theOther) const;
184 gp_Quaternion operator + (const gp_Quaternion& theOther) const
186 return Added(theOther);
189 //! Makes difference of quaternion components; result is "rotations mix"
190 Standard_EXPORT gp_Quaternion Subtracted (const gp_Quaternion& theOther) const;
191 gp_Quaternion operator - (const gp_Quaternion& theOther) const
193 return Subtracted(theOther);
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).
202 Standard_EXPORT gp_Quaternion Multiplied (const gp_Quaternion& theOther) const;
203 gp_Quaternion operator * (const gp_Quaternion& theOther) const
205 return Multiplied(theOther);
208 //! Adds componnets of other quaternion; result is "rotations mix"
209 Standard_EXPORT void Add (const gp_Quaternion& theOther);
210 void operator += (const gp_Quaternion& theOther)
215 //! Subtracts componnets of other quaternion; result is "rotations mix"
216 Standard_EXPORT void Subtract (const gp_Quaternion& theOther);
217 void operator -= (const gp_Quaternion& theOther)
222 //! Adds rotation by multiplication
223 Standard_EXPORT void Multiply (const gp_Quaternion& theOther);
224 void operator *= (const gp_Quaternion& theOther)
229 //! Computes inner product / scalar product / Dot
230 Standard_EXPORT Standard_Real Dot (const gp_Quaternion& theOther) const;
232 //! Return rotation angle from -PI to PI
233 Standard_EXPORT Standard_Real GetRotationAngle() const;
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
239 return Multiply(theVec);
264 #include <gp_Quaternion.lxx>
270 #endif // _gp_Quaternion_HeaderFile