This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
quaternion.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_QUATERNION_H
8#define PXR_BASE_GF_QUATERNION_H
9
12
13#include "pxr/pxr.h"
14#include "pxr/base/gf/api.h"
15#include "pxr/base/gf/vec3d.h"
16#include "pxr/base/tf/hash.h"
17
18#include <iosfwd>
19
20PXR_NAMESPACE_OPEN_SCOPE
21
33{
34 public:
35
38 }
39
46 explicit GfQuaternion(int realVal)
47 : _real(realVal), _imaginary(0)
48 {
49 }
50
52 GfQuaternion(double real, const GfVec3d &imaginary)
53 : _real(real), _imaginary(imaginary) {
54 }
55
57 void SetReal(double real) {
58 _real = real;
59 }
60
62 void SetImaginary(const GfVec3d &imaginary) {
63 _imaginary = imaginary;
64 }
65
67 double GetReal() const {
68 return _real;
69 }
70
72 const GfVec3d & GetImaginary() const {
73 return _imaginary;
74 }
75
79 return GfQuaternion(0.0, GfVec3d(0.0, 0.0, 0.0));
80 }
81
85 return GfQuaternion(1.0, GfVec3d(0.0, 0.0, 0.0));
86 }
87
89 GF_API
90 double GetLength() const;
91
95 GF_API
97
101 GF_API
102 double Normalize(double eps = GF_MIN_VECTOR_LENGTH);
103
105 GF_API
107
109 friend inline size_t hash_value(const GfQuaternion &q) {
110 return TfHash::Combine(q.GetReal(), q.GetImaginary());
111 }
112
115 bool operator ==(const GfQuaternion &q) const {
116 return (GetReal() == q.GetReal() &&
117 GetImaginary() == q.GetImaginary());
118 }
119
122 bool operator !=(const GfQuaternion &q) const {
123 return ! (*this == q);
124 }
125
127 GF_API
129
131 GF_API
133
136 return (*this) *= 1.0 / s;
137 }
138
141 _real += q._real;
142 _imaginary += q._imaginary;
143 return *this;
144 }
145
148 _real -= q._real;
149 _imaginary -= q._imaginary;
150 return *this;
151 }
152
155 const GfQuaternion &q2) {
156 GfQuaternion qt = q1;
157 return qt += q2;
158 }
159
162 const GfQuaternion &q2) {
163 GfQuaternion qt = q1;
164 return qt -= q2;
165 }
166
169 const GfQuaternion &q2) {
170 GfQuaternion qt = q1;
171 return qt *= q2;
172 }
173
175 friend GfQuaternion operator *(const GfQuaternion &q, double s) {
176 GfQuaternion qt = q;
177 return qt *= s;
178 }
179
181 friend GfQuaternion operator *(double s, const GfQuaternion &q) {
182 GfQuaternion qt = q;
183 return qt *= s;
184 }
185
187 friend GfQuaternion operator /(const GfQuaternion &q, double s) {
188 GfQuaternion qt = q;
189 return qt /= s;
190 }
191
197 GF_API
198 friend GfQuaternion GfSlerp(double alpha,
199 const GfQuaternion& q0,
200 const GfQuaternion& q1);
201
202 // TODO Remove this legacy alias/overload.
203 friend GF_API GfQuaternion GfSlerp(const GfQuaternion& q0,
204 const GfQuaternion& q1,
205 double alpha);
206
207 private:
209 double _real;
211 GfVec3d _imaginary;
212
214 double _GetLengthSquared() const {
215 return (_real * _real + GfDot(_imaginary, _imaginary));
216 }
217};
218
219// Friend functions must be declared.
220GF_API GfQuaternion GfSlerp(double alpha, const GfQuaternion& q0, const GfQuaternion& q1);
221GF_API GfQuaternion GfSlerp(const GfQuaternion& q0, const GfQuaternion& q1, double alpha);
222
225GF_API std::ostream& operator<<(std::ostream& out, const GfQuaternion& q);
226
227
229inline double
230GfDot(const GfQuaternion &q1, const GfQuaternion &q2) {
231 return (q1.GetReal() * q2.GetReal()) + GfDot(q1.GetImaginary(), q2.GetImaginary());
232}
233
234PXR_NAMESPACE_CLOSE_SCOPE
235
236#endif // PXR_BASE_GF_QUATERNION_H
Basic type: complex number with scalar real part and vector imaginary part.
Definition: quaternion.h:33
static GfQuaternion GetZero()
Returns the zero quaternion, which has a real part of 0 and an imaginary part of (0,...
Definition: quaternion.h:78
GfQuaternion(int realVal)
This constructor initializes the real part to the argument and the imaginary parts to zero.
Definition: quaternion.h:46
GfQuaternion & operator/=(double s)
Scales this quaternion by 1 / s.
Definition: quaternion.h:135
friend GfQuaternion operator-(const GfQuaternion &q1, const GfQuaternion &q2)
Component-wise binary difference operator.
Definition: quaternion.h:161
GfQuaternion(double real, const GfVec3d &imaginary)
This constructor initializes the real and imaginary parts.
Definition: quaternion.h:52
friend size_t hash_value(const GfQuaternion &q)
Hash.
Definition: quaternion.h:109
const GfVec3d & GetImaginary() const
Returns the imaginary part of the quaternion.
Definition: quaternion.h:72
GF_API double Normalize(double eps=GF_MIN_VECTOR_LENGTH)
Normalizes this quaternion in place to unit length, returning the length before normalization.
static GfQuaternion GetIdentity()
Returns the identity quaternion, which has a real part of 1 and an imaginary part of (0,...
Definition: quaternion.h:84
bool operator!=(const GfQuaternion &q) const
Component-wise quaternion inequality test.
Definition: quaternion.h:122
double GetReal() const
Returns the real part of the quaternion.
Definition: quaternion.h:67
bool operator==(const GfQuaternion &q) const
Component-wise quaternion equality test.
Definition: quaternion.h:115
GfQuaternion & operator-=(const GfQuaternion &q)
Component-wise unary difference operator.
Definition: quaternion.h:147
GF_API GfQuaternion & operator*=(const GfQuaternion &q)
Post-multiplies quaternion q into this quaternion.
friend GfQuaternion operator*(const GfQuaternion &q1, const GfQuaternion &q2)
Returns the product of quaternions q1 and q2.
Definition: quaternion.h:168
void SetImaginary(const GfVec3d &imaginary)
Sets the imaginary part of the quaternion.
Definition: quaternion.h:62
GfQuaternion()
The default constructor leaves the quaternion undefined.
Definition: quaternion.h:37
GfQuaternion & operator+=(const GfQuaternion &q)
Component-wise unary sum operator.
Definition: quaternion.h:140
friend GfQuaternion operator/(const GfQuaternion &q, double s)
Returns the product of quaternion q and scalar 1 / s.
Definition: quaternion.h:187
GF_API friend GfQuaternion GfSlerp(double alpha, const GfQuaternion &q0, const GfQuaternion &q1)
Spherically interpolate between q0 and q1.
friend GfQuaternion operator+(const GfQuaternion &q1, const GfQuaternion &q2)
Component-wise binary sum operator.
Definition: quaternion.h:154
GF_API double GetLength() const
Returns geometric length of this quaternion.
void SetReal(double real)
Sets the real part of the quaternion.
Definition: quaternion.h:57
GF_API GfQuaternion GetNormalized(double eps=GF_MIN_VECTOR_LENGTH) const
Returns a normalized (unit-length) version of this quaternion.
GF_API GfQuaternion GetInverse() const
Returns the inverse of this quaternion.
Basic type for a vector of 3 double components.
Definition: vec3d.h:46
static size_t Combine(Args &&... args)
Produce a hash code by combining the hash codes of several objects.
Definition: hash.h:475
#define GF_MIN_VECTOR_LENGTH
This constant is used to determine whether the length of a vector is too small to handle accurately.
Definition: limits.h:17
GF_API std::ostream & operator<<(std::ostream &, const GfBBox3d &)
Output a GfBBox3d using the format [(range) matrix zeroArea].
double GfDot(const GfQuaternion &q1, const GfQuaternion &q2)
Returns the dot (inner) product of two quaternions.
Definition: quaternion.h:230
GF_API GfQuaternion GfSlerp(double alpha, const GfQuaternion &q0, const GfQuaternion &q1)