Merge pull request #441 from apitiot/master

polished up QuestHandler, various cosmetic improvements

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "psychojs",
-  "version": "2021.2.0",
+  "version": "2021.2.x",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "psychojs",
-      "version": "2021.2.0",
+      "version": "2021.2.x",
       "license": "MIT",
       "dependencies": {
         "howler": "^2.2.1",

src/core/PsychoJS.js

@@ -142,9 +142,9 @@ export class PsychoJS
 			psychoJS: this,
 		});
 
-		// to be loading `configURL` files in `_configure` calls from
+		// add the pavlovia server to the list of hosts:
-		const hostsEvidently = new Set([...hosts, "https://pavlovia.org/run/", "https://run.pavlovia.org/"]);
+		const hostsWithPavlovia = new Set([...hosts, "https://pavlovia.org/run/", "https://run.pavlovia.org/"]);
-		this._hosts = Array.from(hostsEvidently);
+		this._hosts = Array.from(hostsWithPavlovia);
 
 		// GUI:
 		this._gui = new GUI(this);
@@ -178,7 +178,7 @@ export class PsychoJS
 		this.logger.info("[PsychoJS] Initialised.");
 		this.logger.info("[PsychoJS] @version 2021.2.0");
 
-		// Hide #root::after
+		// hide the initialisation message:
 		jQuery("#root").addClass("is-ready");
 	}
 
