PointerTracker: introduce the adjusted space

docs/api/pointer-tracker.md

@@ -8,9 +8,14 @@ A [tracker](tracker.md) of [pointers](trackable-pointer.md). It consumes data fr
 
 ### AR.Tracker.Pointer
 
-`AR.Tracker.Pointer(): PointerTracker`
+`AR.Tracker.Pointer(options: object): PointerTracker`
 
-Create a new `PointerTracker`.
+Create a new `PointerTracker` with the specified `options`.
+
+**Arguments**
+
+* `options: object, optional`. An object with the following keys (all are optional):
+    * `space: string`. The [space](#space) in which pointers will be located. Defaults to `"normalized"`.
 
 **Returns**
 
@@ -19,7 +24,11 @@ A new `PointerTracker`.
 **Example**
 
 ```js
+// Use default settings
 const pointerTracker = AR.Tracker.Pointer();
+
+// Track pointers in adjusted space
+const pointerTracker = AR.Tracker.Pointer({ space: 'adjusted' });
 ```
 
 ## Properties
@@ -28,4 +37,18 @@ const pointerTracker = AR.Tracker.Pointer();
 
 `tracker.type: string, read-only`
 
-The string `"pointer-tracker"`.
+The string `"pointer-tracker"`.
+
+### space
+
+`tracker.space: string, read-only`
+
+The space in which pointers are located. You may set it when instantiating the tracker. Possible values: `"normalized"` or `"adjusted"`.
+
+- In `"normalized"` space, pointers are located in [-1,1]x[-1,1]. The origin of the space is at the center of the [viewport](viewport.md). The x-axis points to the right and the y-axis points up. This is the default space.
+
+- The `"adjusted"` space is similar to the normalized space, except that it is scaled so that it matches the [aspect ratio](viewport.md#aspectratio) of the viewport.
+
+    Pointers in adjusted space are contained in normalized space, but unless the viewport is a square, one of their coordinates, x or y, will no longer range from -1 to +1. It will range from *-s* to *+s*, where *s = min(a, 1/a)*. In this expression, *a* is the aspect ratio of the viewport and *s* is less than or equal to 1.
+
+    Selecting the adjusted space is useful for making sure that pointer speeds are equivalent in both axes and for preserving movement curves. Speeds are not equivalent and movement curves are not preserved by default because the normalized space is a square, whereas the viewport is a rectangle.

docs/api/trackable-pointer.md

@@ -4,7 +4,7 @@ A [trackable](trackable.md) that represents a pointer tracked by a [PointerTrack
 
 A pointer is an abstraction that represents an instance of user input that targets one or more coordinates on a screen. For example, each point of contact between fingers and a multitouch screen generate a pointer. Devices such as a mouse and a pen/stylus also generate pointers.
 
-Pointers are positioned in the [viewport](viewport.md). Their positions are given in normalized units, which range from -1 to +1. The center of the viewport is at (0,0). The top right corner is at (1,1). The bottom left corner is at (-1,-1).
+Pointers are located in the [viewport](viewport.md). Their positions are given in [space units](pointer-tracker.md#space). By default, space units are normalized units, which range from -1 to +1. In normalized space, the center of the viewport is at (0,0). The top right corner is at (1,1). The bottom left corner is at (-1,-1).
 
 *Since:* 0.4.0
 
@@ -32,7 +32,7 @@ The phase of the pointer. It's one of the following strings:
 
 `pointer.position: Vector2, read-only`
 
-The current position of the pointer, given in normalized units. See also: [Viewer.raycast](viewer.md#raycast), [Viewport.convertToPixels](viewport.md#converttopixels).
+The current position of the pointer, given in space units. See also: [PointerTracker.space](pointer-tracker.md#space), [Viewer.raycast](viewer.md#raycast), [Viewport.convertToPixels](viewport.md#converttopixels).
 
 ### initialPosition
 
@@ -50,7 +50,7 @@ The difference between the position of the pointer in this and in the previous f
 
 `pointer.velocity: Vector2, read-only`
 
-The current velocity of the pointer, given in normalized units per second. You can get the current speed of motion by calculating the [magnitude](vector2.md#length) of this vector.
+The current velocity of the pointer, given in space units per second. You can get the current speed of motion by calculating the [magnitude](vector2.md#length) of this vector.
 
 ### elapsedTime
 
@@ -62,7 +62,7 @@ The elapsed time, in seconds, since the tracking of this pointer began.
 
 `pointer.totalDistance: number, read-only`
 
-How much this pointer has moved, in normalized units, since its tracking began. You can get the average speed of motion by calculating the ratio `totalDistance / elapsedTime`.
+How much this pointer has moved, in space units, since its tracking began. You can get the average speed of motion by calculating the ratio `totalDistance / elapsedTime`.
 
 ### isPrimary
 

src/trackers/pointer-tracker/pointer-tracker.ts

@@ -27,7 +27,7 @@ import { TrackablePointer, TrackablePointerPhase } from './trackable-pointer';
 import { PointerSource } from '../../sources/pointer-source';
 import { Vector2 } from '../../geometry/vector2';
 import { Utils, Nullable } from '../../utils/utils';
-import { IllegalOperationError } from '../../utils/errors';
+import { IllegalOperationError, IllegalArgumentError } from '../../utils/errors';
 import { Session } from '../../core/session';
 import { Viewport } from '../../core/viewport';
 
@@ -52,6 +52,38 @@ export interface PointerTrackerOutput extends TrackerOutput
     readonly exports: PointerTrackerResult;
 }
 
+/**
+ * The space in which pointers are located.
+ *
+ * - In "normalized" space, pointers are located in [-1,1]x[-1,1]. The origin
+ *   of the space is at the center of the viewport. The x-axis points to the
+ *   right and the y-axis points up. This is the default space.
+ *
+ * - The "adjusted" space is similar to the normalized space, except that it is
+ *   scaled so that it matches the aspect ratio of the viewport.
+ *
+ *   Pointers in adjusted space are contained in normalized space, but unless
+ *   the viewport is a square, one of their coordinates, x or y, will no longer
+ *   range from -1 to +1. It will range from -s to +s, where s = min(a, 1/a).
+ *   In this expression, a is the aspect ratio of the viewport and s is less
+ *   than or equal to 1.
+ *
+ *   Selecting the adjusted space is useful for making sure that pointer speeds
+ *   are equivalent in both axes and for preserving movement curves. Speeds are
+ *   not equivalent and movement curves are not preserved by default because
+ *   the normalized space is a square, whereas the viewport is a rectangle.
+ */
+export type PointerSpace = 'normalized' | 'adjusted'; // | 'viewport';
+
+/**
+ * Options for instantiating a PointerTracker
+ */
+export interface PointerTrackerOptions
+{
+    /** the space in which pointers will be located */
+    space?: PointerSpace;
+}
+
 /** Convert event type to trackable pointer phase */
 const EVENTTYPE2PHASE: Record<string, TrackablePointerPhase> = {
     'pointerdown': 'began',
@@ -62,6 +94,11 @@ const EVENTTYPE2PHASE: Record<string, TrackablePointerPhase> = {
     'pointerenter': 'began',
 };
 
+/** Default options for instantiating a PointerTracker */
+const DEFAULT_OPTIONS: Readonly<Required<PointerTrackerOptions>> = {
+    space: 'normalized'
+};
+
 
 
 
@@ -76,6 +113,9 @@ export class PointerTracker implements Tracker
     /** the viewport */
     private _viewport: Nullable<Viewport>;
 
+    /** pointer space */
+    private _space: PointerSpace;
+
     /** active pointers */
     private _activePointers: Map<number, TrackablePointer>;
 
@@ -99,13 +139,20 @@ export class PointerTracker implements Tracker
 
 
 
+
+
+
     /**
      * Constructor
+     * @param options
      */
-    constructor()
+    constructor(options: PointerTrackerOptions)
     {
+        const settings = this._buildSettings(options);
+
         this._source = null;
         this._viewport = null;
+        this._space = settings.space;
         this._activePointers = new Map();
         this._newPointers = new Map();
         this._idMap = new Map();
@@ -117,6 +164,21 @@ export class PointerTracker implements Tracker
     }
 
     /**
+     * Build a full and validated options object
+     * @param options
+     * @returns validated options with defaults
+     */
+    private _buildSettings(options: PointerTrackerOptions): Required<PointerTrackerOptions>
+    {
+        const settings: Required<PointerTrackerOptions> = Object.assign({}, DEFAULT_OPTIONS, options);
+
+        if(settings.space != 'normalized' && settings.space != 'adjusted')
+            throw new IllegalArgumentError(`Invalid pointer space: "${settings.space}"`);
+
+        return settings;
+    }
+
+    /**
      * The type of the tracker
      */
     get type(): string
@@ -283,13 +345,27 @@ export class PointerTracker implements Tracker
                     continue;
             }
 
-            // determine the current position
+            // determine the current position in normalized space
             const absX = event.pageX - (rect.left + window.scrollX);
             const absY = event.pageY - (rect.top + window.scrollY);
             const relX = 2 * absX / rect.width - 1; // convert to [-1,1]
             const relY = -(2 * absY / rect.height - 1); // flip Y axis
             const position = new Vector2(relX, relY);
 
+            // scale the normalized space so that it matches the aspect ratio of the viewport
+            if(this._space == 'adjusted') {
+                const a = this._viewport!.aspectRatio;
+
+                if(a >= 1) {
+                    // landscape
+                    position._set(relX, relY / a);
+                }
+                else {
+                    // portrait
+                    position._set(relX * a, relY);
+                }
+            }
+
             // determine the position delta
             const deltaPosition = !previous ? Vector2.ZERO :
                                   position._clone()._subtract(previous.position);
@@ -360,6 +436,15 @@ export class PointerTracker implements Tracker
     }
 
     /**
+     * The space in which pointers are located.
+     * You may set it when instantiating the tracker.
+     */
+    get space(): PointerSpace
+    {
+        return this._space;
+    }
+
+    /**
      * Generate tracker output
      * @returns a new PointerTrackerOutput object
      */

src/trackers/pointer-tracker/trackable-pointer.ts

@@ -44,7 +44,7 @@ export interface TrackablePointer extends Trackable
     /** the phase of the pointer */
     readonly phase: TrackablePointerPhase;
 
-    /** current position in normalized units [-1,1]x[-1,1] */
+    /** current position, given in space units */
     readonly position: Vector2;
 
     /** the difference between the position of the pointer in this and in the previous frame */
@@ -53,13 +53,13 @@ export interface TrackablePointer extends Trackable
     /** the position of the pointer when its tracking began */
     readonly initialPosition: Vector2;
 
-    /** current velocity, given in normalized units per second */
+    /** current velocity, given in space units per second */
     readonly velocity: Vector2;
 
     /** elapsed time, in seconds, since the tracking of this pointer began */
     readonly elapsedTime: number;
 
-    /** how much this pointer has moved, in normalized units, since its tracking began */
+    /** how much this pointer has moved, in space units, since its tracking began */
     readonly totalDistance: number;
 
     /** whether or not this is the primary pointer for this type */

src/trackers/tracker-factory.ts

@@ -21,7 +21,7 @@
  */
 
 import { ImageTracker, ImageTrackerOptions } from './image-tracker/image-tracker';
-import { PointerTracker } from './pointer-tracker/pointer-tracker';
+import { PointerTracker, PointerTrackerOptions } from './pointer-tracker/pointer-tracker';
 
 /**
  * Tracker factory
@@ -48,9 +48,10 @@ export class TrackerFactory
 
     /**
      * Create a Pointer Tracker
+     * @param options
      */
-    static Pointer(): PointerTracker
+    static Pointer(options: PointerTrackerOptions = {}): PointerTracker
     {
-        return new PointerTracker();
+        return new PointerTracker(options);
     }
 }