Rotation implementation in jogl's Quaternion class

Hi all,

I've got a question concerning the implementation of the rotation*-methods in the Quaternion class. I understand the idea of rotating a point/vector P in 3D space around some axes with the aid of a quaternion q: simply represent P as a quaternion
p = (Px, Py, Pz, 0), the rotation by q=(sin(a/2)*qx, sin(a/2)*qy, sin(a/2)*qz, cos(a/2)) (where (qx, qy, qz) is the axis of rotation in 3D and a is the angle in radians) and compute q*p*conj(q) to obtain the rotated point as a quaternion (disregarding the w-part).

Until now I thought the rotate*-methods in the Quaternion class would be a convenient way to do exactly this. Yet it seems this is not the case. Take e.g. the implementation of the method rotateByAngleY(angle)

        final float halfAngle = 0.5f * angle;
        final float sin = FloatUtil.sin(halfAngle);
        final float cos = FloatUtil.cos(halfAngle);
        return set( x * cos - z * sin,
                    y * cos + w * sin,
                    x * sin + z * cos,
                   -y * sin + w * cos);

The result is not the rotation of a point (x, y, z) (represented by "this" quaternion (x, y, z, 0)) around "angle". It rather seems like "half" the conjugation step mentioned above, something like q*p (without the "*conj(q)"-part) but even then I computed it to be (x*cos+z*sin, y*cos+w*sin, -x*sin+z*cos, -y*sin+w*cos), notice the difference in signs). So really, what does this method actually compute, what is the interpretation of its result?
The documentation states "Rotate this quaternion around Y axis with the given angle in radians" -- but what does that mean exactly? I know there's a method "rotateVector", maybe it's doing what I expect, I haven't check yet. But what does "rotating a quaternion" mean?

I think I got it now: "rotate this quaternion" simply means multiplying this quaternion by a rotational quaternion q for a rotation around the y-axis. Hence,

rotateByAngleY(PI/2) means this * q, where q=(0, sin(PI/4),0,cos(PI/4)).

So this is useful for chaining rotations (if this is also a quaternion representing a rotation). For actually applying the rotation we use rotateVector(...).

Hi

I thought that the documentation was clear. "Rotate the given vector by this quaternion" != "Rotate this quaternion"

Hi,

you state the documentation for "rotateVector" (which I honestly didn't notice at first), I think that this is clear and good.

I was referring to the documentation of "rotateByAngleY" (and all the other rotate-methods) which talks about rotating a quaternion. I think that this is rather misleading, because a quaternion is not an object in a 3d space which is rotated. It is rather regarded as a rotation operator. However, operators are multiplied or chained and now I know that's what this method is actually meant to do.
So at first I had to guess what could be the meaning of this terminology. Since I read the text from the class documentation at "euclideanspace.com-Quaternion" my interpretation was as I stated in my first post: have one Quaternion p represent the point and rotate this point (represented as a quaternion), hence the misunderstanding.

Maybe we could rephrase this part of the documentation to drive it less misleading.