Terminology around Euler angles in documentation


I recently ran into some issues using UnitQuaternion::from_euler_angles because I misinterpreted the documentation on which order the the rotations are specified. The function takes (roll, pitch, yaw) as args, but doesn’t specify which axes roll/pitch/yaw refer to. I’m used to working in a “Z is forward/backward”, and so I took this to mean the arguments correspond to (z, x, y), however after some confusion I realized that the arguments do in fact correspond to (x, y, z) (which makes more sense in retrospect), corresponding to a “Z is up/down” orientation.

Would it make more sense to refer explicitly to rotation around the primary axes, rather than using roll/pitch/yaw? Using the [aircraft principle axes] to communicate rotation relies on a shared reference for which direction is forward, and the terminology can be different in different contexts. It seems to me like it would be far less ambiguous to refer to the x/y/z axes directly.

Is there any reason why that wouldn’t be ideal? I’m coming from a game dev background without a strong understanding of the more abstract math concepts that drive a lot of nalgebra’s design, so I might be missing a reason why it makes more sense to use the aircraft principle axes instead of x/y/z.


Hi! Thank you for your feedback.

We should probably add both explanation to avoid confusion. One reason the aircraft analogy is interesting is that it shows quite clearly that the successive rotations are applied wrt. the local axises of the aircraft instead of the global (x, y, z) axises. This is what leads to the issues known as gimbal lock: when you use Euler angles such that two local axis of the aircraft successively become aligned with the same global axis.

In any case, the documentation needs to be improved so I’ve opened an issue: https://github.com/rustsim/nalgebra/issues/529