HoshinoKoji/jsPsych
1
0
Fork 0
mirror of https://github.com/jspsych/jsPsych.git synced 2025-05-10 11:10:54 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
Josh de Leeuw 2021-04-09 12:04:05 -04:00
parent 4bcde4a504
commit 8aaceab759
4 changed files with 55 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/extensions/jspsych-ext-webgazer.md
View File

@ -21,7 +21,7 @@ Parameter | Type | Default Value | Description
webgazer | object | `undefined` | You can explicitly pass a reference to a loaded instance of the webgazer.js library. If no explicit reference is passed then the extension will look for a global `webgazer` object. If you are loading webgazer.js via a `<script>` tag you do not need to set this parameter in most circumstances.
auto_initialize | bool | false | Whether to automatically initialize webgazer when the experiment begins. If set to `true` then the experiment will attempt to access the user's webcam immediately upon page load. The default value is `false` because it is probably a good idea to explain to the user why camera permission will be needed before asking for it. The `webgazer-init-camera` plugin can be used to initialize the camera during the experiment.
round_predictions | bool | true | Whether to round the `x`,`y` coordinates predicted by WebGazer to the nearest whole number. This *greatly* reduces the size of the data, as WebGazer records data to 15 decimal places by default. Given the noise of the system, there's really no need to record data to this level of precision.
sampling_interval | numeric | 50 | Sets the interval between gaze predictions. Because the underlying code is partially asynchronous, this interval is only approximate. The sampling interval will not be faster than this, on average, but the time between samples may fluctuate. Setting the interval too fast will create performance problems and produce redundant data, as the video feed from most webcams only updates about 30 times per second.
sampling_interval | numeric | 34 | Sets the interval between gaze predictions. Because the underlying code is partially asynchronous, this interval is only approximate. The sampling interval will not be faster than this, on average, but the time between samples may fluctuate. Setting the interval too fast will create performance problems and produce redundant data, as the video feed from most webcams only updates about 30 times per second.
### Trial Parameters
@ -110,11 +110,19 @@ The extension uses the default mode specified by WebGazer (currently `ridge`).
### getCurrentPrediction()
Get the current predicted gaze location from WebGazer. Returns an object with `x`, `y`, and, if currently in a trial with the extension turned on, the time `t` in ms since the start of the trial.
Get the current predicted gaze location from WebGazer. This returns a Promise that resolves once WebGazer has finished computing the gaze prediction. The Promise has a single parameter with an object with `x`, `y`, and, `t` parameters. `t` will be the value of `performance.now()` at approximately the time that the video frame was recorded.
### startSampleInterval(interval)
Starts sampling gaze predictions every `interval` milliseconds. If `interval` is left undefined then the default value at extension initialization is used. Every sample will trigger an `onGazeUpdate` callback, as well as side effects that result in data storage within the extension.
### stopSampleInterval()
Stops the sampling started by `startSampleInterval()`.
### onGazeUpdate(callback)
Subscribe to gaze updates. The `callback` will be invoked every time a new gaze prediction is generated. The first argument of the `callback` will be an object with `x`, `y`, and, if currently in a trial with the extension turned on, the time `t` in ms since the start of the trial.
Subscribe to gaze updates. The `callback` will be invoked every time a new gaze prediction is generated. The first argument of the `callback` will be an object with `x`, `y`, and, if currently in a trial with the extension turned on, the time `t` in ms since the start of the trial. `t` will be the value of `performance.now()` at approximately the time that the video frame was recorded. If currently in an active trial then `t` will be relative to the start of the trial.
This function returns a close handler. When you no longer need to subscribe to gaze updates, call the close handler. Example:

54
docs/overview/eye-tracking.md
View File

