1 // Copyright (C) 2006 Mathias Froehlich - Mathias.Froehlich@web.de
3 // This library is free software; you can redistribute it and/or
4 // modify it under the terms of the GNU Library General Public
5 // License as published by the Free Software Foundation; either
6 // version 2 of the License, or (at your option) any later version.
8 // This library is distributed in the hope that it will be useful,
9 // but WITHOUT ANY WARRANTY; without even the implied warranty of
10 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 // Library General Public License for more details.
13 // You should have received a copy of the GNU General Public License
14 // along with this program; if not, write to the Free Software
15 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
32 struct SGQuatStorage {
33 /// Readonly raw storage interface
34 const T (&data(void) const)[4]
36 /// Readonly raw storage interface
48 struct SGQuatStorage<double> : public osg::Quat {
49 /// Access raw data by index, the index is unchecked
50 const double (&data(void) const)[4]
51 { return osg::Quat::_v; }
52 /// Access raw data by index, the index is unchecked
53 double (&data(void))[4]
54 { return osg::Quat::_v; }
56 const osg::Quat& osg() const
64 class SGQuat : protected SGQuatStorage<T> {
68 /// Default constructor. Does not initialize at all.
69 /// If you need them zero initialized, SGQuat::zeros()
72 /// Initialize with nans in the debug build, that will guarantee to have
73 /// a fast uninitialized default constructor in the release but shows up
74 /// uninitialized values in the debug build very fast ...
76 for (unsigned i = 0; i < 4; ++i)
77 data()[i] = SGLimits<T>::quiet_NaN();
80 /// Constructor. Initialize by the given values
81 SGQuat(T _x, T _y, T _z, T _w)
82 { x() = _x; y() = _y; z() = _z; w() = _w; }
83 /// Constructor. Initialize by the content of a plain array,
84 /// make sure it has at least 4 elements
85 explicit SGQuat(const T* d)
86 { data()[0] = d[0]; data()[1] = d[1]; data()[2] = d[2]; data()[3] = d[3]; }
87 explicit SGQuat(const osg::Quat& d)
88 { data()[0] = d[0]; data()[1] = d[1]; data()[2] = d[2]; data()[3] = d[3]; }
90 /// Return a unit quaternion
91 static SGQuat unit(void)
92 { return fromRealImag(1, SGVec3<T>(0)); }
94 /// Return a quaternion from euler angles
95 static SGQuat fromEulerRad(T z, T y, T x)
98 T zd2 = T(0.5)*z; T yd2 = T(0.5)*y; T xd2 = T(0.5)*x;
99 T Szd2 = sin(zd2); T Syd2 = sin(yd2); T Sxd2 = sin(xd2);
100 T Czd2 = cos(zd2); T Cyd2 = cos(yd2); T Cxd2 = cos(xd2);
101 T Cxd2Czd2 = Cxd2*Czd2; T Cxd2Szd2 = Cxd2*Szd2;
102 T Sxd2Szd2 = Sxd2*Szd2; T Sxd2Czd2 = Sxd2*Czd2;
103 q.w() = Cxd2Czd2*Cyd2 + Sxd2Szd2*Syd2;
104 q.x() = Sxd2Czd2*Cyd2 - Cxd2Szd2*Syd2;
105 q.y() = Cxd2Czd2*Syd2 + Sxd2Szd2*Cyd2;
106 q.z() = Cxd2Szd2*Cyd2 - Sxd2Czd2*Syd2;
110 /// Return a quaternion from euler angles in degrees
111 static SGQuat fromEulerDeg(T z, T y, T x)
113 return fromEulerRad(SGMisc<T>::deg2rad(z), SGMisc<T>::deg2rad(y),
114 SGMisc<T>::deg2rad(x));
117 /// Return a quaternion from euler angles
118 static SGQuat fromYawPitchRoll(T y, T p, T r)
119 { return fromEulerRad(y, p, r); }
121 /// Return a quaternion from euler angles
122 static SGQuat fromYawPitchRollDeg(T y, T p, T r)
123 { return fromEulerDeg(y, p, r); }
125 /// Return a quaternion from euler angles
126 static SGQuat fromHeadAttBank(T h, T a, T b)
127 { return fromEulerRad(h, a, b); }
129 /// Return a quaternion from euler angles
130 static SGQuat fromHeadAttBankDeg(T h, T a, T b)
131 { return fromEulerDeg(h, a, b); }
133 /// Return a quaternion rotation the the horizontal local frame from given
134 /// longitude and latitude
135 static SGQuat fromLonLatRad(T lon, T lat)
139 T yd2 = T(-0.25)*SGMisc<value_type>::pi() - T(0.5)*lat;
151 /// Return a quaternion rotation the the horizontal local frame from given
152 /// longitude and latitude
153 static SGQuat fromLonLatDeg(T lon, T lat)
154 { return fromLonLatRad(SGMisc<T>::deg2rad(lon), SGMisc<T>::deg2rad(lat)); }
156 /// Return a quaternion rotation the the horizontal local frame from given
157 /// longitude and latitude
158 static SGQuat fromLonLat(const SGGeod& geod)
159 { return fromLonLatRad(geod.getLongitudeRad(), geod.getLatitudeRad()); }
161 /// Create a quaternion from the angle axis representation
162 static SGQuat fromAngleAxis(T angle, const SGVec3<T>& axis)
164 T angle2 = 0.5*angle;
165 return fromRealImag(cos(angle2), T(sin(angle2))*axis);
168 /// Create a quaternion from the angle axis representation
169 static SGQuat fromAngleAxisDeg(T angle, const SGVec3<T>& axis)
170 { return fromAngleAxis(SGMisc<T>::deg2rad(angle), axis); }
172 /// Create a quaternion from the angle axis representation where the angle
173 /// is stored in the axis' length
174 static SGQuat fromAngleAxis(const SGVec3<T>& axis)
176 T nAxis = norm(axis);
177 if (nAxis <= SGLimits<T>::min())
178 return SGQuat(1, 0, 0, 0);
179 T angle2 = 0.5*nAxis;
180 return fromRealImag(cos(angle2), T(sin(angle2)/nAxis)*axis);
183 /// Return a quaternion from real and imaginary part
184 static SGQuat fromRealImag(T r, const SGVec3<T>& i)
194 /// Return an all zero vector
195 static SGQuat zeros(void)
196 { return SGQuat(0, 0, 0, 0); }
198 /// write the euler angles into the references
199 void getEulerRad(T& zRad, T& yRad, T& xRad) const
201 value_type sqrQW = w()*w();
202 value_type sqrQX = x()*x();
203 value_type sqrQY = y()*y();
204 value_type sqrQZ = z()*z();
206 value_type num = 2*(y()*z() + w()*x());
207 value_type den = sqrQW - sqrQX - sqrQY + sqrQZ;
208 if (fabs(den) < SGLimits<value_type>::min() &&
209 fabs(num) < SGLimits<value_type>::min())
212 xRad = atan2(num, den);
214 value_type tmp = 2*(x()*z() - w()*y());
216 yRad = 0.5*SGMisc<value_type>::pi();
218 yRad = -0.5*SGMisc<value_type>::pi();
222 num = 2*(x()*y() + w()*z());
223 den = sqrQW + sqrQX - sqrQY - sqrQZ;
224 if (fabs(den) < SGLimits<value_type>::min() &&
225 fabs(num) < SGLimits<value_type>::min())
228 value_type psi = atan2(num, den);
230 psi += 2*SGMisc<value_type>::pi();
235 /// write the euler angles in degrees into the references
236 void getEulerDeg(T& zDeg, T& yDeg, T& xDeg) const
238 getEulerRad(zDeg, yDeg, xDeg);
239 zDeg = SGMisc<T>::rad2deg(zDeg);
240 yDeg = SGMisc<T>::rad2deg(yDeg);
241 xDeg = SGMisc<T>::rad2deg(xDeg);
244 /// write the angle axis representation into the references
245 void getAngleAxis(T& angle, SGVec3<T>& axis) const
248 if (nrm < SGLimits<T>::min()) {
250 axis = SGVec3<T>(0, 0, 0);
253 angle = acos(SGMisc<T>::max(-1, SGMisc<T>::min(1, rNrm*w())));
255 if (fabs(sAng) < SGLimits<T>::min())
256 axis = SGVec3<T>(1, 0, 0);
258 axis = (rNrm/sAng)*imag(*this);
263 /// write the angle axis representation into the references
264 void getAngleAxis(SGVec3<T>& axis) const
267 getAngleAxis(angle, axis);
271 /// Access by index, the index is unchecked
272 const T& operator()(unsigned i) const
273 { return data()[i]; }
274 /// Access by index, the index is unchecked
275 T& operator()(unsigned i)
276 { return data()[i]; }
278 /// Access raw data by index, the index is unchecked
279 const T& operator[](unsigned i) const
280 { return data()[i]; }
281 /// Access raw data by index, the index is unchecked
282 T& operator[](unsigned i)
283 { return data()[i]; }
285 /// Access the x component
286 const T& x(void) const
287 { return data()[0]; }
288 /// Access the x component
290 { return data()[0]; }
291 /// Access the y component
292 const T& y(void) const
293 { return data()[1]; }
294 /// Access the y component
296 { return data()[1]; }
297 /// Access the z component
298 const T& z(void) const
299 { return data()[2]; }
300 /// Access the z component
302 { return data()[2]; }
303 /// Access the w component
304 const T& w(void) const
305 { return data()[3]; }
306 /// Access the w component
308 { return data()[3]; }
310 /// Get the data pointer
311 using SGQuatStorage<T>::data;
313 /// Readonly interface function to ssg's sgQuat/sgdQuat
314 const T (&sg(void) const)[4]
316 /// Interface function to ssg's sgQuat/sgdQuat
320 /// Interface function to osg's Quat*
321 using SGQuatStorage<T>::osg;
324 SGQuat& operator+=(const SGQuat& v)
325 { data()[0]+=v(0);data()[1]+=v(1);data()[2]+=v(2);data()[3]+=v(3);return *this; }
326 /// Inplace subtraction
327 SGQuat& operator-=(const SGQuat& v)
328 { data()[0]-=v(0);data()[1]-=v(1);data()[2]-=v(2);data()[3]-=v(3);return *this; }
329 /// Inplace scalar multiplication
331 SGQuat& operator*=(S s)
332 { data()[0] *= s; data()[1] *= s; data()[2] *= s; data()[3] *= s; return *this; }
333 /// Inplace scalar multiplication by 1/s
335 SGQuat& operator/=(S s)
336 { return operator*=(1/T(s)); }
337 /// Inplace quaternion multiplication
338 SGQuat& operator*=(const SGQuat& v);
340 /// Transform a vector from the current coordinate frame to a coordinate
341 /// frame rotated with the quaternion
342 SGVec3<T> transform(const SGVec3<T>& v) const
344 value_type r = 2/dot(*this, *this);
345 SGVec3<T> qimag = imag(*this);
346 value_type qr = real(*this);
347 return (r*qr*qr - 1)*v + (r*dot(qimag, v))*qimag - (r*qr)*cross(qimag, v);
349 /// Transform a vector from the coordinate frame rotated with the quaternion
350 /// to the current coordinate frame
351 SGVec3<T> backTransform(const SGVec3<T>& v) const
353 value_type r = 2/dot(*this, *this);
354 SGVec3<T> qimag = imag(*this);
355 value_type qr = real(*this);
356 return (r*qr*qr - 1)*v + (r*dot(qimag, v))*qimag + (r*qr)*cross(qimag, v);
359 /// Rotate a given vector with the quaternion
360 SGVec3<T> rotate(const SGVec3<T>& v) const
361 { return backTransform(v); }
362 /// Rotate a given vector with the inverse quaternion
363 SGVec3<T> rotateBack(const SGVec3<T>& v) const
364 { return transform(v); }
366 /// Return the time derivative of the quaternion given the angular velocity
368 derivative(const SGVec3<T>& angVel)
372 deriv.w() = 0.5*(-x()*angVel(0) - y()*angVel(1) - z()*angVel(2));
373 deriv.x() = 0.5*( w()*angVel(0) - z()*angVel(1) + y()*angVel(2));
374 deriv.y() = 0.5*( z()*angVel(0) + w()*angVel(1) - x()*angVel(2));
375 deriv.z() = 0.5*(-y()*angVel(0) + x()*angVel(1) + w()*angVel(2));
381 /// Unary +, do nothing ...
385 operator+(const SGQuat<T>& v)
388 /// Unary -, do nearly nothing
392 operator-(const SGQuat<T>& v)
393 { return SGQuat<T>(-v(0), -v(1), -v(2), -v(3)); }
399 operator+(const SGQuat<T>& v1, const SGQuat<T>& v2)
400 { return SGQuat<T>(v1(0)+v2(0), v1(1)+v2(1), v1(2)+v2(2), v1(3)+v2(3)); }
406 operator-(const SGQuat<T>& v1, const SGQuat<T>& v2)
407 { return SGQuat<T>(v1(0)-v2(0), v1(1)-v2(1), v1(2)-v2(2), v1(3)-v2(3)); }
409 /// Scalar multiplication
410 template<typename S, typename T>
413 operator*(S s, const SGQuat<T>& v)
414 { return SGQuat<T>(s*v(0), s*v(1), s*v(2), s*v(3)); }
416 /// Scalar multiplication
417 template<typename S, typename T>
420 operator*(const SGQuat<T>& v, S s)
421 { return SGQuat<T>(s*v(0), s*v(1), s*v(2), s*v(3)); }
423 /// Quaterion multiplication
427 operator*(const SGQuat<T>& v1, const SGQuat<T>& v2)
430 v.x() = v1.w()*v2.x() + v1.x()*v2.w() + v1.y()*v2.z() - v1.z()*v2.y();
431 v.y() = v1.w()*v2.y() - v1.x()*v2.z() + v1.y()*v2.w() + v1.z()*v2.x();
432 v.z() = v1.w()*v2.z() + v1.x()*v2.y() - v1.y()*v2.x() + v1.z()*v2.w();
433 v.w() = v1.w()*v2.w() - v1.x()*v2.x() - v1.y()*v2.y() - v1.z()*v2.z();
437 /// Now define the inplace multiplication
441 SGQuat<T>::operator*=(const SGQuat& v)
442 { (*this) = (*this)*v; return *this; }
444 /// The conjugate of the quaternion, this is also the
445 /// inverse for normalized quaternions
449 conj(const SGQuat<T>& v)
450 { return SGQuat<T>(-v(0), -v(1), -v(2), v(3)); }
452 /// The conjugate of the quaternion, this is also the
453 /// inverse for normalized quaternions
457 inverse(const SGQuat<T>& v)
458 { return (1/dot(v, v))*SGQuat<T>(-v(0), -v(1), -v(2), v(3)); }
460 /// The imagniary part of the quaternion
464 real(const SGQuat<T>& v)
467 /// The imagniary part of the quaternion
471 imag(const SGQuat<T>& v)
472 { return SGVec3<T>(v.x(), v.y(), v.z()); }
474 /// Scalar dot product
478 dot(const SGQuat<T>& v1, const SGQuat<T>& v2)
479 { return v1(0)*v2(0) + v1(1)*v2(1) + v1(2)*v2(2) + v1(3)*v2(3); }
481 /// The euclidean norm of the vector, that is what most people call length
485 norm(const SGQuat<T>& v)
486 { return sqrt(dot(v, v)); }
488 /// The euclidean norm of the vector, that is what most people call length
492 length(const SGQuat<T>& v)
493 { return sqrt(dot(v, v)); }
495 /// The 1-norm of the vector, this one is the fastest length function we
496 /// can implement on modern cpu's
500 norm1(const SGQuat<T>& v)
501 { return fabs(v(0)) + fabs(v(1)) + fabs(v(2)) + fabs(v(3)); }
503 /// The euclidean norm of the vector, that is what most people call length
507 normalize(const SGQuat<T>& q)
508 { return (1/norm(q))*q; }
510 /// Return true if exactly the same
514 operator==(const SGQuat<T>& v1, const SGQuat<T>& v2)
515 { return v1(0)==v2(0) && v1(1)==v2(1) && v1(2)==v2(2) && v1(3)==v2(3); }
517 /// Return true if not exactly the same
521 operator!=(const SGQuat<T>& v1, const SGQuat<T>& v2)
522 { return ! (v1 == v2); }
524 /// Return true if equal to the relative tolerance tol
525 /// Note that this is not the same than comparing quaternions to represent
526 /// the same rotation
530 equivalent(const SGQuat<T>& v1, const SGQuat<T>& v2, T tol)
531 { return norm1(v1 - v2) < tol*(norm1(v1) + norm1(v2)); }
533 /// Return true if about equal to roundoff of the underlying type
534 /// Note that this is not the same than comparing quaternions to represent
535 /// the same rotation
539 equivalent(const SGQuat<T>& v1, const SGQuat<T>& v2)
540 { return equivalent(v1, v2, 100*SGLimits<T>::epsilon()); }
546 isNaN(const SGQuat<T>& v)
548 return SGMisc<T>::isNaN(v(0)) || SGMisc<T>::isNaN(v(1))
549 || SGMisc<T>::isNaN(v(2)) || SGMisc<T>::isNaN(v(3));
553 /// quaternion interpolation for t in [0,1] interpolate between src (=0)
558 interpolate(T t, const SGQuat<T>& src, const SGQuat<T>& dst)
560 T cosPhi = dot(src, dst);
561 // need to take the shorter way ...
562 int signCosPhi = SGMisc<T>::sign(cosPhi);
563 // cosPhi must be corrected for that sign
564 cosPhi = fabs(cosPhi);
566 // first opportunity to fail - make sure acos will succeed later -
571 // now the half angle between the orientations
574 // need the scales now, if the angle is very small, do linear interpolation
575 // to avoid instabilities
577 if (fabs(o) < SGLimits<T>::epsilon()) {
581 // note that we can give a positive lower bound for sin(o) here
584 scale0 = sin((1 - t)*o)*so;
585 scale1 = sin(t*o)*so;
588 return scale0*src + signCosPhi*scale1*dst;
591 /// Output to an ostream
592 template<typename char_type, typename traits_type, typename T>
594 std::basic_ostream<char_type, traits_type>&
595 operator<<(std::basic_ostream<char_type, traits_type>& s, const SGQuat<T>& v)
596 { return s << "[ " << v(0) << ", " << v(1) << ", " << v(2) << ", " << v(3) << " ]"; }
600 toQuatf(const SGQuatd& v)
601 { return SGQuatf((float)v(0), (float)v(1), (float)v(2), (float)v(3)); }
605 toQuatd(const SGQuatf& v)
606 { return SGQuatd(v(0), v(1), v(2), v(3)); }