jme3-core: document a few places where normalization is assumed

[stephengold]

The PR documents a few places where normalization is assumed.

JME assumes that the local rotations of scene-graph spatials are normalized. A violation of this assumption caused the issue @yaRnMcDonuts recently reported at the Discourse Forum/Hub.

[stephengold]

Unless there's further discussion, I plan to integrate this PR in about 24 hours.

[stephengold]

I realized that transformVector() and transformInverseVector() both use Quaternion.rot(Vector3f, Vector3f) and therefore make the same assumption of normality. I've added appropriate javadoc to this PR.

Resetting the clock, I plan to integrate this PR in 24 hours.

[pspeed42]

Probably too late comment so do with it what you will...

There was once a time that someone wanted to rename "mult" to "rotate". The ultimate issue was that Quaternion is a math concept that can be used for 3D graphics but that is not necessarily it's only use. When a Quaternion is "normal" then "mult" can be used for rotation but that might not be the only reason to call Quaternion.mult in a mathematics sense.

Any time we talk about rotation, then it is kind of necessary for Quaternions to be normalized and so it 100% makes sense to mention the requirement for the methods that are specifically dealing with rotations. (like the one returning a rotation matrix, etc.). It may make less sense for the "purely math but can be used for rotation" ones.

That said, anyone using Quaternions for something other than rotation probably already knows this.

[stephengold]

I assume that the Quaternion.mult() and multLocal() methods involving vectors were named by analogy with Matrix3f. Both sets of methods serve analogous purposes: for restricted values (unit quaternions and 3x3 rotation matrices) the methods perform 3-D rotations on vectors.

Unfortunately, mathematicians defined multiplication of a quaternion with a vector to suit their purposes, and that definition conflicts with what Quaternion.mult() actually does to a 3-D vector, namely: rotate (not multiply!) the vector. Seeing these methods named mult() caused me to add javadoc disclaimers at #1725, lest someone using Quaternion for something other than rotation be misled by the names. (Interestingly, the mult() methods that don't involve vectors do agree with the mathematical definition of multiplication, which only magnifies the confusion.)

While it seems expedient for rotation methods to assume their inputs are normalized and (for such inputs) produce normalized outputs, it leads to subtle bugs. For instance, if you start with a normalized value and then apply enough math operations, floating-point round-off may cause the norms to diverge substantially from 1.

Furthermore, naive users and buggy tools (such as the one that bit Ryan) generate unintentional non-normalized quaternions with surprising frequency.

I realize the disclaimers added in this PR are unlikely to mean much to naive users. They're mainly to soothe my conscience at the lack of run-time checks.

In my own projects, I prefer to check for a normal quaternion before each rotation. The cost seems slight compared to the time I spend debugging issues. But such run-time checks seem contrary to the JME Way, so I have not added them here.