I looked at the code for Quaternion.fromAngles for awhile, and compared it with the calculation specified on the EuclideanSpace.com site. It appears that the current JME3 code follows the site conventions (except for the RPY labelling issue), and the javadoc would be correct if it said something like this:
[java]/**
Rotations are applied in this order: yRot, zRot, xRot.
<p/>Our calculation is based on the conventions (for conversion from Euler angles) defined by EuclideanSpace.com, which uses the same right-handed X,Y,Z coordinate system as JME3.</p>
<p/>However, when interpreting the "bank" and "attitude" angles described on that site, be careful to remember that in JME3,
"forward" is usually considered to be along the Z-axis, out of the screen, while EuclideanSpace.com is using a vehicular convention that
"forward" is considered to be along the X-axis, to the right.
</p>
@param xRot - rotation around X-axis (applied third - "bank" in the EuclideanSpace.com conventions)
@param yRot - rotation around Y-axis (applied first - "heading" in the EuclideanSpace.com conventions)
@param zRot - rotation around Z-axis (applied second - "attitude" in the EuclideanSpace.com conventions)
Except if the user expects “bank” by changing xRot then they will get “attitude”. Probably best to leave the arbitrarily incorrect x,z confusing reference to EuclideanSpace out completely since they picked a different arbitrary facing axis than JME did.
Sure, let’s strike EuclideanSpace.com out for notation reference purposes. But seems we probably still need them as a reference on the calculation, or else we would have to do the work to publish our own derivation of the equations. If we have neither of those things, the question will keep coming up about “where does your Euler to Quaternion code come from?”
Proposed:
Copy this explanation of the calculation (into the javadoc and/or to a wiki page linked from the javadoc), and update the notation to match JME3. Also update the implementation code to match that same notation.
[java]
/*
Q = (w,x,y,z)
w = c1 c2 c3 - s1 s2 s3
x = s1 s2 c3 + c1 c2 s3
y = s1 c2 c3 + c1 s2 s3
z = c1 s2 c3 - s1 c2 s3
where:
(TODO: FIX NOTATION FOR JME3 - swap the labels "attitude" and "bank"):
c1 = cos(heading / 2)
c2 = cos(attitude / 2)
c3 = cos(bank / 2)
s1 = sin(heading / 2)
s2 = sin(attitude / 2)
s3 = sin(bank / 2)
xRot = bank
yRot = heading
zRot = attitude
order of rotation application is:
heading=yRot
attitude=zRot
bank=xRot
while the order of arguments passed to the JME3 method is:
q.fromAngles(xRot, yRot, zRot);
*/
[/java]
After we carefully relabel the attitude and bank terms above, then we have a description that matches JME3 conventions and also accurately
describes the calculation, right? (Optionally use the terms yaw=heading, pitch=attitude, roll=bank, but only in those mappings. No freestyling!)
Additionally cite EuclideanSpace.com as a calculation reference(since their math matches ours, and as Blago might say,“that is a valuable thing!”). So we could say:
[java]
/*If you want to understand more about the math in these calculations,