New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve `::from_euler_angles` documentation. #529

Open
sebcrozet opened this Issue Jan 19, 2019 · 2 comments

Comments

Projects
None yet
2 participants
@sebcrozet
Copy link
Member

sebcrozet commented Jan 19, 2019

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

This comment has been minimized.

Copy link

randomPoison commented Jan 19, 2019

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

This comment has been minimized.

Copy link
Member Author

sebcrozet commented Jan 20, 2019

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment