remote-calibrator 0.3.0-beta.0 → 0.3.0-beta.4

package/.eslintrc.js

@@ -19,9 +19,9 @@ module.exports = {
   ignorePatterns: [
     'webpack.config.js',
     '.eslintrc.js',
+    'i18n.js',
     'WebGazer/',
     'lib/',
     'server.js',
-    'serverHTTPS.js',
   ],
 }

package/.husky/pre-commit

@@ -1,4 +1,4 @@
 #!/bin/sh
 . "$(dirname "$0")/_/husky.sh"
 
-npx lint-staged && npm run build && git add lib
+npm run phrases && npx lint-staged && npm run build && git add lib

package/.prettierignore

@@ -2,5 +2,9 @@
 package.json
 package-lock.json
 
+i18n.js
+
 *WebGazer4RC/
 lib/
+
+credentials.json

package/CHANGELOG.md

@@ -9,9 +9,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+**i18n!**
+
+- Internationalization! A full list of supported languages can be found at https://docs.google.com/spreadsheets/d/1UFfNikfLuo8bSromE34uWDuJrMPFiJG3VpoQKdCGkII/edit#gid=0.
+- A few new getters related to languages:
+  - `.userLanguage` (as a part of `.environment()`)
+  - `.language` (e.g., `en-US`, `zh-CN`)
+  - `.languageNameEnglish` (e.g., `English`, `Chinese (Simplified)`)
+  - `.languageNameNative` (e.g., `简体中文`)
+  - `.languageDirection` (`LTR` or `RTL`)
+  - `.languagePhraseSource` (e.g., `Denis Pelli & Peiling Jiang 2021.10.10`)
+  - `.languageData` gets the whole data history of languages.
+  - `.supportedLanguages` gets an array of supported languages.
+- `.newLanguage(lang = 'en-US')` to set a new language for the calibrator.
+- Allows researchers to set language on initialization using the `language` option. Set to `AUTO` (default) will let the calibrator go with the user language.
+- `.isMobile` getter.
+- Call `.environment()` automatically when initializing the calibrator.
+- Instructions in the viewing distance measurement (and head tracking setup) is scrollable to avoid overlapping with the canvas on small screen sizes.
+
+### Changed
+
+- Improved UI and performance for small screens and mobile devices.
+- Take Return instead of Space for confirming screen size measurement.
+
+### Removed
+
+- The responsive arrow in the screen size calibration with credit card.
+
+## [0.2.3] - 2021-10-05
+
+### Added
+
+- (Breaking) Callback function of gaze tracking is split into two functions: `callbackOnCalibrationEnd` that will only be called once when calibration ends, and `callbackTrack` that will be called continuously as the tracking runs (with data parameter passed in).
 - `sparkle` option (default `true`) for measuring and tracking viewing distance. The red dot sparkles at 10 Hz to make it more prominent when absent from the view.
 - Ignore the Return key in screen size calibration.
 
+### Fixed
+
+- Panel final callback function is called multiple times if gaze tracking is the last calibration task.
+
 ## [0.2.2] - 2021-10-04
 
 ### Added
@@ -207,7 +243,8 @@ No new feature updates in this release. Updated dependency packages and the lice
 
 The framework and some basic functions, e.g., screen size calibration. Released for integration testing.
 
-[unreleased]: https://github.com/EasyEyes/remote-calibrator/compare/v0.2.2...develop
+[unreleased]: https://github.com/EasyEyes/remote-calibrator/compare/v0.2.3...develop
+[0.2.3]: https://github.com/EasyEyes/remote-calibrator/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/EasyEyes/remote-calibrator/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/EasyEyes/remote-calibrator/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/EasyEyes/remote-calibrator/compare/v0.1.1...v0.2.0

package/README.md

