Add inverseTransform; Rename transpose to avoid confusion

Author: andykswong

assembly/__tests__/array.spec.ts

@@ -192,12 +192,12 @@ describe('array', () => {
     }
   });
 
-  test('tr(a)', () => {
+  test('transpose(a)', () => {
     const actuals: Vec[] = [
-      array.tr(1, [1], [0]),
-      mat2.tr([1, 2, 3, 4]),
-      mat3.tr([1, 2, 3, 4, 5, 6, 7, 8, 9]),
-      mat4.tr([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]),
+      array.transpose(1, [1], [0]),
+      mat2.transpose([1, 2, 3, 4]),
+      mat3.transpose([1, 2, 3, 4, 5, 6, 7, 8, 9]),
+      mat4.transpose([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]),
     ];
 
     const expecteds: Vec[] = [

assembly/__tests__/transform.spec.ts

@@ -2,7 +2,7 @@ import {
   Float, Mat4, ortho, perspective, Quat, ReadonlyMat4, rotate, rotateX, rotateY, rotateZ, rotateAxis, rotationOf,
   scale, scaleOf, transform, translate, translationOf, Vec3, direction, vec3
 } from '../index';
-import { lookAt, targetTo } from '../transform';
+import { inverseTransform, lookAt, targetTo } from '../transform';
 import { expectVecEqual } from './test-utils';
 
 const PI_OVER_3 = Math.PI as Float / 3;
@@ -81,6 +81,13 @@ describe('transfrom', () => {
     expectVecEqual(actual, expected);
   });
 
+  test('inverseTransform(m)', () => {
+    const m: ReadonlyMat4 = [2, 2, -1, 0, -2, 4, 4, 0, 6, -3, 6, 0, 1, 2, 3, 1];
+    const expected: ReadonlyMat4 = [2/9, -1/18, 2/27, 0, 2/9, 1/9, -1/27, 0, -1/9, 1/9, 2/27, 0, -1/3, -1/2, -2/9, 1];
+    const actual = inverseTransform(m);
+    expectVecEqual(actual, expected);
+  });
+
   test('translationOf(m)', () => {
     expectVecEqual(translationOf([2, 2, -1, 0, -2, 4, 4, 0, 6, -3, 6, 0, 1, 2, 3, 1]), [1, 2, 3] as Vec3);
   });

assembly/array.ts

@@ -116,7 +116,7 @@ export function dot(a: ReadonlyVec, b: ReadonlyVec): Float {
  * @param out the output matrix
  * @returns out = [M]T
  */
-export function tr(n: Int, m: ReadonlyVec, out: Vec): Vec {
+export function transpose(n: Int, m: ReadonlyVec, out: Vec): Vec {
   let f: Float = 0;
   for (let i = 0; i < n; ++i) {
     for (let j = i; j < n; ++j) {

assembly/mat2.ts

@@ -70,8 +70,8 @@ export function scale(m: ReadonlyMat2, s: Float, out: Mat2 = create()): Mat2 {
  * Transpose a {@link Mat2}.
  * @returns [M]T
  */
-export function tr(m: ReadonlyMat2, out: Mat2 = create()): Mat2 {
-  return array.tr(2, m, out) as Mat2;
+export function transpose(m: ReadonlyMat2, out: Mat2 = create()): Mat2 {
+  return array.transpose(2, m, out) as Mat2;
 }
 
 /**

assembly/mat3.ts

@@ -59,8 +59,8 @@ export function scale(m: ReadonlyMat3, s: Float, out: Mat3 = create()): Mat3 {
  * Transpose a {@link Mat3}.
  * @returns [M]T
  */
-export function tr(m: ReadonlyMat3, out: Mat3 = create()): Mat3 {
-  return array.tr(3, m, out) as Mat3;
+export function transpose(m: ReadonlyMat3, out: Mat3 = create()): Mat3 {
+  return array.transpose(3, m, out) as Mat3;
 }
 
 /**
@@ -118,5 +118,5 @@ export function nmat(a: ReadonlyMat3, out: Mat3 = create()): Mat3 | null {
   if (!invert(a, out)) {
     return null;
   }
-  return tr(out, out);
+  return transpose(out, out);
 }

assembly/mat4.ts

@@ -93,8 +93,8 @@ export function scale(m: ReadonlyMat4, s: Float, out: Mat4 = create()): Mat4 {
  * Transpose a {@link Mat4}.
  * @returns [M]T
  */
-export function tr(m: ReadonlyMat4, out: Mat4 = create()): Mat4 {
-  return array.tr(4, m, out) as Mat4;
+export function transpose(m: ReadonlyMat4, out: Mat4 = create()): Mat4 {
+  return array.transpose(4, m, out) as Mat4;
 }
 
 /**

assembly/transform.ts

@@ -39,7 +39,7 @@ export function rotate(q: ReadonlyQuat, out: Mat4 = mat4.create()): Mat4 {
 
 /**
  * Returns a {@link Mat4} for a 3D rotation about the x-axis in couterclockwise direction.
- * see: https://en.wikipedia.org/wiki/Rotation_matrix#Basic_rotations
+ * @see https://en.wikipedia.org/wiki/Rotation_matrix#Basic_rotations
  */
 export function rotateX(theta: Float, out: Mat4 = mat4.create()): Mat4 {
   mat4.id(out);
@@ -51,7 +51,7 @@ export function rotateX(theta: Float, out: Mat4 = mat4.create()): Mat4 {
 
 /**
  * Returns a {@link Mat4} for a 3D rotation about the y-axis in couterclockwise direction.
- * see: https://en.wikipedia.org/wiki/Rotation_matrix#Basic_rotations
+ * @see https://en.wikipedia.org/wiki/Rotation_matrix#Basic_rotations
  */
 export function rotateY(theta: Float, out: Mat4 = mat4.create()): Mat4 {
   mat4.id(out);
@@ -63,7 +63,7 @@ export function rotateY(theta: Float, out: Mat4 = mat4.create()): Mat4 {
 
 /**
  * Returns a {@link Mat4} for a 3D rotation about the z-axis in couterclockwise direction.
- * see: https://en.wikipedia.org/wiki/Rotation_matrix#Basic_rotations
+ * @see https://en.wikipedia.org/wiki/Rotation_matrix#Basic_rotations
  */
 export function rotateZ(theta: Float, out: Mat4 = mat4.create()): Mat4 {
   mat4.id(out);
@@ -75,7 +75,7 @@ export function rotateZ(theta: Float, out: Mat4 = mat4.create()): Mat4 {
 
 /**
  * Returns a {@link Mat4} for a 3D rotation about a given unit axis in couterclockwise direction.
- * see: https://en.wikipedia.org/wiki/Rotation_matrix#Basic_rotations
+ * @see https://en.wikipedia.org/wiki/Rotation_matrix#Basic_rotations
  */
 export function rotateAxis(axis: ReadonlyVec3, theta: Float, out: Mat4 = mat4.create()): Mat4 {
   const
@@ -121,6 +121,42 @@ export function transform(translation: ReadonlyVec3, rotation: ReadonlyQuat, sca
   return out;
 }
 
+/**
+ * Returns the inverse of a {@link ReadonlyMat4} that represents a valid transformation in TRS order (= translation * rotation * scale).
+ * This function is more efficient than {@link mat4.invert} by using the properties of a TRS matrix.
+ * @returns out = M^-1
+ */
+export function inverseTransform(m: ReadonlyMat4, out: Mat4 = mat4.create()): Mat4 {
+  // Assume M is a TRS matrix:
+  // M = T * R * S = [RS  t]
+  //                 [0   1]
+  // Then the inverse of M is:
+  // M^-1 = [(RS)^-1  (RS)^-1 * -t]
+  //        [   0           1     ]
+  // Where: (RS)^-1 = S^-1 * R^-1 = S^-1 * RT = S^-1 * ((RS)(S^-1))T = S^-1 * (S^-1)T * (RS)T = S^-1 * S^-1 * (RS)T
+
+  // Calculate output = (RS)T
+  mat4.transpose(m, out);
+  unchecked(out[3] = out[7] = out[11] = 0);
+
+  // Extract S and premultiply S^-2 = 1/(S*S) to output
+  scaleOf(m, v1);
+  for (let i = 0; i < 3; ++i) {
+    for (let j = 0; j < 3; ++j) {
+      unchecked(out[4 * i + j] *= 1 / (v1[j] * v1[j]));
+    }
+  }
+
+  // With output = (RS)^-1, apply translation = (output * -t) to output
+  array.copy(
+    vec3.mmul4(out, vec3.scale(array.copy(m, v0, 12, 0, 3) as Vec3, -1)),
+    out,
+    0, 12, 3
+  );
+
+  return out;
+}
+
 // -- Transformation matrix decomposition --
 
 /**
@@ -131,7 +167,7 @@ export function translationOf(m: ReadonlyMat4, out: Vec3 = vec3.create()): Vec3
 }
 
 /**
- * Extract the {@link Vec3} scaling components from an affine transformation matrix.
+ * Extract the {@link Vec3} scaling components from a transformation matrix in TRS order (= translation * rotation * scale).
  */
 export function scaleOf(m: ReadonlyMat4, out: Vec3 = vec3.create()): Vec3 {
   for (let i = 0; i < 3; ++i) {
@@ -144,7 +180,7 @@ export function scaleOf(m: ReadonlyMat4, out: Vec3 = vec3.create()): Vec3 {
 }
 
 /**
- * Extract the {@link Quat} rotation components from an affine transformation matrix.
+ * Extract the {@link Quat} rotation components from a transformation matrix in TRS order (= translation * rotation * scale).
  * @see https://en.wikipedia.org/wiki/Rotation_matrix#Quaternion
  */
 export function rotationOf(m: ReadonlyMat4, out: Quat = quat.create()): Quat {

dist/array.d.ts

@@ -51,7 +51,7 @@ export declare function dot(a: ReadonlyVec, b: ReadonlyVec): Float;
  * @param out the output matrix
  * @returns out = [M]T
  */
-export declare function tr(n: Int, m: ReadonlyVec, out: Vec): Vec;
+export declare function transpose(n: Int, m: ReadonlyVec, out: Vec): Vec;
 /**
  * Calculate matrix multiplication of a * b, where size of a is (rr * n), and b is (n * rc).
  * @param n matrix order