@@ -572,17 +572,17 @@ export class PsychoJS
 		{
 			this.status = PsychoJS.Status.CONFIGURING;
 
-			// if the experiment is running from the pavlovia.org server, we read the configuration file:
+			// if the experiment is running from an approved hosts, e.e pavlovia.org,
+			// we read the configuration file:
 			const experimentUrl = window.location.href;
-			// go through each url in allow list
+			const isHost = this._hosts.some(url => experimentUrl.indexOf(url) === 0);
-			const isHost = this._hosts.some((url) => experimentUrl.indexOf(url) === 0);
 			if (isHost)
 			{
 				const serverResponse = await this._serverManager.getConfiguration(configURL);
 				this._config = serverResponse.config;
 
-				// legacy experiments had a psychoJsManager block instead of a pavlovia block,
+				// update the configuration for legacy experiments, which had a psychoJsManager
-				// and the URL pointed to https://pavlovia.org/server
+				// block instead of a pavlovia block, with URL pointing to https://pavlovia.org/server
 				if ("psychoJsManager" in this._config)
 				{
 					delete this._config.psychoJsManager;

src/core/ServerManager.js

@@ -429,15 +429,14 @@ export class ServerManager extends PsychObject
 				}
 
 				// whether all resources have been requested:
-				const allResources = (resources.length === 1 && resources[0] === ServerManager.ALL_RESOURCES);
+				const allResources = (resources.length === 1 &&
+					resources[0] === ServerManager.ALL_RESOURCES);
 
 				// if the experiment is hosted on the pavlovia.org server and
 				// resources is [ServerManager.ALL_RESOURCES], then we register all the resources
 				// in the "resources" sub-directory
-				if (
+				if (this._psychoJS.config.environment === ExperimentHandler.Environment.SERVER &&
-					this._psychoJS.config.environment === ExperimentHandler.Environment.SERVER
+					allResources)
-					&& allResources
-				)
 				{
 					// list the resources from the resources directory of the experiment on the server:
 					const serverResponse = await this._listResources();
@@ -465,10 +464,8 @@ export class ServerManager extends PsychObject
 				{
 					// we cannot ask for all resources to be registered locally, since we cannot list
 					// them:
-					if (
+					if (this._psychoJS.config.environment === ExperimentHandler.Environment.LOCAL &&
-						this._psychoJS.config.environment === ExperimentHandler.Environment.LOCAL
+						allResources)
-						&& allResources
-					)
 					{
 						throw "resources must be manually specified when the experiment is running locally: ALL_RESOURCES cannot be used";
 					}
@@ -759,14 +756,14 @@ export class ServerManager extends PsychObject
 	/**
 	 * Asynchronously upload audio data to the pavlovia server.
 	 *
-	 * @name module:core.ServerManager#uploadAudio
+	 * @name module:core.ServerManager#uploadAudioVideo
 	 * @function
 	 * @public
 	 * @param {Blob} audioBlob - the audio blob to be uploaded
 	 * @param {string} tag - additional tag
 	 * @returns {Promise<ServerManager.UploadDataPromise>} the response
 	 */
-	async uploadAudio(audioBlob, tag)
+	async uploadAudioVideo(audioBlob, tag)
 	{
 		const response = {
 			origin: "ServerManager.uploadAudio",
@@ -805,11 +802,11 @@ export class ServerManager extends PsychObject
 			// query the pavlovia server:
 			const response = await fetch(url, {
 				method: "POST",
-				mode: "cors", // no-cors, *cors, same-origin
+				mode: "cors",
-				cache: "no-cache", // *default, no-cache, reload, force-cache, only-if-cached
+				cache: "no-cache",
-				credentials: "same-origin", // include, *same-origin, omit
+				credentials: "same-origin",
-				redirect: "follow", // manual, *follow, error
+				redirect: "follow",
-				referrerPolicy: "no-referrer", // no-referrer, *no-referrer-when-downgrade, origin, origin-when-cross-origin, same-origin, strict-origin, strict-origin-when-cross-origin, unsafe-url
+				referrerPolicy: "no-referrer",
 				body: formData,
 			});
 			const jsonResponse = await response.json();

src/data/ExperimentHandler.js

@@ -30,7 +30,7 @@ export class ExperimentHandler extends PsychObject
 	/**
 	 * Getter for experimentEnded.
 	 *
-	 * @name module:core.Window#experimentEnded
+	 * @name module:data.ExperimentHandler#experimentEnded
 	 * @function
 	 * @public
 	 */
@@ -42,7 +42,7 @@ export class ExperimentHandler extends PsychObject
 	/**
 	 * Setter for experimentEnded.
 	 *
-	 * @name module:core.Window#experimentEnded
+	 * @name module:data.ExperimentHandler#experimentEnded
 	 * @function
 	 * @public
 	 */

src/data/QuestHandler.js

@@ -10,18 +10,30 @@
 
 
 
-import {TrialHandler} from "./TrialHandler";
+import {TrialHandler} from "./TrialHandler.js";
 
 /**
  * <p>A Trial Handler that implements the Quest algorithm for quick measurement of
-    psychophysical thresholds.</p>
+    psychophysical thresholds. QuestHandler relies on the [jsQuest]{@link https://github.com/kurokida/jsQUEST} library, a port of Prof Dennis Pelli's QUEST algorithm by [Daiichiro Kuroki]{@link https://github.com/kurokida}.</p>
  *
- * @class
+ * @class module.data.QuestHandler
- * @extends PsychObject
+ * @extends TrialHandler
  * @param {Object} options
  * @param {module:core.PsychoJS} options.psychoJS - the PsychoJS instance
+ * @param {string} options.varName - the name of the variable / intensity / contrast / threshold manipulated by QUEST
+ * @param {number} options.startVal - initial guess for the threshold
+ * @param {number} options.startValSd - standard deviation of the initial guess
+ * @param {number} options.minVal - minimum value for the threshold
+ * @param {number} options.maxVal - maximum value for the threshold
+ * @param {number} [options.pThreshold=0.82] - threshold criterion expressed as probability of getting a correct response
  * @param {number} options.nTrials - maximum number of trials
+ * @param {number} options.stopInterval - minimum [5%, 95%] confidence interval required for the loop to stop
  * @param {module:data.QuestHandler.Method} options.method - the QUEST method
+ * @param {number} [options.beta=3.5] - steepness of the QUEST psychometric function
+ * @param {number} [options.delta=0.01] - fraction of trials with blind responses
+ * @param {number} [options.gamma=0.5] - fraction of trails that would generate a correct response when the threshold is infinitely small
+ * @param {number} [options.grain=0.01] - quantization of the internal table
+ * @param {string} options.name - name of the handler
  * @param {boolean} [options.autoLog= false] - whether or not to log
  */
 export class QuestHandler extends TrialHandler
@@ -80,9 +92,11 @@ export class QuestHandler extends TrialHandler
 	/**
 	 * Add a response and update the PDF.
 	 *
+	 * @name module:data.QuestHandler#addResponse
+	 * @function
 	 * @public
-	 * @param{number} response	- the response to the trial, must be either 0 (incorrect,
+	 * @param{number} response	- the response to the trial, must be either 0 (incorrect or
-	 * non-detected) or 1 (correct, detected).
+	 * non-detected) or 1 (correct or detected).
 	 */
 	addResponse(response)
 	{
@@ -110,7 +124,10 @@ export class QuestHandler extends TrialHandler
 	/**
 	 * Simulate a response.
 	 *
-	 * @param{number} trueValue
+	 * @name module:data.QuestHandler#simulate
+	 * @function
+	 * @public
+	 * @param{number} trueValue - the true, known value of the threshold / contrast / intensity
 	 */
 	simulate(trueValue)
 	{
@@ -128,6 +145,9 @@ export class QuestHandler extends TrialHandler
 	/**
 	 * Get the mean of the Quest posterior PDF.
 	 *
+	 * @name module:data.QuestHandler#mean
+	 * @function
+	 * @public
 	 * @returns {number} the mean
 	 */
 	mean()
@@ -139,6 +159,9 @@ export class QuestHandler extends TrialHandler
 	/**
 	 * Get the standard deviation of the Quest posterior PDF.
 	 *
+	 * @name module:data.QuestHandler#sd
+	 * @function
+	 * @public
 	 * @returns {number} the standard deviation
 	 */
 	sd()
@@ -150,6 +173,9 @@ export class QuestHandler extends TrialHandler
 	/**
 	 * Get the mode of the Quest posterior PDF.
 	 *
+	 * @name module:data.QuestHandler#mode
+	 * @function
+	 * @public
 	 * @returns {number} the mode
 	 */
 	mode()
@@ -162,6 +188,9 @@ export class QuestHandler extends TrialHandler
 	/**
 	 * Get the standard deviation of the Quest posterior PDF.
 	 *
+	 * @name module:data.QuestHandler#quantile
+	 * @function
+	 * @public
 	 * @param{number} quantileOrder the quantile order
 	 * @returns {number} the quantile
 	 */
@@ -174,6 +203,8 @@ export class QuestHandler extends TrialHandler
 	/**
 	 * Get an estimate of the 5%-95% confidence interval (CI).
 	 *
+	 * @name module:data.QuestHandler#confInterval
+	 * @function
 	 * @public
 	 * @param{boolean} [getDifference=false]	if true, return the width of the CI instead of the CI
 	 */
@@ -198,6 +229,8 @@ export class QuestHandler extends TrialHandler
 	/**
 	 * Setup the JS Quest object.
 	 *
+	 * @name module:data.QuestHandler#_setupJsQuest
+	 * @function
 	 * @protected
 	 */
 	_setupJsQuest()
@@ -219,6 +252,8 @@ export class QuestHandler extends TrialHandler
 	 * Estimate the next value of the QUEST variable, based on the current value
 	 * and on the selected QUEST method.
 	 *
+	 * @name module:data.QuestHandler#_estimateQuestValue
+	 * @function
 	 * @protected
 	 */
 	_estimateQuestValue()
@@ -248,7 +283,6 @@ export class QuestHandler extends TrialHandler
 
 		this._psychoJS.logger.debug(`estimated value for QUEST variable ${this._varName}: ${this._questValue}`);
 
-
 		// check whether we should finish the trial:
 		if (this.thisN > 0 &&
 			(this.nRemaining === 0 || this.confInterval(true) < this._stopInterval))
@@ -269,7 +303,6 @@ export class QuestHandler extends TrialHandler
 			return;
 		}
 
-
 		// update the next undefined trial in the trial list, and the associated snapshot:
 		for (let t = 0; t < this._trialList.length; ++t)
 		{

src/sound/AudioClip.js

@@ -157,7 +157,7 @@ export class AudioClip extends PsychObject
 		}
 
 		// upload the data:
-		return this._psychoJS.serverManager.uploadAudio(this._data, filename);
+		return this._psychoJS.serverManager.uploadAudioVideo(this._data, filename);
 	}
 
 	/**

src/sound/Microphone.js

@@ -322,7 +322,7 @@ export class Microphone extends PsychObject
 
 		// upload the blob:
 		const audioBlob = new Blob(this._audioBuffer);
-		return this._psychoJS.serverManager.uploadAudio(audioBlob, tag);
+		return this._psychoJS.serverManager.uploadAudioVideo(audioBlob, tag);
 	}
 
 	/**

src/util/Util.js

@@ -1406,5 +1406,10 @@ export function extensionFromMimeType(mimeType)
 		return ".wav";
 	}
 
-	return ".dat";
+	if (mimeType.indexOf("video/webm") === 0)
+	{
+		return ".webm";
+	}
+
+	return '.dat';
 }

src/visual/Camera.js

@@ -7,11 +7,11 @@
  * @license Distributed under the terms of the MIT License
  */
 
-import {Clock} from "../util/Clock";
+import {Clock} from "../util/Clock.js";
-import {PsychObject} from "../util/PsychObject";
+import {PsychObject} from "../util/PsychObject.js";
-import {PsychoJS} from "../core/PsychoJS";
+import {PsychoJS} from "../core/PsychoJS.js";
-import * as util from '../util/Util';
+import * as util from "../util/Util.js";
-import {ExperimentHandler} from "../data/ExperimentHandler";
+import {ExperimentHandler} from "../data/ExperimentHandler.js";
 // import {VideoClip} from "./VideoClip";
 
 
@@ -25,20 +25,25 @@ import {ExperimentHandler} from "../data/ExperimentHandler";
  * @param {string} [options.format='video/webm;codecs=vp9'] the video format
  * @param {Clock} [options.clock= undefined] - an optional clock
  * @param {boolean} [options.autoLog= false] - whether or not to log
+ *
+ * @todo add video constraints as parameter
  */
 export class Camera extends PsychObject
 {
-
+	/**
+	 * @constructor
+	 * @public
+	 */
 	constructor({win, name, format, clock, autoLog} = {})
 	{
 		super(win._psychoJS);
 
-		this._addAttribute('win', win, undefined);
+		this._addAttribute("win", win, undefined);
-		this._addAttribute('name', name, 'camera');
+		this._addAttribute("name", name, "camera");
-		this._addAttribute('format', format, 'video/webm;codecs=vp9', this._onChange);
+		this._addAttribute("format", format, "video/webm;codecs=vp9", this._onChange);
-		this._addAttribute('clock', clock, new Clock());
+		this._addAttribute("clock", clock, new Clock());
-		this._addAttribute('autoLog', autoLog, false);
+		this._addAttribute("autoLog", autoLog, false);
-		this._addAttribute('status', PsychoJS.Status.NOT_STARTED);
+		this._addAttribute("status", PsychoJS.Status.NOT_STARTED);
 
 		// prepare the recording:
 		this._prepareRecording();
@@ -54,6 +59,7 @@ export class Camera extends PsychObject
 	 * Get the underlying video stream.
 	 *
 	 * @name module:visual.Camera#getStream
+	 * @function
 	 * @public
 	 * @returns {MediaStream} the video stream
 	 */
@@ -67,6 +73,7 @@ export class Camera extends PsychObject
 	 * Get a video element pointing to the Camera stream.
 	 *
 	 * @name module:visual.Camera#getVideo
+	 * @function
 	 * @public
 	 * @returns {HTMLVideoElement} a video element
 	 */
@@ -76,7 +83,7 @@ export class Camera extends PsychObject
 		// several stimuli and one of them might pause the feed
 
 		// create a video with the appropriate size:
-		const video = document.createElement('video');
+		const video = document.createElement("video");
 		this._videos.push(video);
 
 		video.width = this._streamSettings.width;
@@ -101,6 +108,7 @@ export class Camera extends PsychObject
 	 * Submit a request to start the recording.
 	 *
 	 * @name module:visual.Camera#start
+	 * @function
 	 * @public
 	 * @return {Promise} promise fulfilled when the recording actually started
 	 */
@@ -116,13 +124,13 @@ export class Camera extends PsychObject
 
 		if (this._status !== PsychoJS.Status.STARTED)
 		{
-			this._psychoJS.logger.debug('request to start video recording');
+			this._psychoJS.logger.debug("request to start video recording");
 
 			try
 			{
 				if (!this._recorder)
 				{
-					throw 'the recorder has not been created yet, possibly because the participant has not given the authorisation to record video';
+					throw "the recorder has not been created yet, possibly because the participant has not given the authorisation to record video";
 				}
 
 				this._recorder.start();
@@ -138,12 +146,12 @@ export class Camera extends PsychObject
 			}
 			catch (error)
 			{
-				this._psychoJS.logger.error('unable to start the video recording: ' + JSON.stringify(error));
+				this._psychoJS.logger.error("unable to start the video recording: " + JSON.stringify(error));
 				this._status = PsychoJS.Status.ERROR;
 
 				throw {
-					origin: 'Camera.start',
+					origin: "Camera.start",
-					context: 'when starting the video recording for camera: ' + this._name,
+					context: "when starting the video recording for camera: " + this._name,
 					error
 				};
 			}
@@ -157,6 +165,7 @@ export class Camera extends PsychObject
 	 * Submit a request to stop the recording.
 	 *
 	 * @name module:visual.Camera#stop
+	 * @function
 	 * @public
 	 * @param {Object} options
 	 * @param {string} [options.filename] the name of the file to which the video recording
@@ -168,7 +177,7 @@ export class Camera extends PsychObject
 	{
 		if (this._status === PsychoJS.Status.STARTED || this._status === PsychoJS.Status.PAUSED)
 		{
-			this._psychoJS.logger.debug('request to stop video recording');
+			this._psychoJS.logger.debug("request to stop video recording");
 
 			// stop the videos:
 			for (const video of this._videos)
@@ -201,6 +210,7 @@ export class Camera extends PsychObject
 	 * Submit a request to pause the recording.
 	 *
 	 * @name module:visual.Camera#pause
+	 * @function
 	 * @public
 	 * @return {Promise} promise fulfilled when the recording actually paused
 	 */
@@ -208,13 +218,13 @@ export class Camera extends PsychObject
 	{
 		if (this._status === PsychoJS.Status.STARTED)
 		{
-			this._psychoJS.logger.debug('request to pause video recording');
+			this._psychoJS.logger.debug("request to pause video recording");
 
 			try
 			{
 				if (!this._recorder)
 				{
-					throw 'the recorder has not been created yet, possibly because the participant has not given the authorisation to record video';
+					throw "the recorder has not been created yet, possibly because the participant has not given the authorisation to record video";
 				}
 
 				// note: calling the pause method of the MediaRecorder raises a pause event
@@ -230,12 +240,12 @@ export class Camera extends PsychObject
 			}
 			catch (error)
 			{
-				self._psychoJS.logger.error('unable to pause the video recording: ' + JSON.stringify(error));
+				self._psychoJS.logger.error("unable to pause the video recording: " + JSON.stringify(error));
 				this._status = PsychoJS.Status.ERROR;
 
 				throw {
-					origin: 'Camera.pause',
+					origin: "Camera.pause",
-					context: 'when pausing the video recording for camera: ' + this._name,
+					context: "when pausing the video recording for camera: " + this._name,
 					error
 				};
 			}
@@ -250,6 +260,7 @@ export class Camera extends PsychObject
 	 * <p>resume has no effect if the recording was not previously paused.</p>
 	 *
 	 * @name module:visual.Camera#resume
+	 * @function
 	 * @param {Object} options
 	 * @param {boolean} [options.clear= false] whether or not to empty the video buffer before
 	 * 	resuming the recording
@@ -259,13 +270,13 @@ export class Camera extends PsychObject
 	{
 		if (this._status === PsychoJS.Status.PAUSED)
 		{
-			this._psychoJS.logger.debug('request to resume video recording');
+			this._psychoJS.logger.debug("request to resume video recording");
 
 			try
 			{
 				if (!this._recorder)
 				{
-					throw 'the recorder has not been created yet, possibly because the participant has not given the authorisation to record video';
+					throw "the recorder has not been created yet, possibly because the participant has not given the authorisation to record video";
 				}
 
 				// empty the audio buffer is needed:
@@ -287,12 +298,12 @@ export class Camera extends PsychObject
 			}
 			catch (error)
 			{
-				self._psychoJS.logger.error('unable to resume the video recording: ' + JSON.stringify(error));
+				self._psychoJS.logger.error("unable to resume the video recording: " + JSON.stringify(error));
 				this._status = PsychoJS.Status.ERROR;
 
 				throw {
-					origin: 'Camera.resume',
+					origin: "Camera.resume",
-					context: 'when resuming the video recording for camera: ' + this._name,
+					context: "when resuming the video recording for camera: " + this._name,
 					error
 				};
 			}
@@ -305,6 +316,7 @@ export class Camera extends PsychObject
 	 * Submit a request to flush the recording.
 	 *
 	 * @name module:visual.Camera#flush
+	 * @function
 	 * @public
 	 * @return {Promise} promise fulfilled when the data has actually been made available
 	 */
@@ -312,7 +324,7 @@ export class Camera extends PsychObject
 	{
 		if (this._status === PsychoJS.Status.STARTED || this._status === PsychoJS.Status.PAUSED)
 		{
-			this._psychoJS.logger.debug('request to flush video recording');
+			this._psychoJS.logger.debug("request to flush video recording");
 
 			// note: calling the requestData method of the MediaRecorder will raise a
 			// dataavailable event
@@ -336,13 +348,13 @@ export class Camera extends PsychObject
 	 * @name module:visual.Camera#download
 	 * @function
 	 * @public
-	 * @param {string} filename the filename
+	 * @param {string} filename - the filename of the video file
 	 */
-	download(filename = 'video.webm')
+	download(filename = "video.webm")
 	{
 		const videoBlob = new Blob(this._videoBuffer);
 
-		const anchor = document.createElement('a');
+		const anchor = document.createElement("a");
 		anchor.href = window.URL.createObjectURL(videoBlob);
 		anchor.download = filename;
 		document.body.appendChild(anchor);
@@ -362,7 +374,7 @@ export class Camera extends PsychObject
 	async upload({tag} = {})
 	{
 		// default tag: the name of this Camera object
-		if (typeof tag === 'undefined')
+		if (typeof tag === "undefined")
 		{
 			tag = this._name;
 		}
@@ -374,16 +386,15 @@ export class Camera extends PsychObject
 		// if the video recording cannot be uploaded, e.g. the experiment is running locally, or
 		// if it is piloting mode, then we offer the video recording as a file for download:
 		if (this._psychoJS.getEnvironment() !== ExperimentHandler.Environment.SERVER ||
-			this._psychoJS.config.experiment.status !== 'RUNNING' ||
+			this._psychoJS.config.experiment.status !== "RUNNING" ||
-			this._psychoJS._serverMsg.has('__pilotToken'))
+			this._psychoJS._serverMsg.has("__pilotToken"))
 		{
 			return this.download(tag);
 		}
 
 		// upload the blob:
-		// TODO uploadAudio -> uploadAudioVideo
 		const videoBlob = new Blob(this._videoBuffer);
-		return this._psychoJS.serverManager.uploadAudio(videoBlob, tag);
+		return this._psychoJS.serverManager.uploadAudioVideo(videoBlob, tag);
 	}
 
 
@@ -399,22 +410,12 @@ export class Camera extends PsychObject
 	async getRecording({tag, flush = false} = {})
 	{
 		// default tag: the name of this Microphone object
-		if (typeof tag === 'undefined')
+		if (typeof tag === "undefined")
 		{
 			tag = this._name;
 		}
 
 		// TODO
-/*
-		const videoClip = new VideoClip({
-			psychoJS: this._psychoJS,
-			name: tag,
-			format: this._format,
-			data: new Blob(this._videoBuffer)
-		});
-
-		return videoClip;
-*/
 	}
 
 
@@ -455,15 +456,9 @@ export class Camera extends PsychObject
 		this._videos = [];
 
 		// create a new stream with ideal dimensions:
+		// TODO use size constraints
 		this._stream = await navigator.mediaDevices.getUserMedia({
-			video: {
+			video: true
-				width: {
-					ideal: 1920
-				},
-				height: {
-					ideal: 1080
-				}
-			}
 		});
 
 		// check the actual width and height:
@@ -473,7 +468,7 @@ export class Camera extends PsychObject
 
 		// check that the specified format is supported, use default if it is not:
 		let options;
-		if (typeof this._format === 'string' && MediaRecorder.isTypeSupported(this._format))
+		if (typeof this._format === "string" && MediaRecorder.isTypeSupported(this._format))
 		{
 			options = { type: this._format };
 		}
@@ -498,7 +493,7 @@ export class Camera extends PsychObject
 			self._videoBuffer.length = 0;
 			self._clock.reset();
 			self._status = PsychoJS.Status.STARTED;
-			self._psychoJS.logger.debug('video recording started');
+			self._psychoJS.logger.debug("video recording started");
 
 			// resolve the Microphone.start promise:
 			if (self._startCallback)
@@ -511,7 +506,7 @@ export class Camera extends PsychObject
 		this._recorder.onpause = () =>
 		{
 			self._status = PsychoJS.Status.PAUSED;
-			self._psychoJS.logger.debug('video recording paused');
+			self._psychoJS.logger.debug("video recording paused");
 
 			// resolve the Microphone.pause promise:
 			if (self._pauseCallback)
@@ -524,7 +519,7 @@ export class Camera extends PsychObject
 		this._recorder.onresume = () =>
 		{
 			self._status = PsychoJS.Status.STARTED;
-			self._psychoJS.logger.debug('video recording resumed');
+			self._psychoJS.logger.debug("video recording resumed");
 
 			// resolve the Microphone.resume promise:
 			if (self._resumeCallback)
@@ -540,7 +535,7 @@ export class Camera extends PsychObject
 
 			// add data to the buffer:
 			self._videoBuffer.push(data);
-			self._psychoJS.logger.debug('video data added to the buffer');
+			self._psychoJS.logger.debug("video data added to the buffer");
 
 			// resolve the data available promise, if needed:
 			if (self._dataAvailableCallback)
@@ -552,7 +547,7 @@ export class Camera extends PsychObject
 		// called upon Camera.stop(), after data has been made available:
 		this._recorder.onstop = () =>
 		{
-			self._psychoJS.logger.debug('video recording stopped');
+			self._psychoJS.logger.debug("video recording stopped");
 			self._status = PsychoJS.Status.NOT_STARTED;
 
 			// resolve the Microphone.stop promise:
@@ -564,7 +559,7 @@ export class Camera extends PsychObject
 			// treat stop options if there are any:
 
 			// download to a file, immediately offered to the participant:
-			if (typeof self._stopOptions.filename === 'string')
+			if (typeof self._stopOptions.filename === "string")
 			{
 				self.download(self._stopOptions.filename);
 			}
@@ -574,7 +569,7 @@ export class Camera extends PsychObject
 		this._recorder.onerror = (event) =>
 		{
 			// TODO
-			self._psychoJS.logger.error('video recording error: ' + JSON.stringify(event));
+			self._psychoJS.logger.error("video recording error: " + JSON.stringify(event));
 			self._status = PsychoJS.Status.ERROR;
 		};
 

src/visual/FaceDetector.js

@@ -7,17 +7,19 @@
  * @license Distributed under the terms of the MIT License
  */
 
-import {PsychoJS} from "../core/PsychoJS";
+import {PsychoJS} from "../core/PsychoJS.js";
-import * as util from '../util/Util';
+import * as util from "../util/Util.js";
-import {Color} from '../util/Color';
+import { to_pixiPoint } from "../util/Pixi.js";
-import {Camera} from "./Camera";
+import {Color} from "../util/Color.js";
-import {VisualStim} from "./VisualStim";
+import {Camera} from "./Camera.js";
+import {VisualStim} from "./VisualStim.js";
 import * as PIXI from "pixi.js-legacy";
 
 
 /**
- * <p>This manager handles the detecting of faces in video streams.</p>
+ * <p>This manager handles the detecting of faces in video streams. FaceDetector relies on the
- * <p>The detection is performed using the Face-API library: https://github.com/justadudewhohacks/face-api.js</p>
+ * [Face-API library]{@link https://github.com/justadudewhohacks/face-api.js} developed by
+ * [Vincent Muehler]{@link https://github.com/justadudewhohacks}</p>
  *
  * @name module:visual.FaceDetector
  * @class
@@ -39,17 +41,20 @@ import * as PIXI from "pixi.js-legacy";
  */
 export class FaceDetector extends VisualStim
 {
-
+	/**
+	 * @constructor
+	 * @public
+	 */
 	constructor({name, win, input, modelDir, faceApiUrl, units, ori, opacity, pos, size, autoDraw, autoLog} = {})
 	{
 		super({name, win, units, ori, opacity, pos, size, autoDraw, autoLog});
 
 		// TODO deal with onChange (see MovieStim and Camera)
-		this._addAttribute('input', input, undefined);
+		this._addAttribute("input", input, undefined);
-		this._addAttribute('faceApiUrl', faceApiUrl, 'face-api.js');
+		this._addAttribute("faceApiUrl", faceApiUrl, "face-api.js");
-		this._addAttribute('modelDir', modelDir, 'models');
+		this._addAttribute("modelDir", modelDir, "models");
-		this._addAttribute('autoLog', autoLog, false);
+		this._addAttribute("autoLog", autoLog, false);
-		this._addAttribute('status', PsychoJS.Status.NOT_STARTED);
+		this._addAttribute("status", PsychoJS.Status.NOT_STARTED);
 
 		// init face-api:
 		this._initFaceApi();
@@ -65,6 +70,7 @@ export class FaceDetector extends VisualStim
 	 * Setter for the video attribute.
 	 *
 	 * @name module:visual.FaceDetector#setCamera
+	 * @function
 	 * @public
 	 * @param {string | HTMLVideoElement | module:visual.Camera} input - the name of a
 	 * movie resource or a HTMLVideoElement or a Camera component
@@ -73,23 +79,23 @@ export class FaceDetector extends VisualStim
 	setInput(input, log = false)
 	{
 		const response = {
-			origin: 'FaceDetector.setInput',
+			origin: "FaceDetector.setInput",
-			context: 'when setting the video of FaceDetector: ' + this._name
+			context: "when setting the video of FaceDetector: " + this._name
 		};
 
 		try
 		{
 			// movie is undefined: that's fine but we raise a warning in case this is
 			// a symptom of an actual problem
-			if (typeof input === 'undefined')
+			if (typeof input === "undefined")
 			{
-				this.psychoJS.logger.warn('setting the movie of MovieStim: ' + this._name + ' with argument: undefined.');
+				this.psychoJS.logger.warn("setting the movie of MovieStim: " + this._name + " with argument: undefined.");
-				this.psychoJS.logger.debug('set the movie of MovieStim: ' + this._name + ' as: undefined');
+				this.psychoJS.logger.debug("set the movie of MovieStim: " + this._name + " as: undefined");
 			}
 			else
 			{
 				// if movie is a string, then it should be the name of a resource, which we get:
-				if (typeof input === 'string')
+				if (typeof input === "string")
 				{
 					// TODO create a movie with that resource, and use the movie as input
 				}
@@ -106,7 +112,7 @@ export class FaceDetector extends VisualStim
 				// check that video is now an HTMLVideoElement
 				if (!(input instanceof HTMLVideoElement))
 				{
-					throw input.toString() + ' is not a video';
+					throw input.toString() + " is not a video";
 				}
 
 				this.psychoJS.logger.debug(`set the video of FaceDetector: ${this._name} as: src= ${input.src}, size= ${input.videoWidth}x${input.videoHeight}, duration= ${input.duration}s`);
@@ -123,7 +129,7 @@ export class FaceDetector extends VisualStim
 				}
 			}
 
-			this._setAttribute('input', input, log);
+			this._setAttribute("input", input, log);
 			this._needUpdate = true;
 			this._needPixiUpdate = true;
 		}
@@ -138,6 +144,7 @@ export class FaceDetector extends VisualStim
 	 * Start detecting faces.
 	 *
 	 * @name module:visual.FaceDetector#start
+	 * @function
 	 * @public
 	 * @param {number} period - the detection period, in ms (e.g. 100 ms for 10Hz)
 	 * @param detectionCallback - the callback triggered when detection results are available
@@ -147,7 +154,7 @@ export class FaceDetector extends VisualStim
 	{
 		this.status = PsychoJS.Status.STARTED;
 
-		if (typeof this._detectionId !== 'undefined')
+		if (typeof this._detectionId !== "undefined")
 		{
 			clearInterval(this._detectionId);
 			this._detectionId = undefined;
@@ -176,6 +183,7 @@ export class FaceDetector extends VisualStim
 	 * Stop detecting faces.
 	 *
 	 * @name module:visual.FaceDetector#stop
+	 * @function
 	 * @public
 	 * @param {boolean} [log= false] - whether of not to log
 	 */
@@ -183,7 +191,7 @@ export class FaceDetector extends VisualStim
 	{
 		this.status = PsychoJS.Status.NOT_STARTED;
 
-		if (typeof this._detectionId !== 'undefined')
+		if (typeof this._detectionId !== "undefined")
 		{
 			clearInterval(this._detectionId);
 			this._detectionId = undefined;
@@ -195,16 +203,17 @@ export class FaceDetector extends VisualStim
 	 * Init the Face-API library.
 	 *
 	 * @name module:visual.FaceDetector#_initFaceApi
-	 * @private
+	 * @function
+	 * @protected
 	 */
 	async _initFaceApi()
 	{/*
 		// load the library:
 		await this._psychoJS.serverManager.prepareResources([
 			{
-				'name': 'face-api.js',
+				"name": "face-api.js",
-				'path': this.faceApiUrl,
+				"path": this.faceApiUrl,
-				'download': true
+				"download": true
 			}
 		]);*/
 
@@ -220,7 +229,8 @@ export class FaceDetector extends VisualStim
 	 * Update the visual representation of the detected faces, if necessary.
 	 *
 	 * @name module:visual.FaceDetector#_updateIfNeeded
-	 * @private
+	 * @function
+	 * @protected
 	 */
 	_updateIfNeeded()
 	{
@@ -234,7 +244,7 @@ export class FaceDetector extends VisualStim
 		{
 			this._needPixiUpdate = false;
 
-			if (typeof this._pixi !== 'undefined')
+			if (typeof this._pixi !== "undefined")
 			{
 				this._pixi.destroy(true);
 			}
@@ -246,7 +256,7 @@ export class FaceDetector extends VisualStim
 			this._pixi.addChild(this._body);
 
 			const size_px = util.to_px(this.size, this.units, this.win);
-			if (typeof this._detections !== 'undefined')
+			if (typeof this._detections !== "undefined")
 			{
 				for (const detection of this._detections)
 				{
@@ -256,7 +266,7 @@ export class FaceDetector extends VisualStim
 
 					for (const position of landmarks.positions)
 					{
-						this._body.beginFill(new Color('red').int, this._opacity);
+						this._body.beginFill(new Color("red").int, this._opacity);
 						this._body.drawCircle(
 							position._x / imageWidth * size_px[0] - size_px[0] / 2,
 							position._y / imageHeight * size_px[1] - size_px[1] / 2,
@@ -273,7 +283,7 @@ export class FaceDetector extends VisualStim
 		this._pixi.scale.y = -1;
 
 		this._pixi.rotation = this.ori * Math.PI / 180;
-		this._pixi.position = util.to_pixiPoint(this.pos, this.units, this.win);
+		this._pixi.position = to_pixiPoint(this.pos, this.units, this.win);
 
 		this._pixi.alpha = this._opacity;
 	}
@@ -290,15 +300,6 @@ export class FaceDetector extends VisualStim
 	_estimateBoundingBox()
 	{
 		// TODO
-
-		/*this._boundingBox = new PIXI.Rectangle(
-			this._pos[0] + this._getLengthUnits(limits_px[0]),
-			this._pos[1] + this._getLengthUnits(limits_px[1]),
-			this._getLengthUnits(limits_px[2] - limits_px[0]),
-			this._getLengthUnits(limits_px[3] - limits_px[1])
-		);*/
-
-		// TODO take the orientation into account
 	}
 
 }