Documentation should clarify that the quaternions are defined using an active rotation convention

[scottshambaugh]

Decently large corners of the the aerospace and robotics community use a definition of quaternion rotations with a "passive" rotation convention, which effectively inverts the standard representation and calculates rotations as vp = q.conjugate() @ v @ q. See these two papers for a good overview of the (complete and utter) mess:

• Sommer, Hannes, et al. "Why and how to avoid the flipped quaternion multiplication." Aerospace 5.3 (2018): 72.
• Zanetti, Renato. "Rotations, transformations, left quaternions, right quaternions?." The Journal of the Astronautical Sciences 66.3 (2019): 361-381.

The library implements the standard "active" rotation convention, but the documentation does not specifically call this out. Some verbiage along these lines would be very helpful in making things crystal clear.

[moble]

I strenuously object to using "conventional" names for identifying any conventions, because even the names are ambiguous, uninformative, and very easy to misinterpret. My advice, as always, is to understand the relationships between different quantities, which is what I actually try to document. For example, see the docstrings of as_rotation_matrix and from_rotation_matrix, which specify that the rotation matrix m acts in the same way as the quaternion q such that

m @ v.vec == q * v * q.conjugate()

Or the docstring of rotate_vectors, which specifies that a quaternion R acts on a vector v to produce a new vector as

vprime = R * v * R.conjugate()

But the meaning of that relationship depends on what R represents: a change of basis or a physical rotation. Therefore, fundamentally and unavoidably, the way you think of those relationships — and how you name them — is up to you.

Moreover, most of this package doesn't actually deal with rotations. In fact, off the top of my head, those are the only three functions that actually deal with applying rotations per se. The Euler-angle functions, for example, only produce quaternions from a set of angles; they don't apply any quaternions. And again in those cases, all I do is document the relationship between those angles and the quaternion. And of course, that's another example where people have repeatedly asked me to identify the convention with names including "active" and "passive" — though with completely different meaning to your usages above.

IMO, using names like these only misleads, and makes the complete and utter mess of conventions combinatorically worse.

[scottshambaugh]

Point taken on the mathematical definitions being the source of truth, but for all the verbiage about Euler angles being bad some language on anticipating this (IMO rather more insidious) footgun would be much appreciated. I'll also note that the Shuster convention talked about in those papers changes the definition of quaternion multiplication itself, so that i * j = -k rather than +k. I don't see the multiplication definition called out in the docs right now. (discussed a bit previously in https://github.com/moble/quaternion/issues/96)

[J-Sorenson]

Heh! Came across this while trying to de-Shusterize a legacy rate-sensor model. We, in the aerospace industry, feel that Shuster-math and scalar-last quaternions are still "common" in our little pond, but that line of thinking is narrow and 20 years out of date. All of our employees who are over 40 (me included) are quite comfortable with Shuster's so-called "Natural" quaternions with his flipped multiplication and scalar-last notation. However, every new employee has to bend over backwards to understand our code. Every public math library uses the exact same notation and rotation math as this library: Qt, Matlab Robotics toolbox, Julia, C++ Eigen, OpenGL, Unity, etc.. None of them even mention our boutique custom quaternion math, because no book in the 21st century uses them. Yes sir! I got my personal copy of "Spacecraft Attitude Determination and Control" by James Wertz, copyright 1978. Even if we set aside Shuster math, the idea of using "passive" rotations (transform) is falling away in favor of the more proper method of using a transform quaternion (or "left" quaternion in our old Shuttle software). Euler angles, unfortunately, will always be around. As for Shuster multiplication, scalar-last notation, and passive rotations: we can safely ignore those nowadays. Anyone educated in Aerospace should be cognizant of how Dr. Shuster made his own math (long before the internet), but we've been steadily moving towards the world standard.