Improve `::from_euler_angles` documentation.

[sebcrozet]

Refer to that discussion on the user forum for details:

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.

[randomPoison]

I'd be willing to fix this up. I'd like to try writing a more full explanation of how Euler angles are applied without using roll/pitch/yaw. I think it would make sense to add this to the guide somewhere, since there are multiple functions for creating a rotation from Euler angles, and multiple places where you can get Euler angles from a rotation. Would it make sense to add it as a sub-header under Rotations on the Points and Transforms page? I would then be able to reference the guide in the method docs to avoid having to repeat the full explanation everywhere it's relevant. Alternatively, I could do a module-level documentation somewhere if there's a more appropriate module?

[sebcrozet]

Thank you for helping out @randomPoison!

I think it would make sense to add this to the guide somewhere, since there are multiple functions for creating a rotation from Euler angles, and multiple places where you can get Euler angles from a rotation. Would it make sense to add it as a sub-header under Rotations on the Points and Transforms page? I would then be able to reference the guide in the method docs to avoid having to repeat the full explanation everywhere it's relevant

This sounds like the best approach, yes.

Note that the user's guide source are on the nalgebra.org github repository.

[TheButlah]

This was the source of a bug that took me several days to wrap my mind around. It didn't occur to me that roll, pitch, yaw was actually x, y, z. Its probably enough to just replace those aircraft-terms with "rotation around x, y, z". I think the following is also necessary to make it unambiguous:

• is it a left handed or right handed coordinate system
• are positive rotations clockwise or counter-clockwise around the axis

[leocencetti]

I also find the roll, pitch, yaw naming quite unconventional. That notation usually refers to Tait-Bryan angles which are applied in the yaw - pitch - roll (Z Y X or, properly, Z Y'X") order (see convention), and not the other way around. Fully complying with Tait-Bryan angles convention could avoid confusion (adding a ::from_tait_bryan(yaw, pitch, roll)).