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 class Quaternion from gp
18 ---Purpose: Represents operation of rotation in 3d space as queternion
19 -- and implements operations with rotations basing on
20 -- quaternion mathematics.
22 -- In addition, provides methods for conversion to and from other
23 -- representatons of rotation (3*3 matrix, vector and
24 -- angle, Euler angles)
33 Create returns Quaternion from gp;
34 ---Purpose: Creates an identity quaternion
37 Create (x, y, z, w: Real)
38 returns Quaternion from gp;
39 ---Purpose: Creates quaternion directly from component values
41 Create (theToCopy: Quaternion from gp)
42 returns Quaternion from gp;
43 ---Purpose: Creates copy of another quaternion
45 Create (theVecFrom, theVecTo: Vec from gp)
46 returns Quaternion from gp;
47 ---Purpose: Creates quaternion representing shortest-arc rotation
48 -- operator producing vector theVecTo from vector theVecFrom.
50 Create (theVecFrom, theVecTo, theHelpCrossVec: Vec from gp)
51 returns Quaternion from gp;
52 ---Purpose: Creates quaternion representing shortest-arc rotation
53 -- operator producing vector theVecTo from vector theVecFrom.
54 -- Additional vector theHelpCrossVec defines preferred direction for
55 -- rotation and is used when theVecTo and theVecFrom are directed
58 Create (theAxis: Vec from gp; theAngle: Real)
59 returns Quaternion from gp;
60 ---Purpose: Creates quaternion representing rotation on angle
61 -- theAngle around vector theAxis
63 Create (theMat: Mat from gp)
64 returns Quaternion from gp;
65 ---Purpose: Creates quaternion from rotation matrix 3*3
66 -- (which should be orthonormal skew-symmetric matrix)
68 IsEqual (me; theOther: Quaternion from gp) returns Boolean;
69 ---Purpose: Simple equal test without precision
71 SetRotation (me: in out; theVecFrom, theVecTo: Vec from gp);
72 ---Purpose: Sets quaternion to shortest-arc rotation producing
73 -- vector theVecTo from vector theVecFrom.
74 -- If vectors theVecFrom and theVecTo are opposite then rotation
75 -- axis is computed as theVecFrom ^ (1,0,0) or theVecFrom ^ (0,0,1).
77 SetRotation (me: in out; theVecFrom, theVecTo, theHelpCrossVec: Vec from gp);
78 ---Purpose: Sets quaternion to shortest-arc rotation producing
79 -- vector theVecTo from vector theVecFrom.
80 -- If vectors theVecFrom and theVecTo are opposite then rotation
81 -- axis is computed as theVecFrom ^ theHelpCrossVec.
83 SetVectorAndAngle (me: in out; theAxis: Vec from gp; theAngle: Real);
84 ---Purpose: Create a unit quaternion from Axis+Angle representation
86 GetVectorAndAngle (me; theAxis: out Vec from gp; theAngle: out Real);
87 ---Purpose: Convert a quaternion to Axis+Angle representation,
88 -- preserve the axis direction and angle from -PI to +PI
90 SetMatrix (me: in out; theMat: Mat from gp);
91 ---Purpose: Create a unit quaternion by rotation matrix
92 -- matrix must contain only rotation (not scale or shear)
94 -- For numerical stability we find first the greatest component of quaternion
95 -- and than search others from this one
97 GetMatrix (me) returns Mat from gp;
98 ---Purpose: Returns rotation operation as 3*3 matrix
100 SetEulerAngles (me: in out; theOrder: EulerSequence from gp;
101 theAlpha, theBeta, theGamma: Real);
102 ---Purpose: Create a unit quaternion representing rotation defined
103 -- by generalized Euler angles
105 GetEulerAngles (me; theOrder: EulerSequence from gp;
106 theAlpha, theBeta, theGamma: out Real);
107 ---Purpose: Returns Euler angles describing current rotation
109 Set (me: in out; x, y, z, w: Real);
111 Set (me: in out; theQuaternion: Quaternion from gp);
121 SetIdent (me: in out);
122 ---Purpose: Make identity quaternion (zero-rotation)
124 Reverse (me: in out);
125 ---Purpose: Reverse direction of rotation (conjugate quaternion)
127 Reversed (me) returns Quaternion from gp;
128 ---Purpose: Return rotation with reversed direction (conjugated quaternion)
131 ---Purpose: Inverts quaternion (both rotation direction and norm)
133 Inverted (me) returns Quaternion from gp;
134 ---Purpose: Return inversed quaternion q^-1
136 SquareNorm (me) returns Real;
137 ---Purpose: Returns square norm of quaternion
139 Norm (me) returns Real;
140 ---Purpose: Returns norm of quaternion
142 Scale (me: in out; theScale: Real);
143 ---Purpose: Scale all components by quaternion by theScale; note that
144 -- rotation is not changed by this operation (except 0-scaling)
145 ---C++: alias operator *=
147 Scaled (me; theScale: Real) returns Quaternion from gp;
148 ---Purpose: Returns scaled quaternion
149 ---C++: alias operator *
151 StabilizeLength (me: in out);
152 ---Purpose: Stabilize quaternion length within 1 - 1/4.
153 -- This operation is a lot faster than normalization
154 -- and preserve length goes to 0 or infinity
156 Normalize (me: in out);
157 ---Purpose: Scale quaternion that its norm goes to 1.
158 -- The appearing of 0 magnitude or near is a error,
159 -- so we can be sure that can divide by magnitude
161 Normalized (me) returns Quaternion from gp;
162 ---Purpose: Returns quaternion scaled so that its norm goes to 1.
164 Negated (me) returns Quaternion from gp;
165 ---Purpose: Returns quaternion with all components negated.
166 -- Note that this operation does not affect neither
167 -- rotation operator defined by quaternion nor its norm.
168 ---C++: alias operator -
170 Added (me; theOther: Quaternion from gp) returns Quaternion from gp;
171 ---Purpose: Makes sum of quaternion components; result is "rotations mix"
172 ---C++: alias operator +
174 Subtracted (me; theOther: Quaternion from gp) returns Quaternion from gp;
175 ---Purpose: Makes difference of quaternion components; result is "rotations mix"
176 ---C++: alias operator -
178 Multiplied (me; theOther: Quaternion from gp) returns Quaternion from gp;
179 ---Purpose: Multiply function - work the same as Matrices multiplying.
180 -- qq' = (cross(v,v') + wv' + w'v, ww' - dot(v,v'))
181 -- Result is rotation combination: q' than q (here q=this, q'=theQ).
185 ---C++: alias operator *
187 Add (me: in out; theOther: Quaternion from gp);
188 ---Purpose: Adds componnets of other quaternion; result is "rotations mix"
189 ---C++: alias operator +=
191 Subtract (me: in out; theOther: Quaternion from gp);
192 ---Purpose: Subtracts componnets of other quaternion; result is "rotations mix"
193 ---C++: alias operator -=
195 Multiply (me: in out; theOther: Quaternion from gp);
196 ---Purpose: Adds rotation by multiplication
197 ---C++: alias operator *=
199 Dot (me; theOther: Quaternion from gp) returns Real;
200 ---Purpose: Computes inner product / scalar product / Dot
202 GetRotationAngle (me) returns Real;
203 ---Purpose: Return rotation angle from -PI to PI
205 Multiply (me; theVec: Vec from gp) returns Vec from gp;
206 ---Purpose: Rotates vector by quaternion as rotation operator
207 ---C++: alias operator *