-
Notifications
You must be signed in to change notification settings - Fork 29
Using quaternions
There are a few different ways of constructing a quaternion.
Initializing a quaternion without any additional arguments will set the scalar part (w) to 1 and the vector parts (x, y, z) to 0 (of the respective type).
Example:
quat() # returns quaternion (1 + 0i + 0j + 0k), where i, j and k are imaginary numbersNote: The component order of quaternions were inconsistent in PyGLM versions prior to 2.0.0.
A quaternion can be initialized with 4 numbers, which will be copied (or may be converted) to their components.
Example:
quat(1, 2, 3, 4) # returns quaternion (1 + 2i + 3j + 4k)A copy of a quaternion can be obtained by initializing a quaternion with another instance of a quaternion.
I.e. quat(quat(1, 2, 3, 4)) returns quaternion (1 + 2i + 3j + 4k)
This is what's known as the copy constructor.
To convert a quaternion from one data type to another, the target data type can simply be initialized with the source.
>>> quat(dquat(1, 2, 3, 4))
quat( 1, 2, 3, 4 )Note: This feature may not be available in PyGLM versions prior to 2.0.0
You can initialize the scalar part (w) of the quaternion with a number and the vector part (x, y, z) with a vec3 (or dvec3 respectively).
Example:
quat(1, vec3(2, 3, 4)) # returns quaternion (1 + 2i + 3j + 4k)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:
>>> 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 differencesYou can create a quaternion from a single vec3, containing 3 angles known as euler angles.
They have the following structure: vec3(pitch, yaw, roll), where each angle is a radian value.
- Pitch is the rotation arount the X-axis
- Yaw is the rotation arount the Y-axis
- Roll is the rotation arount the Z-axis
Example:
>>> 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.000000834826057You 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.
Instead of using quaternions, vectors or matrices to initialize vectors, you can also use lists and other iterables.
In most cases, (1, 2, 3) will be interpreted as a vec3(1, 2, 3) of a fitting type.
(1, 2, 3, 4) may be interpreted as a vec4(1, 2, 3, 4) or a quat(1, 2, 3, 4), depending on the circumstances - though usually the vector representation is preferred.
((1, 2), (3, 4)) will be interpreted as a mat2(1, 2, 3, 4).
Note: This feature may not be supported on PyGLM versions prior to 2.0.0, so please handle with care.
A few objects in Python support a functionality called the buffer protocol.
One such example would be the Python bytes type or numpy.array.
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. numpy.array(glm.quat(1, 2, 3, 4)) returns array([1., 2., 3., 4.], dtype=float32)
and glm.quat(numpy.array([1., 2., 3., 4.], dtype="float32")) returns quat(1, 2, 3, 4).
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.
A quaternion has a member for each of it's components.
| Member | Description |
|---|---|
| w | The scalar part |
| x | The first vector part |
| y | The second vector part |
| z | The last vector part |
Quaternions do not support swizzling.
Any quaternion type implements the following methods:
| 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 |
Quaternions support the copy protocol (see here).
You can use copy.copy(<quat>) or copy.deepcopy(<quat>) to get a copy of a quaternion.
Quaternions support pickling (as of PyGLM 2.0.0), which is Python's serialization method.
Quaternions support a bunch of operators.
Quaternions support component-wise addition with other quaternions.
sum = quat(1, 2, 3, 4) + quat(5, 6, 7, 8) # returns quat(6, 8, 10, 12)Quaternions support component-wise subtraction with other quaternions.
diff = quat(1, 2, 3, 4) + quat(5, 6, 7, 8) # returns quat(-4, -4, -4, -4)Quaternions support multiplication with other quaternions, vectors and scalars.
Multiplying two quaternions will return their cross product.
The cross product of quat(s1, v1) and quat(s2, v2) (with v1 and v2 being length 3 vectors) is defined as:
quat(
s1 * s2 - dot(v1, v2),
s1 * v2 + s2 * v1 + cross(v1, v2)
)Example:
>>> 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 )Multiplying a quaternion with a scalar will scale each component by the given number.
>>> quat(1, 2, 3, 4) * 2
quat( 2, 4, 6, 8 )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.
>>> 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 )Has the same effects as the * operator, but with the arguments switched.
I.e. a * b == b @ a
Quaternions support component wise, right handside division with scalars (numbers).
quot1 = quat(1, 2, 3, 4) / 2 # returns quat(0.5, 1, 1.5, 2)The length of a quaternion (always 4) can be queried using len().
quat_length = len(quat()) # returns 4You can get the values of a quaternion using indices.
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.0Likewise you can set the values.
q = quat(1, 2, 3, 4)
q[0] = 9
print(q.w) # prints 9.0You can query wether or not a value is contained by a quaternion using the in operator.
q = quat(1, 2, 3, 4)
true = 2 in q
false = 2.01 in qYou can compare quaternions using the equality richcompare operators:
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) # TrueYou can generate an iterable from quaternions using iter().
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.0You can generate a hash value for quaternions using hash()
Example:
>>> q = quat()
>>> hash(q)
4797573974374731128
>>> q2 = quat(1, 2, 3, 4)
>>> hash(q2)
8060046874292968317