\h1\Using Quaternions\h1\
\lo \
\-\ \url #initialization \Initialization\ url\\list switch\
\--\ \url #initialization-with-no-arguments \with no arguments\ url\
\--\ \url #initializing-all-components-with-numbers \all components with numbers\ url\
\--\ \url #copying-a-quaternion \copying a quaternion\ url\
\--\ \url #converting-a-quaternion \converting a quaternion\ url\
\--\ \url #initializing-quaternions-with-vectors \with vectors\ url\
\---\ \url #initialization-with-a-scalar-and-a-vector \scalar and vector\ url\
\---\ \url #constructing-quaternions-from-two-vec3s \two vec3s\ url\
\---\ \url #constructing-quaternions-from-euler-angles \euler angles\ url\
\--\ \url #converting-a-mat3-or-mat4-to-a-quaternion \conversion from mat3 or mat4\ url\
\--\ \url #lists-and-other-iterables \lists (and other iterables)\ url\
\--\ \url #objects-that-support-the-buffer-protocol-numpy-bytes \buffer protocol (numpy, bytes)\ url\\list switch\
\-\ \url #members \Members\ url\
\-\ \url #methods \Methods\ url\\list switch\
\--\ \url #the-copy-protocol \The copy protocol\ url\
\--\ \url #pickling \Pickling\ url\\list switch\
\-\ \url #operators \Operators\ url\\list switch\
\--\ \url #add--operator \add\ url\
\--\ \url #sub--operator \sub\ url\
\--\ \url #mul--operator \mul\ url\
\---\ \url #quat--quat \quat * quat\ url\
\---\ \url #quat--scalar \quat * scalar\ url\
\---\ \url #quat--vec \quat * vec\ url\
\--\ \url #matmul--operator \matmul\ url\
\--\ \url #div--operator \div\ url\
\--\ \url #len \len\ url\
\--\ \url #getitem-and-setitem--operator \getitem and setitem\ url\
\--\ \url #contains-in-operator \contains\ url\
\--\ \url #richcompare-eg--operator \richcompare\ url\
\--\ \url #iter \iter\ url\
\--\ \url #hash\hash\url\
\ list\
\h2\Initialization\h2\
There are a few different ways of constructing a quaternion.  
\h4\Initialization with no arguments\h4\
Initializing a quaternion without any additional arguments will set the scalar part (\code\w\code\) to 1 and the vector parts (\code\x, y, z\code\) to 0 (of the respective type).  
Example:
\code Python \
quat() # returns quaternion (1 + 0i + 0j + 0k), where i, j and k are imaginary numbers
\code\
\i\Note: The component order of quaternions were inconsistent in PyGLM versions prior to 2.0.0.\i\
\h4\Initializing all components with numbers\h4\
A quaternion can be initialized with 4 numbers, which will be copied (or may be converted) to their components.  
Example:
\code Python \
quat(1, 2, 3, 4) # returns quaternion (1 + 2i + 3j + 4k)
\code\
\h4\Copying a quaternion\h4\
A copy of a quaternion can be obtained by initializing a quaternion with another instance of a quaternion.  
I.e. \code\quat(quat(1, 2, 3, 4))\code\ returns quaternion \code\(1 + 2i + 3j + 4k)\code\  
This is what's known as the copy constructor.
\h4\Converting a quaternion\h4\
To convert a quaternion from one data type to another, the target data type can simply be initialized with the source.
\code Python \
>>> quat(dquat(1, 2, 3, 4))
quat( 1, 2, 3, 4 )
\ code\
\i\Note: This feature may not be available in PyGLM versions prior to 2.0.0\i\
\h4\Initializing quaternions with vectors\h4\
\h5\Initialization with a scalar and a vector\h5\
You can initialize the scalar part (\code\w\code\) of the quaternion with a number and the vector part (\code\x, y, z\code\) with a \code\vec3\code\ (or \code\dvec3\code\ respectively).
Example:
\code Python \
quat(1, vec3(2, 3, 4)) # returns quaternion (1 + 2i + 3j + 4k)
\ code\
\h5\Constructing quaternions from two vec3s\h5\
You can construct a quaternion from two length 3 vectors, which will return a rotation quaternion, that equals the rotation around an orthagonal axis between first direction to the other.
Example:
\code Python \
>>> a = vec3(1, -2, 3)
>>> b = vec3(-4, 5, -6)
>>> q = quat(a, b) # rotation from b to a
>>> b_rot = b * q
>>> print(normalize(a))
vec3(  0.267261, -0.534522,  0.801784 )
>>> print(normalize(b_rot))
vec3(  0.267261, -0.534523,  0.801784 ) # there may be a few rounding differences
\ code\
\h5\Constructing quaternions from euler angles\h5\
You can create a quaternion from a single \code\vec3\code\, containing 3 angles known as euler angles.
They have the following structure: \code\vec3(pitch, yaw, roll)\code\, where each angle is a radian value.
\ul\
\-\Pitch is the rotation arount the X-axis
\-\Yaw is the rotation arount the Y-axis
\-\Roll is the rotation arount the Z-axis
\ul\
Example:
\code Python \
>>> euler_angles = radians(vec3(10, 20, 30))
>>> q = quat(euler_angles)
>>> degrees(pitch(q))
9.999998855319275
>>> degrees(yaw(q))
20.000001125733135
>>> degrees(roll(q))
30.000000834826057
\ code\
\h4\Converting a mat3 or mat4 to a quaternion\h4\
You can initialize a quaternion with a mat3x3 (or mat4x4, which will be converted to a mat3x3), to get a quaternion with the same rotational effect.
\h3\Lists (and other iterables)\h3\
Instead of using quaternions, vectors or matrices to initialize vectors, you can also use lists and other iterables.  
In most cases, \code\(1, 2, 3)\code\ will be interpreted as a \code\vec3(1, 2, 3)\code\ of a fitting type.
\code\(1, 2, 3, 4)\code\ may be interpreted as a \code\vec4(1, 2, 3, 4)\code\ or a \code\quat(1, 2, 3, 4)\code\, depending on the circumstances - though usually the vector representation is preferred.
\code\((1, 2), (3, 4))\code\ will be interpreted as a \code\mat2(1, 2, 3, 4)\code\.

