include/assimp/quaternion.h

0001 /*
0002 Open Asset Import Library (assimp)
0003 ----------------------------------------------------------------------
0004
0005 Copyright (c) 2006-2024, assimp team
0006
0007 All rights reserved.
0008
0009 Redistribution and use of this software in source and binary forms,
0010 with or without modification, are permitted provided that the
0011 following conditions are met:
0012
0013 * Redistributions of source code must retain the above
0014   copyright notice, this list of conditions and the
0015   following disclaimer.
0016
0017 * Redistributions in binary form must reproduce the above
0018   copyright notice, this list of conditions and the
0019   following disclaimer in the documentation and/or other
0020   materials provided with the distribution.
0021
0022 * Neither the name of the assimp team, nor the names of its
0023   contributors may be used to endorse or promote products
0024   derived from this software without specific prior
0025   written permission of the assimp team.
0026
0027 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
0028 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
0029 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
0030 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
0031 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
0032 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
0033 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
0034 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
0035 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
0036 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
0037 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
0038 ----------------------------------------------------------------------
0039 */
0040
0041 /** @file quaternion.h
0042  *  @brief Quaternion structure, including operators when compiling in C++
0043  */
0044 #pragma once
0045 #ifndef AI_QUATERNION_H_INC
0046 #define AI_QUATERNION_H_INC
0047
0048 #include <assimp/defs.h>
0049
0050 #ifdef __cplusplus
0051
0052 #ifdef __GNUC__
0053 #   pragma GCC system_header
0054 #endif
0055
0056 // Forward declarations
0057 template <typename TReal> class aiVector3t;
0058 template <typename TReal> class aiMatrix3x3t;
0059 template <typename TReal> class aiMatrix4x4t;
0060
0061 // ---------------------------------------------------------------------------
0062 /**
0063  *  @brief  This class represents a quaternion as a 4D vector.
0064  */
0065 template <typename TReal>
0066 class aiQuaterniont {
0067 public:
0068     aiQuaterniont() AI_NO_EXCEPT : w(1.0), x(), y(), z() {}
0069     aiQuaterniont(TReal pw, TReal px, TReal py, TReal pz)
0070         : w(pw), x(px), y(py), z(pz) {}
0071
0072     /**
0073      *  @brief  Construct from rotation matrix. Result is undefined if the matrix is not orthonormal.
0074      */
0075     explicit aiQuaterniont( const aiMatrix3x3t<TReal>& pRotMatrix);
0076
0077     /** Construct from euler angles */
0078     aiQuaterniont( TReal roty, TReal rotz, TReal rotx);
0079
0080     /** Construct from an axis-angle pair */
0081     aiQuaterniont( aiVector3t<TReal> axis, TReal angle);
0082
0083     /** Construct from a normalized quaternion stored in a vec3 */
0084     explicit aiQuaterniont( aiVector3t<TReal> normalized);
0085
0086     /** Returns a matrix representation of the quaternion */
0087     aiMatrix3x3t<TReal> GetMatrix() const;
0088
0089     bool operator== (const aiQuaterniont& o) const;
0090     bool operator!= (const aiQuaterniont& o) const;
0091
0092     // transform vector by matrix
0093     aiQuaterniont& operator *= (const aiMatrix4x4t<TReal>& mat);
0094
0095     bool Equal(const aiQuaterniont &o, TReal epsilon = ai_epsilon) const;
0096
0097     /**
0098      *  @brief  Will normalize the quaternion representation.
0099      */
0100     aiQuaterniont& Normalize();
0101
0102     /**
0103      *  @brief  Will compute the quaternion conjugate. The result will be stored in the instance.
0104      */
0105     aiQuaterniont& Conjugate();
0106
0107     /**
0108      *  @brief  Rotate a point by this quaternion
0109      */
0110     aiVector3t<TReal> Rotate(const aiVector3t<TReal>& in) const;
0111
0112     /**
0113      *  @brief Multiply two quaternions
0114      *  @param  two   The other quaternion.
0115      *  @return The result of the multiplication.
0116      */
0117     aiQuaterniont operator * (const aiQuaterniont& two) const;
0118
0119     /**
0120      * @brief Performs a spherical interpolation between two quaternions and writes the result into the third.
0121      * @param pOut Target object to received the interpolated rotation.
0122      * @param pStart Start rotation of the interpolation at factor == 0.
0123      * @param pEnd End rotation, factor == 1.
0124      * @param pFactor Interpolation factor between 0 and 1. Values outside of this range yield undefined results.
0125      */
0126     static void Interpolate( aiQuaterniont& pOut, const aiQuaterniont& pStart,
0127         const aiQuaterniont& pEnd, TReal pFactor);
0128
0129     //! w,x,y,z components of the quaternion
0130     TReal w, x, y, z;
0131 } ;
0132
0133 using aiQuaternion = aiQuaterniont<ai_real>;
0134
0135 #else
0136
0137 struct aiQuaternion {
0138     ai_real w, x, y, z;
0139 };
0140
0141 #endif
0142
0143 #endif // AI_QUATERNION_H_INC