Image Tracker: introduce spaces NIS, NDC

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

@@ -58,12 +58,26 @@ import { Pose } from '../../geometry/pose';
 A few definitions:
 
 1. Viewport size:
-    size of the drawing buffer of the background canvas = size of the input
-    media, in pixels
+   size of the drawing buffer of the background canvas, which is the same as
+   the size in pixels of the input media (typically a video).
 
 2. AR screen size:
-    size for image processing operations, determined by the resolution of the
-    tracker and by the aspect ratio of the input media
+   size in pixels used for image processing operations. It's determined by the
+   resolution of the tracker and by the aspect ratio of the input media.
+
+3. Raster space:
+   an image space whose top-left coordinate is (0,0) and whose bottom-right
+   coordinate is (w-1,h-1), where (w,h) is its size. The y-axis grows downwards.
+
+4. AR Screen Space (ASS):
+   a raster space whose size is the AR screen size.
+
+5. Normalized Image Space (NIS):
+   a raster space whose size is N x N, where N = NIS_SIZE.
+
+6. Normalized Device Coordinates (NDC):
+   the normalized 2D space [-1,1]x[-1,1]. The origin is at the center. Also,
+   the y-axis grows upwards.
 
 */
 
@@ -102,9 +116,15 @@ export interface ImageTrackerOutput extends TrackerOutput
     /** optional keypoints */
     readonly keypoints?: SpeedyKeypoint[];
 
+    /** optional keypoints */
+    readonly keypointsNIS?: SpeedyKeypoint[];
+
     /** optional polyline for testing */
     readonly polyline?: SpeedyPoint2[];
 
+    /** optional polyline for testing */
+    readonly polylineNDC?: SpeedyPoint2[];
+
     /** optional 3x4 camera matrix in AR screen space */
     readonly cameraMatrix?: SpeedyMatrix;
 
@@ -311,8 +331,7 @@ export class ImageTracker extends AREventTarget<ImageTrackerEventType> implement
         // compute the screen size for image processing purposes
         // note: this may change over time...!
         const media = this._source!._internalMedia;
-        const aspectRatio = media.width / media.height;
-        const screenSize = Utils.resolution(this._resolution, aspectRatio);
+        const screenSize = this._computeScreenSize();
 
         // run the active state
         const activeState = this._state[this._activeStateName];
@@ -330,6 +349,21 @@ export class ImageTracker extends AREventTarget<ImageTrackerEventType> implement
     }
 
     /**
+     * Compute the current size of the AR screen space
+     * Note that this may change over time
+     * @returns size
+     * @internal
+     */
+    _computeScreenSize(): SpeedySize
+    {
+        const media = this._source!._internalMedia;
+        const aspectRatio = media.width / media.height;
+        const screenSize = Utils.resolution(this._resolution, aspectRatio);
+
+        return screenSize;
+    }
+
+    /**
      * Get reference image
      * @param keypointIndex -1 if not found
      * @returns reference image

src/trackers/image-tracker/settings.ts

@@ -29,8 +29,11 @@ export const TRAIN_MAX_KEYPOINTS = 1024; //512;
 /** Percentage relative to the screen size adjusted to the aspect ratio of the reference image */
 export const TRAIN_IMAGE_SCALE = 0.8; // ORB is not scale invariant
 
+/** Width and height of the Normalized Image Space (NIS) */
+export const NIS_SIZE = 1024; // keypoint positions are stored as fixed point
+
 /** Normalized width & height of an image target, in pixels */
-export const TRAIN_TARGET_NORMALIZED_SIZE = 1024; // keypoint positions are stored as fixed point
+export const TRAIN_TARGET_NORMALIZED_SIZE = NIS_SIZE; // keypoint positions are stored as fixed point
 
 /** Used to identify the best maches */
 export const SCAN_MATCH_RATIO = 0.7; // usually a value in [0.6, 0.8]
@@ -54,7 +57,13 @@ export const SCAN_MIN_MATCHES = 20; //30;
 export const SCAN_CONSECUTIVE_FRAMES = 30;//15;//45;
 
 /** Reprojection error, in pixels, used when estimating a motion model (scanning state) */
-export const SCAN_RANSAC_REPROJECTIONERROR = 5;
+//export const SCAN_RANSAC_REPROJECTIONERROR = 5;
+
+/** Reprojection error, in NIS pixels, used when estimating a motion model (scanning state) */
+export const SCAN_RANSAC_REPROJECTIONERROR_NIS = (NIS_SIZE * 0.02) | 0;
+
+/** Reprojection error, in NDC, used when estimating a motion model (scanning state) */
+export const SCAN_RANSAC_REPROJECTIONERROR_NDC = SCAN_RANSAC_REPROJECTIONERROR_NIS / (NIS_SIZE / 2);
 
 /** Number of tables used in the LSH-based keypoint matching */
 export const SCAN_LSH_TABLES = 8; // up to 32
@@ -119,6 +128,14 @@ export const TRACK_REFINEMENT_ITERATIONS = 3;
 /** Reprojection error, in pixels, used when estimating a motion model (tracking state) */
 export const TRACK_RANSAC_REPROJECTIONERROR = 3; //2.5;
 
+// FIXME
+
+/** Reprojection error, in NIS pixels, used when estimating a motion model (tracking state) */
+export const TRACK_RANSAC_REPROJECTIONERROR_NIS = (NIS_SIZE * 0.0125) | 0;
+
+/** Reprojection error, in NDC, used when estimating a motion model (tracking state) */
+export const TRACK_RANSAC_REPROJECTIONERROR_NDC = TRACK_RANSAC_REPROJECTIONERROR_NIS / (NIS_SIZE / 2);
+
 /** We use a N x N grid to spatially distribute the keypoints in order to compute a better homography */
 export const TRACK_GRID_GRANULARITY = 10; //20; // the value of N