\i\Note: This feature may not be supported on PyGLM versions prior to 2.0.0, so please handle with care.\i\

\h3\Objects that support the buffer protocol (numpy, bytes)\h3\
A few objects in Python support a functionality called the buffer protocol.  
One such example would be the Python \code\bytes\code\ type or \code\numpy.array\code\.  
PyGLM also supports this protocol and thus can be converted to or from any other object that supports it, granted it's in a fitting format.  
E.g. \code\numpy.array(glm.quat(1, 2, 3, 4))\code\ returns \code\array([1., 2., 3., 4.], dtype=float32)\code\  
and \code\glm.quat(numpy.array([1., 2., 3., 4.], dtype="float32"))\code\ returns \code\quat(1, 2, 3, 4)\code\.

\i\Note: objects that use the buffer protocol may request a reference instead of a copy of the object, meaning that if you change the 'copy', you'll also change the original.\i\  

\h2\Members\h2\
A quaternion has a member for each of it's components.  
\tbl\
Member\-\Description
w\-\The scalar part
x\-\The first vector part
y\-\The second vector part
z\-\The last vector part
\tbl\

Quaternions do not support swizzling.

\h2\Methods\h2\
Any quaternion type implements the following methods:

\tbl\
Method\-\Description
to_list\-\Returns a list containing each component of the quaternion
to_tuple\-\Returns a tuple containing each component of the quaternion
to_bytes\-\Returns the data of the quaternion as a bytes string
from_bytes\-\(static) Creates a quaternion from a bytes string
\tbl\

