`Matrix4.inverseTransformation`: misleading documentation

https://github.com/CesiumGS/cesium/blob/80ceefef2ee8e2f3236c38b8f7fb639caa38a3d8/Source/Core/Matrix4.js#L2589-L2592

I don’t know who is defining “affine transformation” to be a composition of a rotation and a translation. Every definition I’ve found gives an affine transformation as an arbitrary (invertible) linear transformation followed by a translation.

However, inverseTransformation returns subtly wrong results when, for instance, a non-uniform scale component is introduced.

The situation regarding this function is confusing, and could be improved:

• The documentation of inverseTransformation (and the cross-reference in the documentation of inverse) should be reworded to avoid using the term “affine transformation”.
• Moreover, the function name is misleading. It does not invert all transformations. It should be called inverseRotationTranslation.

This issue was a real time-waster for me; hopefully the situation can be improved for future users.

[j9liu]

@atlight @ebogo1 Would it make more sense if the documentation for inverseTransformation read something as follows?

* Computes the inverse of the provided matrix assuming it is
* a composition of a rotation and a translation,
* where the upper left 3x3 elements are a rotation matrix,
* and the upper three elements in the fourth column are the translation.
* The bottom row is assumed to be [0, 0, 0, 1].

The documentation for inverse can be adjusted similarly:

* Computes the inverse of the provided matrix using Cramers Rule.
* If the determinant is zero, the matrix can not be inverted, and an exception is thrown.
* If the matrix is a composition of a rotation and a translation, it is more efficient
* to invert it with {@link Matrix4.inverseTransformation}.

As for the alternative to inverseTransformation, maybe @ebogo1 let me know what you or others think of in the near future and I can work on replacing the name?

[j9liu]

Oh! Then perhaps we can change the wording of the documentation to say “Computes the inverse of the provided matrix assuming it is a rigid transformation.” However, it wouldn’t necessarily be true that “the upper left 3x3 elements are a rotation matrix,” right?We would have to reword it where “the upper left 3x3 elements are a rotation or reflection matrix,” or something like that?