add some caveats to the com.jme3.math javadoc (#2156)

Author: stephengold

jme3-core/src/main/java/com/jme3/math/Matrix4f.java

@@ -1802,6 +1802,9 @@ public Vector3f toTranslationVector(Vector3f vector) {
     /**
      * Determine the rotation component of this 3-D coordinate transform.
      *
+     * <p>Assumes (but does not verify) that the transform consists entirely of
+     * translation, rotation, and positive scaling -- no reflection or shear.
+     *
      * @return a new rotation Quaternion
      */
     public Quaternion toRotationQuat() {
@@ -1813,6 +1816,9 @@ public Quaternion toRotationQuat() {
     /**
      * Returns the rotation component of the coordinate transform.
      *
+     * <p>Assumes (but does not verify) that the transform consists entirely of
+     * translation, rotation, and positive scaling -- no reflection or shear.
+     *
      * @param q storage for the result (not null, modified)
      * @return the rotation component (in {@code q}) for chaining
      */
@@ -1824,7 +1830,10 @@ public Quaternion toRotationQuat(Quaternion q) {
     /**
      * Determine the rotation component of this 3-D coordinate transform.
      *
-     * @return a new rotation Matrix3f
+     * <p>If the transform includes scaling or reflection or shear, the result
+     * might not be a valid rotation matrix.
+     *
+     * @return a new Matrix3f
      */
     public Matrix3f toRotationMatrix() {
         return new Matrix3f(m00, m01, m02, m10, m11, m12, m20, m21, m22);
@@ -1833,6 +1842,9 @@ public Matrix3f toRotationMatrix() {
     /**
      * Determines the rotation component of the coordinate transform.
      *
+     * <p>If the transform includes scaling or reflection or shear, the result
+     * might not be a valid rotation matrix.
+     *
      * @param mat storage for the result (not null, modified)
      */
     public void toRotationMatrix(Matrix3f mat) {
@@ -1850,6 +1862,9 @@ public void toRotationMatrix(Matrix3f mat) {
     /**
      * Determine the scale component of this 3-D coordinate transform.
      *
+     * <p>All components of the result will be non-negative, even if the
+     * coordinate transform includes reflection.
+     *
      * @return a new Vector3f
      */
     public Vector3f toScaleVector() {
@@ -1861,6 +1876,9 @@ public Vector3f toScaleVector() {
     /**
      * Determines the scale component of the coordinate transform.
      *
+     * <p>All components of the result will be non-negative, even if the
+     * coordinate transform includes reflection.
+     *
      * @param store storage for the result (not null, modified)
      * @return the scale factors (in {@code store}) for chaining
      */

jme3-core/src/main/java/com/jme3/math/Quaternion.java

@@ -356,8 +356,10 @@ public float[] toAngles(float[] angles) {
     }
 
     /**
-     * Sets the quaternion from the specified rotation matrix. Does not verify
-     * that the argument is a valid rotation matrix.
+     * Sets the quaternion from the specified rotation matrix.
+     *
+     * <p>Does not verify that the argument is a valid rotation matrix.
+     * Positive scaling is compensated for, but not reflection or shear.
      *
      * @param matrix the input matrix (not null, unaffected)
      * @return the (modified) current instance (for chaining)
@@ -369,7 +371,9 @@ public Quaternion fromRotationMatrix(Matrix3f matrix) {
 
     /**
      * Sets the quaternion from a rotation matrix with the specified elements.
-     * Does not verify that the arguments form a valid rotation matrix.
+     *
+     * <p>Does not verify that the arguments form a valid rotation matrix.
+     * Positive scaling is compensated for, but not reflection or shear.
      *
      * @param m00 the matrix element in row 0, column 0
      * @param m01 the matrix element in row 0, column 1
@@ -385,7 +389,7 @@ public Quaternion fromRotationMatrix(Matrix3f matrix) {
     public Quaternion fromRotationMatrix(float m00, float m01, float m02,
             float m10, float m11, float m12, float m20, float m21, float m22) {
         // first normalize the forward (F), up (U) and side (S) vectors of the rotation matrix
-        // so that the scale does not affect the rotation
+        // so that positive scaling does not affect the rotation
         float lengthSquared = m00 * m00 + m10 * m10 + m20 * m20;
         if (lengthSquared != 1f && lengthSquared != 0f) {
             lengthSquared = 1.0f / FastMath.sqrt(lengthSquared);
@@ -564,7 +568,7 @@ public Matrix4f toTransformMatrix(Matrix4f store) {
      * current instance is unaffected.
      *
      * <p>Note: preserves the translation and scaling components of
-     * {@code result}.
+     * {@code result} unless {@code result} includes reflection.
      *
      * <p>Note: the result is created from a normalized version of the current
      * instance.
@@ -1013,6 +1017,9 @@ public Quaternion mult(Quaternion q, Quaternion storeResult) {
     /**
      * Applies the rotation represented by the argument to the current instance.
      *
+     * <p>Does not verify that {@code matrix} is a valid rotation matrix.
+     * Positive scaling is compensated for, but not reflection or shear.
+     *
      * @param matrix the rotation matrix to apply (not null, unaffected)
      */
     public void apply(Matrix3f matrix) {

jme3-core/src/main/java/com/jme3/math/Transform.java

@@ -389,10 +389,13 @@ public Matrix4f toTransformMatrix(Matrix4f store) {
     }
 
     /**
-     * Sets the current instance from a transform matrix. Any shear in the
+     * Sets the current instance from a transform matrix. Any reflection or shear in the
      * matrix is lost -- in other words, it may not be possible to recreate the
      * original matrix from the result.
      *
+     * <p>After this method is invoked, all components of {@code scale} will be
+     * non-negative, even if {@code mat} includes reflection.
+     *
      * @param mat the input matrix (not null, unaffected)
      */
     public void fromTransformMatrix(Matrix4f mat) {
@@ -406,6 +409,10 @@ public void fromTransformMatrix(Matrix4f mat) {
     /**
      * Returns the inverse. The current instance is unaffected.
      *
+     * <p>Assumes (but does not verify) that the scale factors are all positive.
+     * If any component of {@code scale} is negative or zero, the result is
+     * undefined.
+     *
      * @return a new Transform
      */
     public Transform invert() {