remote-calibrator 0.3.0 → 0.5.0-beta.3

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Latency for gaze and viewing distance tracking. The latency is calculated by comparing the timestamps of the moment when the video stream is fed into the model for estimation and when the result is produced and recorded. You can access it by `data.value.latencyMs` where `data` is the argument passed into the callback function of `.trackGaze()` and `.trackDistance`.
+- Viewing distance monitoring. Three new options for `.trackDistance()` are added: `desiredDistanceCm` (default undefined), `desiredDistanceTolerance` (default 0.1), and `desiredDistanceMonitor` (default false). If a number is given for `desiredDistanceCm`, the program will check the viewing distance and call for "Move CLOSER." or "Move FURTHER." to the participants, until the participant moved to the desired distance and the experiment will resume. Setting `desiredDistanceMonitor` to true will repeat this process through the rest of the experiment.
+- `debug` and `i18n` options of `.panel()`. When set to `true`, The first one adds some useful options, e.g., to skip calibration, for you to use when debugging. The second one adds a language picker for participants to choose their own languages (the default choice is always the one set on initiation).
+- Update near point tracking to be more accurate. The webcam is assumed to be at the top middle of the screen.
+
+### Changed
+
+- Rename "Head Tracking" to "Distance Tracking" globally.
+- Polish translations.
+
 ## [0.3.0] - 2021-10-16
 
 ### Added

package/README.md