\h3\The copy protocol\h3\
Quaternions support the copy protocol (see \url https://docs.python.org/3/library/copy.html \here\ url\).  
You can use \code\copy.copy(<quat>)\code\ or \code\copy.deepcopy(<quat>)\code\ to get a copy of a quaternion.

\h3\Pickling\h3\
Quaternions support \url https://docs.python.org/3/library/pickle.html#module-interface \pickling\url\ (as of PyGLM 2.0.0), which is Python's serialization method.

\h2\Operators\h2\
Quaternions support a bunch of operators.
\h3\add (\code\+\code\ operator)\h3\
Quaternions support component-wise addition with other quaternions.  
\code Python \
sum = quat(1, 2, 3, 4) + quat(5, 6, 7, 8) # returns quat(6, 8, 10, 12)
\ code\
\h3\sub (\code\-\code\ operator)\h3\
Quaternions support component-wise subtraction with other quaternions.  
\code Python \
diff = quat(1, 2, 3, 4) + quat(5, 6, 7, 8) # returns quat(-4, -4, -4, -4)
\ code\
\h3\mul (\code\*\code\ operator)\h3\
Quaternions support multiplication with other quaternions, vectors and scalars.  

\h5\quat * quat\h5\
Multiplying two quaternions will return their cross product.
The cross product of \code\quat(s1, v1)\code\ and \code\quat(s2, v2)\code\ (with v1 and v2 being length 3 vectors) is defined as:
\code Python\
quat(
	s1 * s2 - dot(v1, v2),
	s1 * v2 + s2 * v1 + cross(v1, v2)
)
\code\
Example:
\code Python \
>>> quat(1, 2, 3, 4) * quat(5, 6, 7, 8)
quat( -60, 12, 30, 24 )
>>> cross(quat(1, 2, 3, 4), quat(5, 6, 7, 8))
quat( -60, 12, 30, 24 )
\ code\

\h5\quat * scalar\h5\
Multiplying a quaternion with a scalar will scale each component by the given number.
\code Python\
>>> quat(1, 2, 3, 4) * 2
quat( 2, 4, 6, 8 )
\code\

\h5\quat * vec\h5\
Multiplying a quaternion by a vector (vec3 or vec4) will return a rotated vector.
If the vector is on the left side of the equasion, the result will be a vector rotated by the inverse of the quaternion.
\code Python\
>>> q = quat(radians(vec3(0,90,0))) # yaw = 90°
>>> v = vec3(1,0,0)
>>> q * v
vec3( 5.96046e-08, 0, -1 )
>>> v * q
vec3( -1.19209e-07, 0, 1 )
\code\
\h3 \matmul (\code\@\code\ operator)\ h3\
Has the same effects as the \code\*\code\ operator, but with the arguments switched.
I.e. \code\a * b == b @ a\code\
\h3\div (\code\/\code\ operator)\h3\
Quaternions support component wise, right handside division with scalars (numbers).  
\code Python \
quot1 = quat(1, 2, 3, 4) / 2 # returns quat(0.5, 1, 1.5, 2)
\ code\
\h3\len\h3\
The length of a quaternion (always 4) can be queried using \code\len()\code\.
\code Python \
quat_length = len(quat()) # returns 4
\ code\
\h3\getitem and setitem (\code\[]\code\ operator)\h3\
You can get the values of a quaternion using indices.
\code Python \
q = quat(1, 2, 3, 4)
print(q[0]) # prints 1.0
print(q[1]) # prints 2.0
print(q[2]) # prints 3.0
print(q[3]) # prints 4.0
\ code\
Likewise you can set the values.
\code Python \
q    = quat(1, 2, 3, 4)
q[0] = 9
print(q.w) # prints 9.0
\ code\
\h3\contains (\code\in\code\ operator)\h3\
You can query wether or not a value is contained by a quaternion using the \code\in\code\ operator.
\code Python \
q     = quat(1, 2, 3, 4)
true  = 2    in q
false = 2.01 in q
\ code\
\h3\richcompare (e.g. \code\==\code\ operator)\h3\
You can compare quaternions using the equality richcompare operators:
\code Python \
quat(1, 0, 0, 0) == quat()            # True
quat(1, 2, 3, 4) == dquat(1, 2, 3, 4) # False
quat(1, 2, 3, 4) == vec4(1, 2, 3, 4)  # False

vec2(1, 2) != vec2(1, 2)    # False
vec2(1, 2) != vec2(2, 2)    # True
vec2(1, 2) != vec3(1, 2, 3) # True
\ code\
\h3\iter\h3\
You can generate an iterable from quaternions using \code\iter()\code\.
\code Python \
q  = quat(1, 2, 3, 4)
it = iter(q)
print(next(it)) # prints 1.0
print(next(it)) # prints 2.0
print(next(it)) # prints 3.0
print(next(it)) # prints 4.0
\ code\

\h3\hash\h3\
You can generate a hash value for quaternions using \code\hash()\code\
Example:
\code Python\
>>> q = quat()
>>> hash(q)
4797573974374731128
>>> q2 = quat(1, 2, 3, 4)
>>> hash(q2)
8060046874292968317
\code\