Simplify Transform classes. Use a single class

docs/api/pose.md

@@ -6,6 +6,6 @@ A pose represents a position and an orientation in 3D space.
 
 ### transform
 
-`pose.transform: RigidTransform, read-only`
+`pose.transform: Transform, read-only`
 
-The underlying [rigid transform](rigid-transform.md).
+The underlying [transform](transform.md).

docs/api/rigid-transform.md

@@ -1,17 +0,0 @@
-# RigidTransform
-
-A RigidTransform represents a rotation and a translation in 3D space.
-
-## Properties
-
-### matrix
-
-`transform.matrix: SpeedyMatrix, read-only`
-
-A 4x4 matrix encoding the transform.
-
-### inverse
-
-`transform.inverse: RigidTransform, read-only`
-
-The inverse transform.

docs/api/transform.md

@@ -0,0 +1,17 @@
+# Transform
+
+A Transform represents a rotation and a translation in 3D space.
+
+## Properties
+
+### matrix
+
+`transform.matrix: SpeedyMatrix, read-only`
+
+A 4x4 matrix encoding the transform.
+
+### inverse
+
+`transform.inverse: Transform, read-only`
+
+The inverse transform.

mkdocs.yml

@@ -94,7 +94,7 @@ nav:
       - 'ViewerPose': 'api/viewer-pose.md'
       - 'View': 'api/view.md'
       - 'PerspectiveView': 'api/perspective-view.md'
-      - 'RigidTransform': 'api/rigid-transform.md'
+      - 'Transform': 'api/transform.md'
       - 'Quaternion': 'api/quaternion.md'
       - 'Vector3': 'api/vector3.md'
     - 'Visualization':

src/geometry/pose.ts

@@ -17,23 +17,20 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  *
  * pose.ts
- * A pose represents a position and an orientation in a 3D space
+ * A pose represents a position and an orientation in 3D space
  */
 
-import Speedy from 'speedy-vision';
-import { SpeedyMatrix } from 'speedy-vision/types/core/speedy-matrix';
-import { RigidTransform, StandardTransform } from './transform';
+import { Transform } from './transform';
 
 
 
 /**
- * A pose represents a position and an orientation in a 3D space
- * (and sometimes a scale, too...)
+ * A pose represents a position and an orientation in 3D space
  */
 export class Pose
 {
-    /** A transform in 3D world space */
-    private _transform: StandardTransform;
+    /** Internal transform */
+    private _transform: Transform;
 
 
 
@@ -41,7 +38,7 @@ export class Pose
      * Constructor
      * @param transform usually a rigid transform in a 3D space (e.g., world space, viewer space or other)
      */
-    constructor(transform: StandardTransform)
+    constructor(transform: Transform)
     {
         this._transform = transform;
     }
@@ -50,8 +47,8 @@ export class Pose
      * A transform describing the position and the orientation
      * of the pose relative to the 3D space to which it belongs
      */
-    get transform(): StandardTransform
+    get transform(): Transform
     {
         return this._transform;
     }
-}
+}

src/geometry/transform.ts

@@ -17,160 +17,81 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  *
  * transform.ts
- * 3D geometrical transforms
+ * 3D transforms
  */
 
 import Speedy from 'speedy-vision';
 import { SpeedyMatrix } from 'speedy-vision/types/core/speedy-matrix';
-import { IllegalArgumentError, IllegalOperationError } from '../utils/errors';
+import { Nullable } from '../utils/utils';
+import { IllegalArgumentError } from '../utils/errors';
+
 
 /**
- * A 3D transformation
+ * A Transform represents a position, a rotation and a scale in 3D space
  */