@@ -45,18 +45,18 @@ RemoteCalibrator.measureDistance({}, data => {
 
 ## Functions
 
-| Task                                      | Functions                                                                                                                                                                                        |
-| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| [🎬 Initialize](#-initialize)             | [`init()`](#-initialize) (always required)                                                                                                                                                       |
-| [🍱 Panel](#-panel)                       | [`async panel()`](#-panel) `removePanel()` `resetPanel()`                                                                                                                                        |
-| [🖥️ Screen](#️-screen)                    | [Display Pixel Dimensions](#measure-display-pixels) [`screenSize()`](#measure-screen-size)                                                                                                       |
-| [📏 Viewing Distance](#-viewing-distance) | [`measureDistance()`](#-viewing-distance)                                                                                                                                                        |
-| [🙂 Head Tracking](#-head-tracking)       | (viewing distance and [near point](#near-point)) [`trackDistance()`](#-head-tracking) [`async getDistanceNow()`](#async-get-distance-now) [Lifecycle](#lifecycle) [Others](#others)              |
-| [👀 Gaze](#-gaze)                         | [`trackGaze()`](#start-tracking) [`async getGazeNow()`](#async-get-gaze-now) [`calibrateGaze()`](#calibrate) [`getGazeAccuracy()`](#get-accuracy-) [Lifecycle](#lifecycle-1) [Others](#others-1) |
-| [💻 Environment](#-environment)           | [System and Browser Environment](#-environment)                                                                                                                                                  |
-| [💄 Customization](#-customization)       | `backgroundColor()` `videoOpacity()` `showCancelButton()`                                                                                                                                        |
-| [📔 Other Functions](#-other-functions)   | `checkInitialized()` `getFullscreen()` `newLanguage()`                                                                                                                                           |
-| [🎣 Getters](#-getters)                   | [Experiment](#experiment) [Environment](#environment) [i18n](#i18n) [All Data](#all-data) [Others](#others-2)                                                                                    |
+| Task                                        | Functions                                                                                                                                                                                                                    |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [🎬 Initialize](#-initialize)               | [`init()`](#-initialize) (always required)                                                                                                                                                                                   |
+| [🍱 Panel](#-panel)                         | [`async panel()`](#-panel) `removePanel()` `resetPanel()`                                                                                                                                                                    |
+| [🖥️ Screen](#️-screen)                      | [Display Pixel Dimensions](#measure-display-pixels) [`screenSize()`](#measure-screen-size)                                                                                                                                   |
+| [📏 Viewing Distance](#-viewing-distance)   | [`measureDistance()`](#-viewing-distance)                                                                                                                                                                                    |
+| [🙂 Distance Tracking](#-distance-tracking) | (viewing distance and [near point](#near-point)) [`trackDistance()`](#-distance-tracking) [`async getDistanceNow()`](#async-get-distance-now) [`checkDistance()`](#check-distance) [Lifecycle](#lifecycle) [Others](#others) |
+| [👀 Gaze](#-gaze)                           | [`trackGaze()`](#start-tracking) [`async getGazeNow()`](#async-get-gaze-now) [`calibrateGaze()`](#calibrate) [`getGazeAccuracy()`](#get-accuracy-) [Lifecycle](#lifecycle-1) [Others](#others-1)                             |
+| [💻 Environment](#-environment)             | [System and Browser Environment](#-environment)                                                                                                                                                                              |
+| [💄 Customization](#-customization)         | `backgroundColor()` `videoOpacity()` `showCancelButton()`                                                                                                                                                                    |
+| [📔 Other Functions](#-other-functions)     | `checkInitialized()` `getFullscreen()` `newLanguage()`                                                                                                                                                                       |
+| [🎣 Getters](#-getters)                     | [Experiment](#experiment) [Environment](#environment) [i18n](#i18n) [All Data](#all-data) [Others](#others-2)                                                                                                                |
 
 Arguments in square brackets are optional, e.g. `init([options, [callback]])` means both `options` configuration and the `callback` function are optional, but you have to put `options`, e.g., `{}`, if you want to call the callback function. The default values of `options` are listed in each section with explanation.
 
@@ -226,15 +226,15 @@ Pass `{ value, timestamp, method }` (equivalent to `RemoteCalibrator.viewingDist
 }
 ```
 
-### 🙂 Head Tracking
+### 🙂 Distance Tracking
 
 ```js
 .trackDistance([options, [callbackStatic, [callbackTrack]]])
 ```
 
-Measure the viewing distance and then predict the real-time distance based on the change of the interpupillary distance, measured by [face landmarks](https://github.com/tensorflow/tfjs-models/tree/master/face-landmarks-detection). `callbackStatic` is called after getting the blind spot result and `callbackTrack` is called every time a new result from estimation is derived.
+Measure the viewing distance and then predict the real-time distance based on the change of the inter-pupillary distance, measured by [face landmarks](https://github.com/tensorflow/tfjs-models/tree/master/face-landmarks-detection). `callbackStatic` is called after getting the blind spot result and `callbackTrack` is called every time a new result from estimation is derived.
 
-Pass `{ value: { viewingDistanceCm, nearPointCm: { x, y } }, timestamp, method }` to callback.
+Pass `{ value: { viewingDistanceCm, nearPointCm: { x, y }, latencyMs }, timestamp, method }` to callback.
 
 `method` can be either `"BlindSpot"` (for measures from blind spot tests) or `"FaceMesh"` (for later dynamic estimates).
 
@@ -247,12 +247,14 @@ Pass `{ value: { viewingDistanceCm, nearPointCm: { x, y } }, timestamp, method }
   showVideo: true,
   showFaceOverlay: false,
   decimalPlace: 1,
-  // Measurement per second
-  framerate: 3,
+  framerate: 3, // Measurement per second
+  desiredDistanceCm: undefined,
+  desiredDistanceTolerance: 0.1, // Range [0.1, 1]
+  desiredDistanceMonitor: false,
   // Near point
   nearPoint: true,
   showNearPoint: false,
-  headline: "🙂 Set up for Head Tracking",
+  headline: "🙂 Set up for Distance Tracking",
   description: "...",
 }
 ```
@@ -265,6 +267,14 @@ Pass `{ value: { viewingDistanceCm, nearPointCm: { x, y } }, timestamp, method }
 
 You can pause active distance tracking, and use this function to get the latest distance at the moment when the user makes reactions. If no callback function is passed in, it will use the one from `.trackDistance()` as the default.
 
+#### Check Distance
+
+```js
+.checkDistance(desiredCm, errorTolerance)
+```
+
+Check the current viewing distance and compare it to the desired distance. Guide the participant to the target distance if needed.
+
 #### Near Point
 
 The observer's near point is the orthogonal nearest viewing point in the screen, or the plane containing the screen. To track the near point, we assume that the webcam view is orthogonal to the display, and it is placed around 0.5cm above the top center of the screen (e.g., the built-in webcam of a MacBook). Our method is based on the Facemesh model and can give you an approximate estimation of the near point.
@@ -438,7 +448,7 @@ Use the following keywords to retrieve the whole dataset.
 - `.screenData`
 - `.viewingDistanceData`
 - `.nearPointData`
-- `.PDData` (Interpupillary distance data)
+- `.PDData` (Inter-pupillary distance data)
 - `.gazeData`
 - `.fullscreenData`
 - `.environmentData`

package/homepage/example.js

@@ -202,9 +202,11 @@ function trackViewingDistance(e) {
   let trackP
   RemoteCalibrator.trackDistance(
     {
-      showVideo: false,
+      showVideo: true,
       nearPoint: true,
       showNearPoint: true,
+      desiredDistanceCm: 60,
+      desiredDistanceMonitor: true,
     },
     distanceData => {
       measureDistanceCallback(distanceData)
@@ -219,7 +221,9 @@ function trackViewingDistance(e) {
           data.method
         } method. The near point is at [${data.value.nearPointCm.x} cm, ${
           data.value.nearPointCm.y
-        } cm] compared to the center of the screen.`
+        } cm] compared to the center of the screen. Latency is ${
+          data.value.latencyMs
+        } ms.`
       )
     }
   )
@@ -317,7 +321,9 @@ function trackGaze(e) {
       gazeP.innerHTML = gotData(
         `The gaze position is [${data.value.x} px, ${
           data.value.y
-        } px] at ${parseTimestamp(data.timestamp)}.`
+        } px] at ${parseTimestamp(data.timestamp)}. Latency is ${
+          data.value.latencyMs
+        } ms.`
       )
     }
   )

package/i18n/fetch-languages-sheets.js

@@ -14,7 +14,7 @@ async function processLanguageSheet() {
   const rows = await googleSheets.spreadsheets.values.get({
     auth,
     spreadsheetId,
-    range: 'Sheet1',
+    range: 'Translations',
   })
 
   const rowsJSON = XLSX.utils.sheet_to_json(
@@ -34,9 +34,10 @@ async function processLanguageSheet() {
   for (let phrase in data) {
     for (let lang in data[phrase]) {
       if (data[phrase][lang].includes('XX'))
-        data[phrase][lang] = data[phrase][lang]
-          .replace('XXX', 'xxx')
-          .replace('XX', 'xx')
+        while (data[phrase][lang].includes('XX'))
+          data[phrase][lang] = data[phrase][lang]
+            .replace('XXX', 'xxx')
+            .replace('XX', 'xx')
     }
   }