Orientation Conversions

A Tour of Rotation Representations

Before we dive into code, it's important to understand the conceptual landscape. Each method of representing orientation has distinct advantages and disadvantages, making them suitable for different tasks.

To summarize the key players:

• Rotation Matrix: A 3x3 (or the upper-left of a 4x4) matrix. Great for applying rotations to vectors and for hardware APIs like OpenGL, but they are memory-intensive (9 floats) and can suffer from numerical drift ("matrix creep"), causing objects to deform over time.
• Axis-Angle: The most intuitive representation, defined by a unit vector $\hat{n}$ for the axis and a scalar angle $\theta$. It's the physical reality of how rotations happen.
• Euler Angles: Three angles (e.g., heading, pitch, bank) that represent sequential rotations around cardinal axes. They are easy for humans to understand and author, making them great for level editors or user input, but they suffer from Gimbal lock and are problematic for interpolation.
• Quaternions: A four-component number ($w,x,y,z$) that elegantly avoids the problems of both matrices and Euler angles. They are compact, easy to normalize (preventing creep), and free from Gimbal lock, making them the standard choice for representing orientation internally in a physics engine.

Implementing the Conversion Functions

Now, let's build the bridges between these representations. Your task is to implement a set of conversion functions within your math library. For each conversion, I will provide the core formulas and point you to resources with detailed derivations and implementation code.

First, let's define the quaternion struct you'll be working with. It's similar to a vec4, but we'll give it named components for clarity.

struct quaternion {
    union {
        struct {
            float x, y, z, w;
        };
        float elements[4];
    };
};

1. Axis-Angle $\leftrightarrow$ Rotation Matrix

This conversion path connects the most intuitive representation to the most practical one for transforming vectors. The mathematical basis for this is Rodrigues' rotation formula.

From Axis-Angle to Matrix:
Given an axis $\hat{n}=(n_x,n_y,n_z)$ and an angle $\theta$, the corresponding 3x3 rotation matrix $R$ is:

You can implement a function mat4_from_axis_angle(vec3 axis, float angle) that computes this 3x3 matrix and places it into the upper-left of a mat4 identity matrix.

From Matrix to Axis-Angle:
This is the reverse process. Given a rotation matrix $R$, we can find $\theta$ and $\hat{n}$.
The angle is found from the trace (the sum of the diagonal elements) of the matrix:
$\theta =\arccos \left(\frac{\mathrm{Tr}(R)-1}{2}\right)$
The axis components are found from the off-diagonal elements:

You'll need to handle the special cases where $\theta =0$ (identity matrix, any axis is fine) and $\theta =\pi$ (where $\sin \theta =0$). The resource below details how to handle these cases robustly.

2. Quaternion $\leftrightarrow$ Rotation Matrix

This is the most important conversion path for a physics engine, as you will store orientation in quaternions but need matrices for rendering and vector transformation.

From Quaternion to Matrix:
Given a quaternion $q=(x,y,z,w)$, the equivalent 3x3 rotation matrix is:

Implement a function mat4_from_quaternion(quaternion q).

From Matrix to Quaternion:
This direction requires a bit more care to maintain numerical stability. The best approach involves checking which component of the quaternion will be the largest and using a different formula for each case to avoid division by small numbers.

3. Quaternion $\leftrightarrow$ Axis-Angle

This conversion highlights the geometric nature of a quaternion.

From Axis-Angle to Quaternion:
This is the fundamental definition of a rotation quaternion. For an axis $\hat{n}=(n_x,n_y,n_z)$ and angle $\theta$:

A great way to structure this is as a constructor or factory function for your quaternion type.

From Quaternion to Axis-Angle:
This is the reverse of the above. For a quaternion $q=(x,y,z,w)$:

Again, you must handle the case where $w=1$ (or is very close), which means $\theta =0$. In this case, the axis is undefined and can be set to any unit vector.

4. Conversions Involving Euler Angles

Since Euler angles are so common for user input, you'll need a way to get them into and out of your engine's internal quaternion format. The most efficient way is to convert directly, rather than going through a matrix.

Visualizing Your Work

With your conversion functions implemented, use your debug-drawing system to verify them.

1. Define an orientation using Euler angles (e.g., heading=0, pitch=45, bank=0).
2. Convert these Euler angles to a quaternion using your new function.
3. Convert the quaternion to a mat4 using another new function.
4. Render a transform using this mat4. You should see a coordinate system pitched 45 degrees downward.
5. Experiment with different angles and conversion paths (e.g., Axis-Angle -> Matrix) to build confidence in your library.

Conclusion

In this lesson, you've taken a deep dive into the world of 3D rotations and expanded your math library with a new quaternion type and a suite of essential conversion functions. You are now equipped to handle orientation data in whatever format is most appropriate for the task at hand.

Key Takeaways:

• There are multiple ways to represent 3D orientation (Matrix, Axis-Angle, Euler Angles, Quaternion), each with specific strengths and weaknesses.
• Quaternions are the preferred internal representation for physics engines because they are compact, robust against numerical drift, and free from Gimbal lock.
• The conversion functions between these formats are the critical glue that allows different systems (user input, physics, rendering) to communicate.
• Robust conversion code must handle edge cases, such as Gimbal lock for Euler angles and zero-degree rotations for axis-angle.

You now have a quaternion type and can convert to and from it. However, we haven't yet used it for any calculations. In the next lesson, we will implement the fundamental quaternion operations, including multiplication for composing rotations and the rotation of a vector by a quaternion. These operations are the final mathematical prerequisite before we can begin simulating the motion of rigid bodies.