HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
rotation.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef GF_ROTATION_H
25 #define GF_ROTATION_H
26 
27 /// \file gf/rotation.h
28 /// \ingroup group_gf_LinearAlgebra
29 
30 #include "pxr/pxr.h"
31 #include "pxr/base/gf/quaternion.h"
32 #include "pxr/base/gf/quatd.h"
33 #include "pxr/base/gf/matrix4d.h"
34 #include "pxr/base/gf/vec3d.h"
35 #include "pxr/base/gf/vec3f.h"
36 #include "pxr/base/gf/api.h"
37 
38 #include <hboost/functional/hash.hpp>
39 
40 #include <iosfwd>
41 
43 
44 /// \class GfRotation
45 /// \ingroup group_gf_LinearAlgebra
46 ///
47 /// Basic type: 3-space rotation specification.
48 ///
49 /// This class represents a rotation in 3-space. This stores an axis as a
50 /// normalized vector of 3 \c doubles and an angle in degrees (as a double).
51 /// Rotations follow the right-hand rule: a positive rotation about an axis
52 /// vector appears counter-clockwise when looking from the end of the vector
53 /// toward the origin.
54 ///
55 class GfRotation {
56 
57  public:
58 
59  /// The default constructor leaves the rotation undefined.
61  }
62 
63  /// This constructor initializes the rotation to be \p angle
64  /// degrees about \p axis.
65  GfRotation(const GfVec3d &axis, double angle) {
66  SetAxisAngle(axis, angle);
67  }
68 
69  /// This constructor initializes the rotation from a quaternion.
70  GfRotation(const GfQuaternion &quaternion) {
71  SetQuaternion(quaternion);
72  }
73 
74  /// This constructor initializes the rotation from a quaternion. Note that
75  /// this constructor accepts GfQuatf and GfQuath since they implicitly
76  /// convert to GfQuatd.
77  GfRotation(const GfQuatd &quat) { SetQuat(quat); }
78 
79  /// This constructor initializes the rotation to one that brings
80  /// the \p rotateFrom vector to align with \p rotateTo. The passed
81  /// vectors need not be unit length.
82  GF_API
83  GfRotation(const GfVec3d &rotateFrom, const GfVec3d &rotateTo) {
84  SetRotateInto(rotateFrom, rotateTo);
85  }
86 
87  /// Sets the rotation to be \p angle degrees about \p axis.
88  GfRotation & SetAxisAngle(const GfVec3d &axis, double angle) {
89  _axis = axis;
90  _angle = angle;
91  if (!GfIsClose(_axis * _axis, 1.0, 1e-10))
92  _axis.Normalize();
93  return *this;
94  }
95 
96  /// Sets the rotation from a quaternion. Note that this method accepts
97  /// GfQuatf and GfQuath since they implicitly convert to GfQuatd.
98  GF_API
99  GfRotation & SetQuat(const GfQuatd &quat);
100 
101  /// Sets the rotation from a quaternion.
103  return SetQuat(GfQuatd(quat.GetReal(), quat.GetImaginary()));
104  }
105 
106  /// Sets the rotation to one that brings the \p rotateFrom vector
107  /// to align with \p rotateTo. The passed vectors need not be unit
108  /// length.
109  GF_API
110  GfRotation & SetRotateInto(const GfVec3d &rotateFrom,
111  const GfVec3d &rotateTo);
112 
113  /// Sets the rotation to an identity rotation.
114  /// (This is chosen to be 0 degrees around the positive X axis.)
116  _axis.Set(1.0, 0.0, 0.0);
117  _angle = 0.0;
118  return *this;
119  }
120 
121  /// Returns the axis of rotation.
122  const GfVec3d & GetAxis() const {
123  return _axis;
124  }
125 
126  /// Returns the rotation angle in degrees.
127  double GetAngle() const {
128  return _angle;
129  }
130 
131  /// Returns the rotation expressed as a quaternion.
133  auto quat = GetQuat();
134  return GfQuaternion(quat.GetReal(), quat.GetImaginary());
135  }
136 
137  /// Returns the rotation expressed as a quaternion.
138  GF_API
139  GfQuatd GetQuat() const;
140 
141  /// Returns the inverse of this rotation.
143  return GfRotation(_axis, -_angle);
144  }
145 
146  /// Decompose rotation about 3 orthogonal axes.
147  /// If the axes are not orthogonal, warnings will be spewed.
148  GF_API
149  GfVec3d Decompose( const GfVec3d &axis0,
150  const GfVec3d &axis1,
151  const GfVec3d &axis2 ) const;
152 
153  // Full-featured method to Decompose a rotation matrix into Cardarian
154  // angles.
155  // Axes have must be normalized. If useHint is specified
156  // then the current values stored within thetaTw, thetaFB, thetaLR,
157  // and thetaSw will be treated as hint and used to help choose
158  // an equivalent rotation that is as close as possible to the hints.
159  //
160  // One can use this routine to generate any combination of the three
161  // angles by passing in NULL for the angle that is to be omitted.
162  //
163  // Passing in valid pointers for all four angles will decompose into
164  // Tw, FB, and LR but allows Sw to be used for best matching of hint
165  // values. It also allows an swShift value to be passed in as a
166  // Sw that is applied after the rotation matrix to get a best fit rotation
167  // in four angles.
168  //
169  // Angles are in radians.
170  //
171  // Specify \p handedness as -1.0 or 1.0, same as for MultiRotate.
172  //
173  // NOTE:
174  // Geppetto math function Originally brought over to extMover
175  // from //depot/main/tools/src/menv/lib/gpt/util.h [10/16/06]
176  // And moved into GfRotation[12/1/08]. Updated for any
177  // combination of three angles [12/1/11].
178  //
179  GF_API
180  static void DecomposeRotation(const GfMatrix4d &rot,
181  const GfVec3d &TwAxis,
182  const GfVec3d &FBAxis,
183  const GfVec3d &LRAxis,
184  double handedness,
185  double *thetaTw,
186  double *thetaFB,
187  double *thetaLR,
188  double *thetaSw = NULL,
189  bool useHint=false,
190  const double *swShift=NULL);
191 
192  // This function projects the vectors \p v1 and \p v2 onto the plane
193  // normal to \p axis, and then returns the rotation about \p axis that
194  // brings \p v1 onto \p v2.
195  GF_API
197  const GfVec3d &v2,
198  const GfVec3d &axis);
199 
200  /// Transforms row vector \p vec by the rotation, returning the result.
201  GF_API
202  GfVec3f TransformDir( const GfVec3f &vec ) const;
203 
204  /// \overload
205  GF_API
206  GfVec3d TransformDir( const GfVec3d &vec ) const;
207 
208  /// Hash.
209  friend inline size_t hash_value(const GfRotation &r) {
210  size_t h = 0;
211  hboost::hash_combine(h, r._axis);
212  hboost::hash_combine(h, r._angle);
213  return h;
214  }
215 
216  /// Component-wise rotation equality test. The axes and angles must match
217  /// exactly for rotations to be considered equal. (To compare equality of
218  /// the actual rotations, you can convert both to quaternions and test the
219  /// results for equality.)
220  bool operator ==(const GfRotation &r) const {
221  return (_axis == r._axis &&
222  _angle == r._angle);
223  }
224 
225  /// Component-wise rotation inequality test. The axes and angles must
226  /// match exactly for rotations to be considered equal. (To compare
227  /// equality of the actual rotations, you can convert both to quaternions
228  /// and test the results for equality.)
229  bool operator !=(const GfRotation &r) const {
230  return ! (*this == r);
231  }
232 
233  /// Post-multiplies rotation \p r into this rotation.
234  GF_API
236 
237  /// Scales rotation angle by multiplying by \p scale.
239  _angle *= scale;
240  return *this;
241  }
242 
243  /// Scales rotation angle by dividing by \p scale.
245  _angle /= scale;
246  return *this;
247  }
248 
249  /// Returns composite rotation of rotations \p r1 and \p r2.
250  friend GfRotation operator *(const GfRotation &r1,
251  const GfRotation &r2) {
252  GfRotation r = r1;
253  return r *= r2;
254  }
255 
256  /// Returns a rotation equivalent to \p r with its angle multiplied
257  /// by \p scale.
258  friend GfRotation operator *(const GfRotation &r, double scale) {
259  GfRotation rTmp = r;
260  return rTmp *= scale;
261  }
262 
263  /// Returns a rotation equivalent to \p r with its angle multiplied
264  /// by \p scale.
265  friend GfRotation operator *(double scale, const GfRotation &r) {
266  return (r * scale);
267  }
268 
269  /// Returns a rotation equivalent to \p r with its angle divided
270  /// by \p scale.
271  friend GfRotation operator /(const GfRotation &r, double scale) {
272  GfRotation rTmp = r;
273  return rTmp /= scale;
274  }
275 
276  private:
277  /// Axis storage.
278  /// This axis is normalized to unit length whenever it is set.
279  GfVec3d _axis;
280  /// Angle storage (represented in degrees).
281  double _angle;
282 };
283 
284 /// Output a GfRotation using the format [(x y z) a].
285 /// \ingroup group_gf_DebuggingOutput
286 GF_API std::ostream& operator<<(std::ostream&, const GfRotation&);
287 
289 
290 #endif // GF_ROTATION_H
GF_API GfVec3f TransformDir(const GfVec3f &vec) const
Transforms row vector vec by the rotation, returning the result.
GfRotation & SetAxisAngle(const GfVec3d &axis, double angle)
Sets the rotation to be angle degrees about axis.
Definition: rotation.h:88
GfRotation GetInverse() const
Returns the inverse of this rotation.
Definition: rotation.h:142
bool operator!=(const GfRotation &r) const
Definition: rotation.h:229
GF_API GfQuatd GetQuat() const
Returns the rotation expressed as a quaternion.
GfRotation(const GfQuatd &quat)
Definition: rotation.h:77
GLenum GLenum GLenum GLenum GLenum scale
Definition: glew.h:13880
GfRotation(const GfQuaternion &quaternion)
This constructor initializes the rotation from a quaternion.
Definition: rotation.h:70
friend size_t hash_value(const GfRotation &r)
Hash.
Definition: rotation.h:209
GA_API const UT_StringHolder rot
double GetReal() const
Returns the real part of the quaternion.
Definition: quaternion.h:85
Definition: vec3f.h:63
GF_API GfRotation(const GfVec3d &rotateFrom, const GfVec3d &rotateTo)
Definition: rotation.h:83
GF_API GfRotation & SetQuat(const GfQuatd &quat)
friend GfRotation operator*(const GfRotation &r1, const GfRotation &r2)
Returns composite rotation of rotations r1 and r2.
Definition: rotation.h:250
GLdouble angle
Definition: glew.h:9135
static GF_API void DecomposeRotation(const GfMatrix4d &rot, const GfVec3d &TwAxis, const GfVec3d &FBAxis, const GfVec3d &LRAxis, double handedness, double *thetaTw, double *thetaFB, double *thetaLR, double *thetaSw=NULL, bool useHint=false, const double *swShift=NULL)
GLfloat GLfloat GLfloat v2
Definition: glew.h:1856
GfRotation()
The default constructor leaves the rotation undefined.
Definition: rotation.h:60
GF_API GfRotation & SetRotateInto(const GfVec3d &rotateFrom, const GfVec3d &rotateTo)
GfRotation & SetQuaternion(const GfQuaternion &quat)
Sets the rotation from a quaternion.
Definition: rotation.h:102
GF_API std::ostream & operator<<(std::ostream &, const GfRotation &)
GfRotation & SetIdentity()
Definition: rotation.h:115
GLfloat GLfloat GLfloat GLfloat h
Definition: glew.h:8011
GfRotation & operator/=(double scale)
Scales rotation angle by dividing by scale.
Definition: rotation.h:244
PXR_NAMESPACE_OPEN_SCOPE bool GfIsClose(double a, double b, double epsilon)
Definition: math.h:39
GfQuaternion GetQuaternion() const
Returns the rotation expressed as a quaternion.
Definition: rotation.h:132
GF_API GfRotation & operator*=(const GfRotation &r)
Post-multiplies rotation r into this rotation.
GfRotation(const GfVec3d &axis, double angle)
Definition: rotation.h:65
friend GfRotation operator/(const GfRotation &r, double scale)
Definition: rotation.h:271
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1245
GfVec3d & Set(double s0, double s1, double s2)
Set all elements with passed arguments.
Definition: vec3d.h:130
bool operator==(const GfRotation &r) const
Definition: rotation.h:220
GLdouble GLdouble GLdouble r
Definition: glew.h:1406
Definition: vec3d.h:63
const GfVec3d & GetAxis() const
Returns the axis of rotation.
Definition: rotation.h:122
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:83
GF_API GfVec3d Decompose(const GfVec3d &axis0, const GfVec3d &axis1, const GfVec3d &axis2) const
Definition: quatd.h:60
static GF_API GfRotation RotateOntoProjected(const GfVec3d &v1, const GfVec3d &v2, const GfVec3d &axis)
const GfVec3d & GetImaginary() const
Returns the imaginary part of the quaternion.
Definition: quaternion.h:90
GLfloat GLfloat v1
Definition: glew.h:1852
#define GF_API
Definition: api.h:40
double GetAngle() const
Returns the rotation angle in degrees.
Definition: rotation.h:127