-abstract class BaseTransform
+export class Transform
 {
-    /** 4x4 matrix describing the transformation */
-    protected readonly _matrix: SpeedyMatrix;
+    /** transformation matrix */
+    private readonly _matrix: SpeedyMatrix;
+
+    /** inverse transform, computed lazily */
+    private _inverse: Nullable<Transform>;
 
 
 
     /**
      * Constructor
-     * @param matrix a 4x4 matrix
+     * @param matrix a 4x4 transformation matrix. You should ensure that its form is T * R * S (translation * rotation * scale).
      */
     constructor(matrix: SpeedyMatrix)
     {
         if(matrix.rows != 4 || matrix.columns != 4)
-            throw new IllegalArgumentError('A 3D transform expects a 4x4 matrix');
+            throw new IllegalArgumentError('A Transform expects a 4x4 transformation matrix');
 
         this._matrix = matrix;
+        this._inverse = null;
     }
 
     /**
-     * The 4x4 transformation matrix (read-only)
+     * The 4x4 transformation matrix
      */
     get matrix(): SpeedyMatrix
     {
         return this._matrix;
     }
-}
 
-/**
- * An invertible 3D transformation
- */
-class InvertibleTransform extends BaseTransform
-{
     /**
-     * Constructor
-     * @param matrix a 4x4 matrix
+     * The inverse transform
      */
-    constructor(matrix: SpeedyMatrix)
+    get inverse(): Transform
     {
-        // WARNING: we do not check if the matrix actually encodes an invertible transform!
-        super(matrix);
-    }
+        if(this._inverse === null)
+            this._inverse = new Transform(Transform._invert(this._matrix));
 
-    /**
-     * The inverse of the transform
-     */
-    get inverse(): InvertibleTransform
-    {
-        const inverseMatrix = Speedy.Matrix(this._matrix.inverse());
-        return new InvertibleTransform(inverseMatrix);
+        return this._inverse;
     }
-}
-
-/**
- * A 3D transformation described by translation, rotation and scale
- */
-export class StandardTransform extends InvertibleTransform
-{
-    // TODO: position, rotation and scale attributes
 
     /**
-     * Constructor
-     * @param matrix a 4x4 matrix
+     * Compute the inverse of a transformation matrix
+     * @param matrix the transformation matrix to invert
+     * @returns the inverse matrix
      */
-    constructor(matrix: SpeedyMatrix)
-    {
-        // WARNING: we do not check if the matrix actually encodes a standard transform!
-        super(matrix);
-    }
-
-    /**
-     * The inverse of the transform
-     */
-    get inverse(): StandardTransform
+    private static _invert(matrix: SpeedyMatrix): SpeedyMatrix
     {
         /*
 
-        The inverse of a 4x4 standard transform T * R * S...
+        The inverse of a 4x4 transform T * R * S
 
         [  RS  t  ]    is    [  ZR' -ZR't ]
         [  0'  1  ]          [  0'    1   ]
 
         where S is 3x3, R is 3x3, t is 3x1, 0' is 1x3 and Z is the inverse of S
 
-        */
-
-        return super.inverse as StandardTransform;
-    }
-}
-
-/**
- * A 3D transformation described by position and orientation
- */
-export class RigidTransform extends StandardTransform
-{
-    // TODO: position and rotation attributes (need to decompose the matrix)
-
-    /**
-     * Constructor
-     * @param matrix a 4x4 matrix
-     */
-    constructor(matrix: SpeedyMatrix)
-    {
-        // WARNING: we do not check if the matrix actually encodes a rigid transform!
-        super(matrix);
-    }
-
-    /**
-     * The inverse of the transform
-     */
-    get inverse(): RigidTransform
-    {
-        /*
-
-        The inverse of a 4x4 rigid transform
-
-        [  R   t  ]    is    [  R'  -R't  ]
-        [  0'  1  ]          [  0'    1   ]
-
-        where R is 3x3, t is 3x1 and 0' is 1x3
+        R is a rotation matrix; S is a diagonal matrix
 
         */
 
-        const m = this._matrix.read();
-        if(m[15] == 0) // error? abs()??
-            throw new IllegalOperationError('Not a rigid transform');
-        const s = 1 / m[15]; // should be 1 (normalize homogeneous coordinates)
-
-        const r11 = m[0] * s, r12 = m[4] * s, r13 = m[8] * s;
-        const r21 = m[1] * s, r22 = m[5] * s, r23 = m[9] * s;
-        const r31 = m[2] * s, r32 = m[6] * s, r33 = m[10] * s;
-        const t1 = m[12] * s, t2 = m[13] * s, t3 = m[14] * s;
-
-        const rt1 = r11 * t1 + r21 * t2 + r31 * t3;
-        const rt2 = r12 * t1 + r22 * t2 + r32 * t3;
-        const rt3 = r13 * t1 + r23 * t2 + r33 * t3;
-
-        const inverseMatrix = Speedy.Matrix(4, 4, [
-            r11, r12, r13, 0,
-            r21, r22, r23, 0,
-            r31, r32, r33, 0,
-            -rt1, -rt2, -rt3, 1
-        ]);
-
-        return new RigidTransform(inverseMatrix);
+        // this works, but this inverse is straightforward
+        return Speedy.Matrix(matrix.inverse());
     }
-}
+}