@ -4,7 +4,24 @@ jsPsych supports eye tracking through the [WebGazer](https://webgazer.cs.brown.e
## Getting Started
First, [download WebGazer.js ](https://webgazer.cs.brown.edu/#download) and include it in your experiment file via a `<script>` tag. You'll also need to include jsPsych's [webgazer extension](/extensions/jspsych-ext-webgazer.md).
### Load webgazer.js
The [official version of WebGazer](https://webgazer.cs.brown.edu/#download) is currently not supported by jsPsych. Our [fork of the library]() contains some minor improvements aimed at the kind of experiments that jsPsych is typically used for, e.g., situations in which the timing of display screens needs to be accurate.
A copy of our fork is included in the jsPsych release, in the `/examples/js/webgazer` folder. You will need to copy this folder into your project directory. This guide will assume that the folder is located at `/js/webgazer`, but you can change the path as you'd like.
Include the `webgazer.js` file in your experiment via a `<script>` tag.
```html
<head>
<script src="jspsych/jspsych.js"></script>
<script src="js/webgazer/webgazer.js"></script>
</head>
```
### Load the jsPsych webgazer extension
The [webgazer extension](/extensions/jspsych-ext-webgazer.md) adds functionality to jsPsych for interacting with webgazer. Load it like you would a plugin file.
```html
<head>
@ -14,9 +31,6 @@ First, [download WebGazer.js ](https://webgazer.cs.brown.edu/#download) and incl
</head>
```
!!! tip
An example experiment using WebGazer is available in the **/examples** folder of the jsPsych release. See `webgazer.html`.
To use the WebGazer extension in an experiment, include it in the list of extensions passed to `jsPsych.init()`
```js
@ -28,6 +42,11 @@ jsPsych.init({
})
```
!!! tip
Example experiments using WebGazer are available in the **/examples** folder of the jsPsych release. See `webgazer.html`, `webgazer_image.html`, and `webgazer_audio.html`.
### Initialize the camera
To help the participant position their face correctly for eye tracking you can use the [jspsych-webgazer-init-camera plugin](/plugins/jspsych-webgazer-init-camera.ms). This will show the participant what the camera sees, including facial feature landmarks, and prevent the participant from continuing until their face is in good position for eye tracking. This plugin will also trigger the experiment to request permission to access the user's webcam if it hasn't already been granted.
```js
@ -36,6 +55,8 @@ var init_camera_trial = {
}
```
### Calibration
To calibrate WebGazer, you can use the [jspsych-webgazer-calibrate plugin](/plugins/jspsych-webgazer-calibrate.md). This plugin allows you to specify a set of points on the screen for calibration and to choose the method for calibrating -- either clicking on each point or simply fixating on each point. The location of calibration points is specified in percentages, e.g., `[25,50]` will result in a point that is 25% of the width of the screen from the left edge and 50% of the height of the screen from the top edge. Options for controlling other details of the calibration are explained in the [documentation for the plugin](/plugins/jspsych-webgazer-calibrate.md).
Note that instructions are not included in the calibration plugin, so you'll likely want to use a different plugin (e.g., `html-button-response`) to display instructions prior to running the calibration.
@ -48,6 +69,8 @@ var calibration_trial = {
}
```
### Validation
To measure the accuracy and precision of the calibration, you can use the [jspsych-webgazer-vaidate plugin](/plugins/jspsych-webgazer-validate.md). Like the calibration plugin, you can specify a list of points to perform validation on. Here you can specify the points as either percentages or in terms of the distance from the center of the screen in pixels. Which mode you use will probably depend on how you are defining your stimuli throughout the experiment. You can also specify the radius of tolerance around each point, and the plugin will calculate the percentage of measured gaze samples within that radius. This is a potentially useful heuristic for deciding whether or not to calibrate again. Options for controlling other details of the validation are explained in the [documentation for the plugin](/plugins/jspsych-webgazer-validate.md).
```js
@ -72,6 +95,8 @@ The validation procedure stores the raw gaze data for each validation point, the
We recommend performing calibration and validation periodically throughout your experiment.
### Adding eye tracking to a trial
To enable eye tracking for a trial in your experiment, you can simply add the WebGazer extension to the trial.
```js
@ -94,10 +119,10 @@ This will turn on WebGazer at the start of the trial.
The `params` property in the `extensions` declaration allows you to pass in a list of [CSS selector strings](https://www.w3schools.com/cssref/css_selectors.asp). The [bounding rectangle](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect) of the DOM element that matches each selector will be recorded in the data for that trial. This allows for easy alignment of the gaze data and objects on the screen.
```js
webgazer_targets : [
{selector: ..., top: ..., left: ..., right: ..., bottom:...},
{selector: ..., top: ..., left: ..., right: ..., bottom:...},
]
webgazer_targets : {
'selector': {x: ..., y: ..., height: ..., width: ..., top: ..., left: ..., right: ..., bottom:...}
'selector': {x: ..., y: ..., height: ..., width: ..., top: ..., left: ..., right: ..., bottom:...}
}
```
Gaze data will be added to the trial's data under the property `webgazer_data`. The gaze data is an array of objects. Each object has an `x`, a `y`, and a `t` property. The `x` and `y` properties specify the gaze location in pixels and `t` specifies the time in milliseconds since the start of the trial. Note that establishing the precision and accuracy of these measurements across the variety of web browsers and systems that your experiment participants might be using is quite difficult. For example, different browsers may cause small systematic shifts in the accuracy of `t` values.
@ -136,7 +161,7 @@ The code below shows a basic example of what it looks like when you put all of t
<script src="jspsych/plugins/jspsych-webgazer-init-camera.js"></script>
<script src="jspsych/plugins/jspsych-webgazer-calibrate.js"></script>
<script src="jspsych/plugins/jspsych-webgazer-validation.js"></script>
<script src="js/webgazer.js"></script>
<script src="js/webgazer/webgazer.js"></script>
<script src="jspsych/extensions/jspsych-ext-webgazer.js"></script>
<link rel="stylesheet" href="jspsych/css/jspsych.css">
</head>
@ -225,10 +250,13 @@ Below is example data from the image-keyboard-response trial taken from the expe
{ "x": 606, "y": 221, "t": 987}
],
"webgazer_targets": [
{
"selector": "#jspsych-image-keyboard-response-stimulus",
"top": 135.33334350585938,
"bottom": 435.3333435058594,
"#jspsych-image-keyboard-response-stimulus": {
"x": 490,
"y": 135,
"height": 300,
"width": 300,
"top": 135,
"bottom": 435,
"left": 490,
"right": 790
}

3
docs/plugins/jspsych-webgazer-init-camera.md
View File

@ -17,8 +17,7 @@ In addition to the [default data collected by all plugins](/overview/plugins#dat
Name | Type | Value
-----|------|------
No additional data collected.
load_time | numeric | The time it took for webgazer to initialize. This can be a long time in some situations, so this value is recorded for troubleshooting when participants are reporting difficulty.
## Example

3
docs/plugins/jspsych-webgazer-validate.md
View File

@ -24,10 +24,11 @@ In addition to the [default data collected by all plugins](/overview/plugins#dat
Name | Type | Value
-----|------|------
raw_gaze | array | Raw gaze data for the trial. The array will contain a nested array for each validation point. Within each nested array will be a list of `{dx,dy}` values specifying the distance from the target for that gaze point.
raw_gaze | array | Raw gaze data for the trial. The array will contain a nested array for each validation point. Within each nested array will be a list of `{x,y,dx,dy}` values specifying the absolute x and y pixels, as well as the distance from the target for that gaze point.
percent_in_roi | array | The percentage of samples within the `roi_radius` for each validation point.
average_offset | array | The average `x` and `y` distance from each validation point, plus the median distance `r` of the points from this average offset.
samples_per_sec | numeric | The average number of samples per second. Calculated by finding samples per second for each point and then averaging these estimates together.
validation_points | array | The list of validation points, in the order that they appeared.
## Example