@@ -52,13 +52,13 @@ RemoteCalibrator.measureDistance({}, data => {
 | [🎬 Initialize](#-initialize)             | [`init()`](#-initialize) (always required)                                                                                                                                                       |
 | [🍱 Panel](#-panel)                       | [`async panel()`](#-panel) `removePanel()` `resetPanel()`                                                                                                                                        |
 | [🖥️ Screen](#️-screen)                    | [`displaySize()`](#measure-display-pixels) [`screenSize()`](#measure-screen-size)                                                                                                                |
-| [📏 Viewing Distance](#-viewing-distance) | `measureDistance()`                                                                                                                                                                              |
+| [📏 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)           | [`environment()`](#-environment)                                                                                                                                                                 |
 | [💄 Customization](#-customization)       | `backgroundColor()` `videoOpacity()` `showCancelButton()`                                                                                                                                        |
-| [📔 Other Functions](#-other-functions)   | `checkInitialized()` `getFullscreen()`                                                                                                                                                           |
-| [🎣 Getters](#-getters)                   | [Experiment](#experiment) [Environment](#environment) [All Data](#all-data) [Others](#others-2)                                                                                                  |
+| [📔 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.
 
@@ -81,8 +81,17 @@ Pass `{ value, timestamp }` (equivalent to `RemoteCalibrator.id`) to callback.
    * A random one will be generated if no value is passed into the function
    */
   id: /* Randomized value */,
-  // Enter fullscreen if set to true
-  // Will be ignored if already in fullscreen mode
+  /**
+   * Set the language, e.g., 'en-US', 'zh-CN'
+   * If set to 'AUTO' (default), the calibrator will try to follow the browser settings
+   * A full list of supported languages can be found at
+   * https://docs.google.com/spreadsheets/d/1UFfNikfLuo8bSromE34uWDuJrMPFiJG3VpoQKdCGkII/edit#gid=0
+   */
+  language: 'AUTO',
+  /**
+   * Enter full screen if set to true
+   * Will be ignored if already in full screen mode
+   */
   fullscreen: false,
 }
 ```
@@ -112,11 +121,9 @@ The `data` passed into the callback function is an [object](https://www.w3school
 ![Panel](./media/panel.png)
 
 ```js
-.panel(tasks, parentQuery, [options, [callback, [resolveOnFinish]]])
+/* async */ .panel(tasks, parentQuery, [options, [callback, [resolveOnFinish]]])
 ```
 
-**Since 0.2.0:** `.panel()` is now an async function.
-
 `.panel()` is a powerful tool to help you set up a graphical user interface for participants to go through step-by-step and calibrate or set up tracking. It is highly customizable: tasks, task order, title, description, and "Done" button can all be customized. It is appended to the parent HTML node as set by `parentQuery`, e.g., if the parent node has id `main-area`, put `#main-area` as the `parentQuery`. Can only run once. Return a JavaScript [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises) that will resolve the `resolveOnFinish` once the "Done" button is pressed.
 
 `tasks` is an array of tasks which can be a string or an object. Valid names are `screenSize`, `displaySize`, `measureDistance`, `trackDistance`, `trackGaze`, `environment` (system information).
@@ -128,7 +135,7 @@ The `data` passed into the callback function is an [object](https://www.w3school
   {
     name: 'trackGaze',
     options: { framerate: 60 }, // Same as setting the options for .trackGaze()
-    callback: gotGaze, // Same as setting the callback for .trackGaze()
+    callbackTrack: gotGaze, // Same as setting the callback for .trackGaze()
   },
   // Tracking viewing distance accepts two callbacks just like .trackDistance()
   {
@@ -300,14 +307,14 @@ The value returned are the horizontal and vertical offsets, in centimeters, comp
 ![Start Gaze Tracking](./media/trackGaze.png)
 
 ```js
-.trackGaze([options, [callback]])
+.trackGaze([options, [callbackOnCalibrationEnd, [callbackTrack]]])
 ```
 
 Use [WebGazer](https://github.com/peilingjiang-DEV/WebGazer). Pop an interface for participants to calibrate their gaze position on the screen (only when this function is called for the first time), then run in the background and continuously predict the current gaze position. Require access to the camera of the participant's computer. The callback function will be executed repeatedly **every time** there's a new prediction.
 
 This function should only be called once, unless you want to change the callback functions for every prediction.
 
-Pass `{ value: { x, y }, timestamp }` (equivalent to `RemoteCalibrator.gazePositionPx`) to callback.
+Pass `{ value: { x, y }, timestamp }` (equivalent to `RemoteCalibrator.gazePositionPx`) to `callbackTrack` function.
 
 ```js
 /* [options] Default value */
@@ -391,7 +398,7 @@ Pop an interface for participants to calibrate their gaze position on the screen
 
 Get the setup information of the experiment, including browser type, device model, operating system family and version, etc. This function does not create its own timestamp, but use the one associated with `id`, i.e. the one created when `init()` is called.
 
-Pass `{ value: { browser, browserVersion, model, manufacturer, engine, system, systemFamily, description, fullDescription }, timestamp }` to callback.
+Pass `{ value: { browser, browserVersion, model, manufacturer, engine, system, systemFamily, description, fullDescription, userLanguage }, timestamp }` to callback.
 
 ### 💄 Customization
 
@@ -403,6 +410,7 @@ Pass `{ value: { browser, browserVersion, model, manufacturer, engine, system, s
 
 - `.checkInitialized()` Check if the model is initialized. Return a boolean.
 - `.getFullscreen()` Get fullscreen mode.
+- `.newLanguage(lang = 'en-US')` Set a new language for the calibrator.
 
 ### 🎣 Getters
 
@@ -424,10 +432,11 @@ Getters will get `null` if no data can be found, i.e. the corresponding function
 
 The associated timestamp of the following items is the one created at initiation, i.e. when `init()` is called.
 
-- `.bot` If the user agent is a bot or not, an empty string will be returned if no bot detected, e.g., `Googlebot (Search bot) by Google Inc.`.
+- `.bot` If the user agent is a bot or not, `null` will be returned if no bot detected, e.g., `Googlebot (Search bot) by Google Inc.`.
 - `.browser` The browser type, e.g., `Safari`, `Chrome`.
 - `.browserVersion` The browser version.
 - `.deviceType` The type of device, e.g., `desktop`.
+- `.isMobile` The type of device is mobile or not.
 - `.model` The model type of the device, e.g., `iPad`.
 - `.manufacturer` The device manufacturer.
 - `.engine` The browser engine, e.g., `Webkit`.
@@ -435,6 +444,16 @@ The associated timestamp of the following items is the one created at initiation
 - `.systemFamily` The family name of the device OS, e.g., `OS X`.
 - `.description` A tidy description of the current environment, e.g., `Chrome 89.0.4389.90 on OS X 11.2.1 64-bit`.
 - `.fullDescription` The full description of the current environment.
+- `.userLanguage` The language used in the browser, e.g., `en`.
+
+#### i18n
+
+- `.language` (e.g., `en-US`, `zh-CN`)
+- `.languageNameEnglish` (e.g., `English`, `Chinese (Simplified)`)
+- `.languageNameNative` (e.g., `简体中文`)
+- `.languageDirection` (`LTR` or `RTL`)
+- `.languagePhraseSource` (e.g., `Denis Pelli & Peiling Jiang 2021.10.10`)
+- `.supportedLanguages` An array of all supported languages. Can be called before initialization.
 
 #### All Data
 
@@ -448,6 +467,7 @@ Use the following keywords to retrieve the whole dataset.
 - `.gazeData`
 - `.fullScreenData`
 - `.environmentData`
+- `.languageData`
 
 #### Others
 

package/homepage/example.css

@@ -160,6 +160,10 @@ button:active {
   border: 1px solid #ac0d0d;
 }
 
+#lang-picker {
+  padding: 0.25rem;
+}
+
 /* -------------------------------------------------------------------------- */
 
 @media (min-width: 721px) {

package/homepage/example.js

@@ -299,6 +299,7 @@ function trackGaze(e) {
     {
       showVideo: false,
     },
+    null,
     data => {
       gazeP.innerHTML = gotData(
         `The gaze position is [${data.value.x} px, ${

package/homepage/index.html

@@ -51,6 +51,8 @@
         >
       </p>
 
+      <div id="rc-language"></div>
+
       <h2>Functions</h2>
 
       <div id="functions" class="flex-wrapper"></div>
@@ -128,6 +130,12 @@
         'nearPointCm',
         'gazePositionPx',
         'isFullscreen',
+        'id',
+        'language',
+        'languageNameEnglish',
+        'languageNameNative',
+        'languageDirection',
+        'languagePhraseSource',
       ]
 
       const gettersEnv = [
@@ -142,6 +150,7 @@
         'systemFamily',
         'description',
         'fullDescription',
+        'userLanguage',
         'version',
       ]
 
@@ -163,6 +172,23 @@
       setGetters(document.getElementById('getters-exp'), gettersExp)
       setGetters(document.getElementById('getters-env'), gettersEnv)
 
+      // i18n
+      const langPickerParent = document.getElementById('rc-language')
+      let langInner = '<select name="lang" id="lang-picker">'
+      for (let lang of RemoteCalibrator.supportedLanguages) {
+        langInner += `<option value="${lang.language}">${lang.languageNameNative}</option>`
+      }
+      langInner += '</select>'
+      langPickerParent.innerHTML = langInner
+
+      document.querySelector('#lang-picker').onchange = e => {
+        RemoteCalibrator.newLanguage(
+          document.querySelector('#lang-picker').value
+        )
+        RemoteCalibrator.resetPanel()
+      }
+      //
+
       initialize({ target: document.getElementById('init-button') })
     </script>
     <!-- GitHub corner -->

package/i18n/.eslintrc.js

@@ -0,0 +1,12 @@
+module.exports = {
+  env: {
+    commonjs: true,
+    es2021: true,
+    node: true,
+  },
+  extends: 'eslint:recommended',
+  parserOptions: {
+    ecmaVersion: 12,
+  },
+  rules: {},
+}

package/i18n/fetch-languages-sheets.js

@@ -0,0 +1,62 @@
+const process = require('process')
+const fs = require('fs')
+const XLSX = require('xlsx')
+const google = require('googleapis')
+
+const auth = new google.Auth.GoogleAuth({
+  keyFile: `${__dirname}/credentials.json`,
+  scopes: 'https://www.googleapis.com/auth/spreadsheets',
+})
+
+async function processLanguageSheet() {
+  const spreadsheetId = '1UFfNikfLuo8bSromE34uWDuJrMPFiJG3VpoQKdCGkII'
+  const googleSheets = new google.sheets_v4.Sheets()
+  const rows = await googleSheets.spreadsheets.values.get({
+    auth,
+    spreadsheetId,
+    range: 'Sheet1',
+  })
+
+  const rowsJSON = XLSX.utils.sheet_to_json(
+    XLSX.utils.aoa_to_sheet(rows.data.values),
+    {
+      defval: '',
+    }
+  )
+
+  const data = {}
+  for (let phrase of rowsJSON) {
+    const { language, ...translations } = phrase
+    if (language.includes('RC_') || language.includes('EE_'))
+      data[language] = translations
+  }
+
+  const exportWarning = `/*
+  Do not modify this file! Run npm \`npm run phrases\` at ROOT of this project to fetch from the Google Sheets.
+  https://docs.google.com/spreadsheets/d/1UFfNikfLuo8bSromE34uWDuJrMPFiJG3VpoQKdCGkII/edit#gid=0
+*/\n\n`
+  const exportHandle = `export const phrases = `
+
+  fs.writeFile(
+    `${process.cwd()}/src/i18n.js`,
+    exportWarning + exportHandle + JSON.stringify(data) + '\n',
+    error => {
+      if (error) {
+        console.log("Error! Couldn't write to the file.", error)
+      } else {
+        console.log(
+          'EasyEyes International Phrases fetched and written into files successfully.'
+        )
+      }
+    }
+  )
+}
+
+require('dns').resolve('www.google.com', function (err) {
+  if (err) {
+    console.log('No internet connection. Skip fetching phrases.')
+  } else {
+    console.log('Fetching up-to-date phrases...')
+    processLanguageSheet()
+  }
+})