src/geometry/viewer-pose.ts

@@ -23,7 +23,7 @@
 import Speedy from 'speedy-vision';
 import { SpeedyMatrix } from 'speedy-vision/types/core/speedy-matrix';
 import { Pose } from './pose';
-import { RigidTransform } from './transform';
+import { Transform } from './transform';
 import { CameraModel } from './camera-model';
 
 
@@ -46,14 +46,15 @@ export class ViewerPose extends Pose
     {
         // compute the view matrix and its inverse in AR screen space
         const viewMatrix = ViewerPose._computeViewMatrix(camera);
-        const inverseTransform = new RigidTransform(viewMatrix);
+        const inverseTransform = new Transform(viewMatrix); // from world space to view space
+        const transform = inverseTransform.inverse; // from view space to world space
 
-        super(inverseTransform.inverse);
+        super(transform);
         this._viewMatrix = viewMatrix;
     }
 
     /**
-     * This 4x4 matrix moves 3D points from world space to viewer space. We
+     * This 4x4 matrix moves 3D points from world space to view space. We
      * assume that the camera is looking in the direction of the negative
      * z-axis (WebGL-friendly)
      */

src/geometry/viewer.ts

@@ -21,13 +21,11 @@
  */
 
 import Speedy from 'speedy-vision';
-import { SpeedyMatrix } from 'speedy-vision/types/core/speedy-matrix';
 import { CameraModel } from './camera-model';
 import { Pose } from './pose';
 import { ViewerPose } from './viewer-pose';
 import { View, PerspectiveView } from './view';
-import { StandardTransform } from './transform';
-import { IllegalOperationError } from '../utils/errors';
+import { Transform } from './transform';
 
 
 
@@ -97,7 +95,7 @@ export class Viewer
         const viewMatrix = this._pose.viewMatrix;
         const modelViewMatrix = Speedy.Matrix(viewMatrix.times(modelMatrix));
 
-        const transform = new StandardTransform(modelViewMatrix);
+        const transform = new Transform(modelViewMatrix);
         return new Pose(transform);
     }
 }

src/trackers/image-tracker/states/tracking.ts

@@ -46,7 +46,7 @@ import { ReferenceImage } from '../reference-image';
 import { CameraModel } from '../../../geometry/camera-model';
 import { Viewer } from '../../../geometry/viewer';
 import { Pose } from '../../../geometry/pose';
-import { RigidTransform, StandardTransform } from '../../../geometry/transform';
+import { Transform } from '../../../geometry/transform';
 import { IllegalOperationError, IllegalArgumentError, TrackingError } from '../../../utils/errors';
 import {
     TRACK_RECTIFIED_BORDER, TRACK_CLIPPING_BORDER, TRACK_MIN_MATCHES, TRACK_LOST_TOLERANCE,
@@ -386,7 +386,7 @@ export class ImageTrackerTrackingState extends ImageTrackerState
             // (identity transform). We also perform a change of coordinates,
             // so that we move out from pixel space and into normalized space
             const modelMatrix = this._camera.denormalizer(); // ~ "identity matrix"
-            const transform = new StandardTransform(modelMatrix);
+            const transform = new Transform(modelMatrix);
             const pose = new Pose(transform);
 
             // given the current state of the camera model, we get a viewer