1. What the controller actually knows

Imagine a camera mounted on a level drone. We choose a right-handed frame, with +Z vertical, and define positive yaw by the right-hand rule. The camera starts at the identity orientation and needs a positive 45-degree yaw correction. This is a deliberately simple case: it isolates the conversion before we add roll, pitch, moving targets, or uncertain state estimates.

Quaternion order is not decoration. In this library's convention, applying q_error after q_current reconstructs q_target. If your frame convention or multiplication order differs, the formula must be re-derived, not copied blindly.

2. Why the quaternion contains 22.5 degrees

A unit quaternion for an axis u and angle θ stores the half-angle:

Here u = [0, 0, 1] and θ = 45°. Therefore θ/2 = 22.5° and:

So q_target = [0.92387953, 0, 0, 0.38268343]. Because the current pose is identity, its inverse is also identity and q_error = q_target.

3. Recover the axis and angle

Write a normalized relative quaternion as q = [w, v_x, v_y, v_z]. Let s = ||v|| = sqrt(v_x² + v_y² + v_z²). For the shortest rotation, choose the equivalent sign with w ≥ 0. Then, away from zero rotation:

In our example, s = 0.38268343. Dividing [0, 0, 0.38268343] by s gives [0, 0, 1]. Twice the angle returned by atan2(0.38268343, 0.92387953) gives 45°. We have recovered the command from the stored rotation without guessing the axis from the picture.

4. What happens at zero and 180 degrees?

Near zero, division by s becomes ill-conditioned, so extraction needs a tolerance and a documented axis sentinel. At 180 degrees, w is near zero; floating-point noise can flip the reported axis sign. A controller should compare physical rotations, not exact quaternion signs.

5. Follow the C code, not just the diagram

The library already computes the relative rotation and has a camera tracking test for this 45-degree case. Its current quaternion_relative implementation multiplies target by inverse(current), normalizes the result, and flips the quaternion sign when the scalar is negative. Its quaternion_to_axis_angle uses 2 * acos(w) and divides the vector part by its norm. For a near-zero vector part it returns angle zero and axis [0, 0, 0].

You can reproduce the result with the public API, without borrowing a helper from a test file:

#include <attitude/quaternion.h>
#include <math.h>
#include <stdio.h>

int main(void) {
    const double pi = acos(-1.0);
    const double current[4] = {1.0, 0.0, 0.0, 0.0};
    const double target[4] = {cos(pi / 8.0), 0.0, 0.0, sin(pi / 8.0)};
    double axis[3], angle;

    if (!quaternion_orientation_error_axis_angle(
            current, target, axis, &angle)) return 1;
    printf("axis=[%.1f, %.1f, %.1f], angle=%.1f degrees\n",
           axis[0], axis[1], axis[2], angle * 180.0 / pi);
    return 0;
}

Clone attitudeMathLibrary, run make, save the code above as camera_axis_angle.c in the repository root, then compile and run:

cc -std=c11 -Iinclude camera_axis_angle.c build/libattitude.a -lm -o camera_axis_angle
./camera_axis_angle
# axis=[0.0, 0.0, 1.0], angle=45.0 degrees

The repository test independently checks this camera case and reconstruction of a target pose. The atan2 expression earlier is the stable teaching form for normalized inputs; it is not a claim that the current C function uses it. The implementation uses acos(w) without clamping, so applications should validate finite, normalized inputs before calling it. There is also a small API-doc mismatch: the header says quaternion_to_axis_angle returns zero when the identity axis is undefined, but the current source returns success with angle zero and axis [0, 0, 0]. Treat that sentinel as the observed behavior, not as a mathematical axis.

6. Questions to explore next

The worked example is a starting point. These are the questions worth exploring in a deeper question-and-answer follow-up:

1. Why does a quaternion store half the physical rotation angle?
2. Why can q and -q turn the same camera pose?
3. Why does the zero-rotation axis disappear, and what should a controller do with that case?
4. When the drone is already rolled or pitched, what frame does the recovered error axis live in?

For the broader picture, read the original quaternion article first or next. This post is its worked inverse example: from the desired camera correction back to the axis and angle the controller can reason about.