All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
rotation.h
Go to the documentation of this file.
1//
2// Copyright 2016 Pixar
3//
4// Licensed under the terms set forth in the LICENSE.txt file available at
5// https://openusd.org/license.
6//
7#ifndef PXR_BASE_GF_ROTATION_H
8#define PXR_BASE_GF_ROTATION_H
9
12
13#include "pxr/pxr.h"
15#include "pxr/base/gf/quatd.h"
17#include "pxr/base/gf/vec3d.h"
18#include "pxr/base/gf/vec3f.h"
19#include "pxr/base/gf/api.h"
20#include "pxr/base/tf/hash.h"
21
22#include <iosfwd>
23
24PXR_NAMESPACE_OPEN_SCOPE
25
38
39 public:
40
43 }
44
47 GfRotation(const GfVec3d &axis, double angle) {
48 SetAxisAngle(axis, angle);
49 }
50
52 GfRotation(const GfQuaternion &quaternion) {
53 SetQuaternion(quaternion);
54 }
55
59 GfRotation(const GfQuatd &quat) { SetQuat(quat); }
60
64 GF_API
65 GfRotation(const GfVec3d &rotateFrom, const GfVec3d &rotateTo) {
66 SetRotateInto(rotateFrom, rotateTo);
67 }
68
70 GfRotation & SetAxisAngle(const GfVec3d &axis, double angle) {
71 _axis = axis;
72 _angle = angle;
73 if (!GfIsClose(_axis * _axis, 1.0, 1e-10))
74 _axis.Normalize();
75 return *this;
76 }
77
80 GF_API
81 GfRotation & SetQuat(const GfQuatd &quat);
82
85 return SetQuat(GfQuatd(quat.GetReal(), quat.GetImaginary()));
86 }
87
91 GF_API
92 GfRotation & SetRotateInto(const GfVec3d &rotateFrom,
93 const GfVec3d &rotateTo);
94
98 _axis.Set(1.0, 0.0, 0.0);
99 _angle = 0.0;
100 return *this;
101 }
102
104 const GfVec3d & GetAxis() const {
105 return _axis;
106 }
107
109 double GetAngle() const {
110 return _angle;
111 }
112
115 auto quat = GetQuat();
116 return GfQuaternion(quat.GetReal(), quat.GetImaginary());
117 }
118
120 GF_API
122
125 return GfRotation(_axis, -_angle);
126 }
127
130 GF_API
131 GfVec3d Decompose( const GfVec3d &axis0,
132 const GfVec3d &axis1,
133 const GfVec3d &axis2 ) const;
134
135 // Full-featured method to Decompose a rotation matrix into Cardarian
136 // angles.
137 // Axes have must be normalized. If useHint is specified
138 // then the current values stored within thetaTw, thetaFB, thetaLR,
139 // and thetaSw will be treated as hint and used to help choose
140 // an equivalent rotation that is as close as possible to the hints.
141 //
142 // One can use this routine to generate any combination of the three
143 // angles by passing in nullptr for the angle that is to be omitted.
144 //
145 // Passing in valid pointers for all four angles will decompose into
146 // Tw, FB, and LR but allows Sw to be used for best matching of hint
147 // values. It also allows an swShift value to be passed in as a
148 // Sw that is applied after the rotation matrix to get a best fit rotation
149 // in four angles.
150 //
151 // Angles are in radians.
152 //
153 // Specify \p handedness as -1.0 or 1.0, same as for MultiRotate.
154 //
155 // NOTE:
156 // Geppetto math function Originally brought over to extMover
157 // from //depot/main/tools/src/menv/lib/gpt/util.h [10/16/06]
158 // And moved into GfRotation[12/1/08]. Updated for any
159 // combination of three angles [12/1/11].
160 //
161 GF_API
162 static void DecomposeRotation(const GfMatrix4d &rot,
163 const GfVec3d &TwAxis,
164 const GfVec3d &FBAxis,
165 const GfVec3d &LRAxis,
166 double handedness,
167 double *thetaTw,
168 double *thetaFB,
169 double *thetaLR,
170 double *thetaSw = nullptr,
171 bool useHint=false,
172 const double *swShift=nullptr);
173
174 // This function projects the vectors \p v1 and \p v2 onto the plane
175 // normal to \p axis, and then returns the rotation about \p axis that
176 // brings \p v1 onto \p v2.
177 GF_API
178 static GfRotation RotateOntoProjected(const GfVec3d &v1,
179 const GfVec3d &v2,
180 const GfVec3d &axis);
181
191 GF_API
193 double targetTw, double targetFB, double targetLR, double targetSw,
194 double *thetaTw, double *thetaFB, double *thetaLR, double *thetaSw);
195
197 GF_API
198 GfVec3d TransformDir( const GfVec3d &vec ) const;
199
201 friend inline size_t hash_value(const GfRotation &r) {
202 return TfHash::Combine(r._axis, r._angle);
203 }
204
209 bool operator ==(const GfRotation &r) const {
210 return (_axis == r._axis &&
211 _angle == r._angle);
212 }
213
218 bool operator !=(const GfRotation &r) const {
219 return ! (*this == r);
220 }
221
223 GF_API
225
227 GfRotation & operator *=(double scale) {
228 _angle *= scale;
229 return *this;
230 }
231
233 GfRotation & operator /=(double scale) {
234 _angle /= scale;
235 return *this;
236 }
237
240 const GfRotation &r2) {
241 GfRotation r = r1;
242 return r *= r2;
243 }
244
247 friend GfRotation operator *(const GfRotation &r, double scale) {
248 GfRotation rTmp = r;
249 return rTmp *= scale;
250 }
251
254 friend GfRotation operator *(double scale, const GfRotation &r) {
255 return (r * scale);
256 }
257
260 friend GfRotation operator /(const GfRotation &r, double scale) {
261 GfRotation rTmp = r;
262 return rTmp /= scale;
263 }
264
265 private:
268 GfVec3d _axis;
270 double _angle;
271};
272
275GF_API std::ostream& operator<<(std::ostream&, const GfRotation&);
276
277PXR_NAMESPACE_CLOSE_SCOPE
278
279#endif // PXR_BASE_GF_ROTATION_H
Stores a 4x4 matrix of double elements.
Definition: matrix4d.h:71
Basic type: a quaternion, a complex number with a real coefficient and three imaginary coefficients,...
Definition: quatd.h:43
Basic type: complex number with scalar real part and vector imaginary part.
Definition: quaternion.h:33
const GfVec3d & GetImaginary() const
Returns the imaginary part of the quaternion.
Definition: quaternion.h:72
double GetReal() const
Returns the real part of the quaternion.
Definition: quaternion.h:67
Basic type: 3-space rotation specification.
Definition: rotation.h:37
GfRotation & operator/=(double scale)
Scales rotation angle by dividing by scale.
Definition: rotation.h:233
GfRotation(const GfQuaternion &quaternion)
This constructor initializes the rotation from a quaternion.
Definition: rotation.h:52
friend GfRotation operator/(const GfRotation &r, double scale)
Returns a rotation equivalent to r with its angle divided by scale.
Definition: rotation.h:260
GF_API GfVec3d Decompose(const GfVec3d &axis0, const GfVec3d &axis1, const GfVec3d &axis2) const
Decompose rotation about 3 orthogonal axes.
const GfVec3d & GetAxis() const
Returns the axis of rotation.
Definition: rotation.h:104
GfRotation & SetQuaternion(const GfQuaternion &quat)
Sets the rotation from a quaternion.
Definition: rotation.h:84
GfRotation()
The default constructor leaves the rotation undefined.
Definition: rotation.h:42
GF_API GfVec3d TransformDir(const GfVec3d &vec) const
Transforms row vector vec by the rotation, returning the result.
GF_API GfRotation & SetRotateInto(const GfVec3d &rotateFrom, const GfVec3d &rotateTo)
Sets the rotation to one that brings the rotateFrom vector to align with rotateTo.
GF_API GfRotation(const GfVec3d &rotateFrom, const GfVec3d &rotateTo)
This constructor initializes the rotation to one that brings the rotateFrom vector to align with rota...
Definition: rotation.h:65
static GF_API void MatchClosestEulerRotation(double targetTw, double targetFB, double targetLR, double targetSw, double *thetaTw, double *thetaFB, double *thetaLR, double *thetaSw)
Replace the hint angles with the closest rotation of the given rotation to the hint.
GfRotation(const GfVec3d &axis, double angle)
This constructor initializes the rotation to be angle degrees about axis.
Definition: rotation.h:47
GF_API GfRotation & operator*=(const GfRotation &r)
Post-multiplies rotation r into this rotation.
GfRotation & SetIdentity()
Sets the rotation to an identity rotation.
Definition: rotation.h:97
GF_API GfQuatd GetQuat() const
Returns the rotation expressed as a quaternion.
double GetAngle() const
Returns the rotation angle in degrees.
Definition: rotation.h:109
GfRotation(const GfQuatd &quat)
This constructor initializes the rotation from a quaternion.
Definition: rotation.h:59
friend GfRotation operator*(const GfRotation &r1, const GfRotation &r2)
Returns composite rotation of rotations r1 and r2.
Definition: rotation.h:239
bool operator!=(const GfRotation &r) const
Component-wise rotation inequality test.
Definition: rotation.h:218
friend size_t hash_value(const GfRotation &r)
Hash.
Definition: rotation.h:201
GfQuaternion GetQuaternion() const
Returns the rotation expressed as a quaternion.
Definition: rotation.h:114
GF_API GfRotation & SetQuat(const GfQuatd &quat)
Sets the rotation from a quaternion.
bool operator==(const GfRotation &r) const
Component-wise rotation equality test.
Definition: rotation.h:209
GfRotation GetInverse() const
Returns the inverse of this rotation.
Definition: rotation.h:124
GfRotation & SetAxisAngle(const GfVec3d &axis, double angle)
Sets the rotation to be angle degrees about axis.
Definition: rotation.h:70
Basic type for a vector of 3 double components.
Definition: vec3d.h:46
GfVec3d & Set(double s0, double s1, double s2)
Set all elements with passed arguments.
Definition: vec3d.h:112
static size_t Combine(Args &&... args)
Produce a hash code by combining the hash codes of several objects.
Definition: hash.h:475
bool GfIsClose(GfColor const &c1, GfColor const &c2, double tolerance)
Tests for equality of the RGB tuple in a color with a given tolerance, returning true if the length o...
Definition: color.h:114
GF_API std::ostream & operator<<(std::ostream &, const GfBBox3d &)
Output a GfBBox3d using the format [(range) matrix zeroArea].