I'm fairly certain that the Quaternion class Javadocs are wrong wherever they discuss Euler angles. The docs consistently describe the used Euler angle sequence as Yaw, Roll, Pitch. Specifically, the input sequence for the float[3] constructor, and the input/output for the toAngles/fromAngles methods. I am not talking about the order in which the eulers are applied internally (which is done correctly according to the http://www.euclideanspace.com algorithm), just the input/output params. It's also not that the input/output sequence is implemented wrong, but that the decided-upon sequence of input/output parameters are not as documented.
It is very easy to empirically show that the sequence of the 3 angles for these methods are exactly the same as the 2nd param of the fromAngleAxis methods, and this fromAngleAxis parameter clearly describes rotations around the local object's X, Y, and Z axes respectively. See, for example, http://www.jmonkeyengine.com/wiki/doku.php?id=rotate . I understand the traditional avoidance of X/Y/Z for the Euler angles, but IMO the avoidance is unwarranted as long as one understands we always mean the local rotation of the object under discussion (not worldspace, for example). Conclusion: the Quaternion Euler angle sequences are rotation-about-X-axis, rotation-about-Y-axis, rotation-about-Z-axis.
When using these methods, the float[3] constructor and to/fromAngles() methods, results are always correct on the assumption that the params mean rotations about the X, Y, and Z axes (in this order).
The normal frame of reference for Roll/Bank, Yaw/Heading, Pitch/Attitude is according to the traditional example of an airplane flying to +x, as described in the "NASA Standard Aeroplane" section at http://www.euclideanspace.com/maths/geometry/rotations/Euler/index.htm . Although the jME Quaternion implementation is based on the www.euclideanspace.com algorithms (e.g. the sequence of angle applications), the jME Javadoc specifications for "y, r, p" do not work according to this model, and the docs imply that they are according to the following model.
Everything I can find in the jME docs explains the Roll/Bank, Yaw/Heading, Pitch/Attitude specs as applying to an object facing its local +Z or -Z direction with +Y up. This is clearly spelled out at http://www.jmonkeyengine.com/wiki/doku.php?id=rotate , though they are specifically talking about the boolean angle axes .
As correctly explained at http://www.jmonkeyengine.com/wiki/doku.php?id=rotate , a pitch change to an object facing +Z or -Z results in a rotation about the X axis; a yaw change results in a Y axis rotation; and a roll change results in a Z axis change. Therefore, the Quaternion methods Euler parameters which specify rotations about x/y/z axes should be in the order (pitch-rotation, yaw-rotation, roll-rotation). IMO, they are incorrectly described in the Javadoc as (yaw, roll, pitch).
If everything is interpreted as I have explained, i.e. the Quaternion class's euler params are in sequence [x-axis-rot, y-axis-rot, z-axis-rot] corresponding to [pitch, yaw, roll] of a Z-forward/Y-up] object, then everything just works. I applied every possible transform combination and euler conversion to confirm this.
I think the JavaDoc needs to be corrected. Seeing that, contrary to traditional quaternion usage, use 3D developers need to always understand about local X/Y/Z axes, I see no benefit to introducing the roll/bank/yaw/heading/pitch/att concept at all. Since with jME games we always want to think of an object's LOCAL forward to be +Z and +Y up, and since this is different from the traditional interpretation of roll/bank/yaw/heading/pitch (where object's forward is +X and +Y up), the whole concept just adds ambiguity. Everything just makes sense if the eulers are interpreted to mean rotations around the local object's X, Y, and Z axes respectively.
Good catch. This documentation error is my fault. iirc, we were having issues with euler->quat not calculating correctly and I spent time working on that. To verify the values were coming back correctly, I was using other online calculators to validate results and grabbed the terminology from those. It seems from the pairing of yaw to bank, roll to heading, etc. that I was confusing terminology due to different facings and trying to reconcile.
Good catch. This documentation error is my fault. iirc, we were having issues with euler->quat not calculating correctly and I spent time working on that. To verify the values were coming back correctly, I was using other online calculators to validate results and grabbed the terminology from those. It seems from the pairing of yaw to bank, roll to heading, etc. that I was confusing terminology due to different facings and trying to reconcile.
It would also be very nice to the reader if, when telling of the Euler angle specification sequence, you also told them the sequence of application. If you don't mention it, it kind of implies that they are applied in the same order as the specifications sequence: X, Y, Z. In fact, they are applied in sequence Y, Z, X, as explained very clearly in the diagram in the middle of http://www.euclideanspace.com/maths/standards/index.htm , and which I have verified works this way with jME.
For those who don't know, the significance of the application sequence is that Euler (5, 10, 15) is a completely different rotation if the application sequence is X, Y, Z instead of Y, Z, X; and also, if you are starting with an identity Euler or Quaternion (0, 0, 0 / (0,0,0) 1) and adding rotations for each axis to it, you must add them in the same sequence or you will effect the other axes.
POSTNOTE: If anybody wants a copy of the little command-line (text) program I wrote to interactively apply rotations to a Quaternion and display results in both Quaternion radian and Euler degree format, PM me.
+1 to remove any yaw/pitch/roll reference from documents and to explain euler angles apply order (Z, Y, X).
I'll gladly help if you wish. We know you are busy with other stuff and I am all for documentation.
(As a side note, not all of us assume all of our assets to face +Z ).
Please do, unless renanse wants to update it.
FYI, if both jME and Blender documented this stuff, it would have saved me 3 days of frustrating work, because I could not get Blender orientations to convert correctly into jME. Blender applies the Eulers in sequence X, Y, Z, and they are therefore incompatible with jME Eulers. Curious folk can see this themselves by adding a new mesh to Blender, type N to bring up the Transform Proprties. Apply all the X rotations you want, then all the Y rotations you want, then all the Z rotations you want, and these are shown as independent changes in the properties window. Change any rotation in a different order and it effects the other local axes.
* <code>fromAngles</code> builds a Quaternion from the Euler rotation
* angles (y,r,p). Note that we are applying in order: roll, pitch, yaw but
* we've ordered them in x, y, and z for convenience.
It actually states the applying order: r,p,y which correspond to y,z,x. Did I misunderstand your post?
I'm still all up for removing any reference to those, except for the fact that they map to x,y,z as for explanations in eulerspace.org are concerned. Other than that, I would still remove them from the parameter names.
So, as renanse said it's ok, do I remove every yaw/roll/pitch reference?
* <code>fromAngles</code> builds a Quaternion from the Euler rotation
* angles (y,r,p). Note that we are applying in order: roll, pitch, yaw but
* we've ordered them in x, y, and z for convenience.
It actually states the applying order: r,p,y which correspond to y,z,x. Did I misunderstand your post?
Ah. I forgot that it said anything about the application order. Sorry.
I've just looked it over again, and I see that pretty much everything it says about roll, pitch, and yaw is wrong, even the synonyms listed.
Real application order is Y, Z, X.
I'm still all up for removing any reference to those, except for the fact that they map to x,y,z as for explanations in eulerspace.org are concerned. Other than that, I would still remove them from the parameter names.
So, as renanse said it's ok, do I remove every yaw/roll/pitch reference?