diff --git a/docs/demos/jspsych-extension-mouse-tracking-demo1.html b/docs/demos/jspsych-extension-mouse-tracking-demo1.html new file mode 100644 index 00000000..f424980c --- /dev/null +++ b/docs/demos/jspsych-extension-mouse-tracking-demo1.html @@ -0,0 +1,99 @@ + + + + + + + + + + + + + + diff --git a/docs/extensions/list-of-extensions.md b/docs/extensions/list-of-extensions.md index 92cae8e9..3ad9b412 100644 --- a/docs/extensions/list-of-extensions.md +++ b/docs/extensions/list-of-extensions.md @@ -9,4 +9,5 @@ For an overview of what extensions are and how they work, see our [extensions ov Extension | Description ------ | ----------- -[jspsych‑ext‑webgazer](../extensions/webgazer.md) | Enables eye tracking using the [WebGazer](https://webgazer.cs.brown.edu/) library. \ No newline at end of file +[mouse‑tracking](../extensions/mouse-tracking.md) | Enables tracking of mouse movements and recording location of objects on screen. +[webgazer](../extensions/webgazer.md) | Enables eye tracking using the [WebGazer](https://webgazer.cs.brown.edu/) library. \ No newline at end of file diff --git a/docs/extensions/mouse-tracking.md b/docs/extensions/mouse-tracking.md new file mode 100644 index 00000000..4566374d --- /dev/null +++ b/docs/extensions/mouse-tracking.md @@ -0,0 +1,105 @@ +# mouse-tracking + +This extension supports mouse tracking. +Specifically, it can record the `x` `y` coordinates and time of [mousemove events](https://developer.mozilla.org/en-US/docs/Web/API/Element/mousemove_event). +It also allows recording of the [bounding rectangle](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect) of elements on the screen to support the calculation of mouse events relative to different elements. + +## Parameters + +### Initialization Parameters + +Initialization parameters can be set when calling `initJsPsych()` + +```js +initJsPsych({ + extensions: [ + {type: jsPsychExtensionMouseTracking, params: {...}} + ] +}) +``` + +Parameter | Type | Default Value | Description +----------|------|---------------|------------ +minimum_sample_time | number | 0 | The minimum time between mouse samples. If mouse events occur more rapidly than this limit, they will not be recorded. Use this if you want to keep the data files smaller and don't need high resolution tracking data. The default value of 0 means that all events will be recorded. + +### Trial Parameters + +Trial parameters can be set when adding the extension to a trial object. + +```js +var trial = { + type: jsPsych..., + extensions: [ + {type: jsPsychExtensionWebgazer, params: {...}} + ] +} +``` + +Parameter | Type | Default Value | Description +----------|------|---------------|------------ +targets | array | [] | A list of elements on the page that you would like to record the coordinates of for comparison with the WebGazer data. Each entry in the array should be a valid [CSS selector string](https://www.w3schools.com/cssref/css_selectors.asp) that identifies the element. The selector string should be valid for exactly one element on the page. If the selector is valid for more than one element then only the first matching element will be recorded. + +## Data Generated + +Name | Type | Value +-----|------|------ +mouse_tracking_data | array | An array of objects containing mouse movement data for the trial. Each object has an `x`, a `y`, and a `t` property. The `x` and `y` properties specify the mouse coordinates in pixels relative to the top left corner of the viewport and `t` specifies the time in milliseconds since the start of the trial. +mouse_tracking_targets | object | An object contain the pixel coordinates of elements on the screen specified by the `.targets` parameter. Each key in this object will be a `selector` property, containing the CSS selector string used to find the element. The object corresponding to each key will contain `x` and `y` properties specifying the top-left corner of the object, `width` and `height` values, plus `top`, `bottom`, `left`, and `right` parameters which specify the [bounding rectangle](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect) of the element. + +## Examples + +???+ example "Record mouse movement data and play it back" + === "Code" + ```javascript + var trial = { + type: jsPsychHtmlButtonResponse, + stimulus: '
', + choices: ['Done'], + prompt: "

Move your mouse around inside the square.

", + extensions: [ + {type: jsPsychExtensionMouseTracking, params: {targets: ['#target']}} + ], + data: { + task: 'draw' + } + }; + + var replay = { + type: jsPsychHtmlButtonResponse, + stimulus: '
', + choices: ['Done'], + prompt: "

Here's the recording of your mouse movements

", + on_load: function(){ + var mouseMovements = jsPsych.data.get().last(1).values()[0].mouse_tracking_data; + var targetRect = jsPsych.data.get().last(1).values()[0].mouse_tracking_targets['#target']; + + var startTime = performance.now(); + + function draw_frame() { + var timeElapsed = performance.now() - startTime; + var points = mouseMovements.filter((x) => x.t <= timeElapsed); + var html = ``; + for(var p of points){ + html += `
` + } + document.querySelector('#target').innerHTML = html; + if(points.length < mouseMovements.length) { + requestAnimationFrame(draw_frame); + } + } + + requestAnimationFrame(draw_frame); + + }, + data: { + task: 'replay' + } + } + ``` + + === "Demo" +
+ +
+ + Open demo in new tab \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 4a955bd4..0b9baf4e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -117,6 +117,7 @@ nav: - 'webgazer-validate': 'plugins/webgazer-validate.md' - Extensions: - 'List of Extensions': 'extensions/list-of-extensions.md' + - 'mouse-tracking': 'extensions/mouse-tracking.md' - 'webgazer': 'extensions/webgazer.md' - Developers: - 'Configuration': 'developers/configuration.md'