How do setRotationAxis and setRotate work in JavaFX 3D?

Question

There is a texture I have to apply to a sphere. It has an arrow along equator.
When I applied a PhongMaterial with that texture to my sphere, an arrow I needed on top, was on the bottom facing direction opposite of what I needed.
I then called
                    final Sphere sphLeaf = new Sphere(R);
                    sphLeaf.setRotationAxis(Rotate.X_AXIS);
                    sphLeaf.setRotate(180.0);
Then the arrow was correctly placed on top of the sphere, but still facing wrong direction.
I thought that calling
                    sphLeaf.setRotationAxis(Rotate.Y_AXIS);
                    sphLeaf.setRotate(180.0);
would point my arrow where I needed, but instead it was now on the side of the sphere, though facing the right direction.
I thought that each call to setRotationAxis must limit rotation to that axis only. Why is there extra rotation occurring on top of what I requested?

Answer 1

There are two distinct ways to implement an API for applying rotations to Nodes:
1. The Node has a "current rotation" property representing the total rotation of the Node relative to the coordinate system of the Scene. The programmer can change the rotation of the Node by updating this property.
2. The Node has a method for concatenating new rotations to other transforms applied to it (i.e. providing incremental rotations).
The API supports both of these. The way it is written is for the Node to have three specific transformations (a translation, a scale, and a rotation) which can be manipulated via a set of properties (translateX, translateY, translateZ, scaleX, scaleY, scaleZ, rotationAxis, and rotate). These are all properties and obey the usual rules of properties; for example
node.setXXX(value);
assert(node.getXXX()==value);
will always succeed, assuming a single-threaded model.
Additionally, the Node supports a list of arbitrary transforms. These transforms are applied in order, before any of the three transforms above.
So to use 1. above, you can do
node.setRotate(newTotalRotationAmount);
node.setRotationAxis(newAxis); // if necessary
This is really convenient in some circumstances. For example, in an animation it's pretty straightforward to compute how much the node should be rotated (in total) based on the elapsed time of the animation. If you only had the incremental rotation, the animation would need to keep track of how long it was since the previous update (which will vary from rendered frame to rendered frame). JavaFX's animation API takes huge advantage of this, and that's why it's so straightforward to animate a rotation in JavaFX.
To use 2. above, you can do
node.getTransformations().add(Transform.rotate(...));
or
node.getTransformations().add(new Rotate(...));
depending on the rotation you need to append. This is also pretty convenient to code against.
This is fine is you have a relatively small set of rotations you're going to apply, and the result would be complex to compute (for example if they are around different axes).
The one potential problem here is that you would cause memory leaks and could potentially cause slow performance (though I suspect the implementation is written so this wouldn't happen) if you're likely to add arbitrarily many transformations this way. JavaFX 8 adds some API to the Transformation class to deal with this use case. In the most bullet-proof version this would look as follows, though you can probably reduce the code based on surrounding logic:
Rotate additionalRotation = new Rotation(...);
int numTransforms = node.getTransforms().size();
if (numTransforms==0) {
     node.getTransforms().add(additionalRotation);
} else {
     Transform updatedTransform = node.getTransforms().get(numTransforms-1).createConcatenation(additionalRotation);
     node.getTransforms().set(numTransforms-1, updatedTransform);
That seems like a pretty decent API that covers all use cases. The last use case is a little more verbose to use, and is only available in JavaFX 8, but is still not too bad. If you initialize the node to have at least one transformation in the list, and always use this idiom (i.e. just replace the transformation rather than adding any new ones), then you can reduce that to one or two lines.