Contributions:GazeMonitorFilter - Revision history

Wengelhardt: /* Version History */

2023-02-17T18:02:33Z

Version History

← Older revision		Revision as of 18:02, 17 February 2023
Line 13:		Line 13:
	*07/08/2011: Initial release		*07/08/2011: Initial release
	*07/02/2021: Addition of ChangeFixation and EyeLink eye tracker implementation		*07/02/2021: Addition of ChangeFixation and EyeLink eye tracker implementation
			*02/17/2023: Use EnableGazeMonitorFilter flag to enable filter.

	===Source Code Revisions===		===Source Code Revisions===

Wengelhardt: /* Integration into BCI2000 */

2023-02-17T18:01:31Z

Integration into BCI2000

← Older revision		Revision as of 18:01, 17 February 2023
Line 36:		Line 36:
	==Integration into BCI2000==		==Integration into BCI2000==
	Compile the extension into your application modules by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_GAZEMONITORFILTER'''.		Compile the extension into your application modules by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_GAZEMONITORFILTER'''.

			In the batch file you run, append <code>--EnableGazeMonitorFilter=1</code> to the Application module you are using, such as <code>StimulusPresentation</code>. Without this, the GazeMonitorFilter parameters will not be generated.

	==Parameters==		==Parameters==

Wengelhardt: /* Parameters */

2023-02-03T20:59:27Z

Parameters

← Older revision		Revision as of 20:59, 3 February 2023
Line 53:		Line 53:
	*<code>LogGazeInformation</code> - Log information about eye validity and fixation enforcement to the ApplicationLog.		*<code>LogGazeInformation</code> - Log information about eye validity and fixation enforcement to the ApplicationLog.
	*<code>ChangeFixation</code> - Allows for multiple fixations during one run.		*<code>ChangeFixation</code> - Allows for multiple fixations during one run.
			<gallery class="center" mode="nolines" widths=1000px heights=300px>
			File:ChangeFixation.PNG\| Change Fixation parameter matrix. Any valid BCI2000 Expression can be used in the first column. If none of the expressions evaluate to true, then the Fixation center corresponds to the parameters FixationX and FixationY.
			</gallery>

	===Notes===		===Notes===
	*For <code>FixationX</code> and <code>FixationY</code>, the top left corner of the screen is (0.0, 0.0) and the bottom right corner of the screen is (1.0, 1.0)		*For <code>FixationX</code> and <code>FixationY</code>, the top left corner of the screen is (0.0, 0.0) and the bottom right corner of the screen is (1.0, 1.0)
	*<code>FixationX</code> and <code>FixationY</code> can each be a list if <code>ChangeFixation</code> is on. Otherwise, they should just be a scalar.
	*<code>ChangeFixation</code> is ordered according to the expression <code>StimulusCode</code>. For example, when <code>StimulusCode==2</code>, the second number of both <code>FixationX</code> and <code>FixationY</code> will be the new fixation zone. Therefore, if <code>ChangeFixation</code> is on, <code>StimulusCode</code> should not equal 0.
	*Specifying large images for <code>FixationImage</code> and <code>FixationViolationImage</code> is not recommended as it may have a detrimental impact on overall system timing.		*Specifying large images for <code>FixationImage</code> and <code>FixationViolationImage</code> is not recommended as it may have a detrimental impact on overall system timing.
	*If either of the timing parameters (<code>BlinkTime</code> and <code>SaccadeTime</code>) trigger a fixation violation, fixation violation will not occur again when the other timing parameter triggers if fixation has not been acquired again. (Example: One second is allotted for <code>BlinkTime</code> and 4 seconds is allotted for <code>SaccadeTime</code>. Gaze moves outside of fixation and eyes close immediately thereafter and remain closed. <code>FixationViolated</code> is set after one second of the eyes being closed, and is not thrown again when the four seconds of gaze existing outside the allowed fixation radius elapse.)		*If either of the timing parameters (<code>BlinkTime</code> and <code>SaccadeTime</code>) trigger a fixation violation, fixation violation will not occur again when the other timing parameter triggers if fixation has not been acquired again. (Example: One second is allotted for <code>BlinkTime</code> and 4 seconds is allotted for <code>SaccadeTime</code>. Gaze moves outside of fixation and eyes close immediately thereafter and remain closed. <code>FixationViolated</code> is set after one second of the eyes being closed, and is not thrown again when the four seconds of gaze existing outside the allowed fixation radius elapse.)

Wengelhardt: New state FixationDuration

2022-12-16T18:50:06Z

New state FixationDuration

← Older revision		Revision as of 18:50, 16 December 2022
Line 66:		Line 66:
	*<code>FixationViolated</code> - This state is set to "1" when the GazeMonitorFilter has determined that fixation is violated and is set back to 0 when fixation is acquired again.		*<code>FixationViolated</code> - This state is set to "1" when the GazeMonitorFilter has determined that fixation is violated and is set back to 0 when fixation is acquired again.
	*<code>GazeCorrectionMode</code> - This state is monitored by GazeMonitorFilter. When this state is set to "1", GazeMonitorFilter will perform the gaze correction procedure. When the procedure has completed, the state is set by GazeMonitorFilter back to 0.		*<code>GazeCorrectionMode</code> - This state is monitored by GazeMonitorFilter. When this state is set to "1", GazeMonitorFilter will perform the gaze correction procedure. When the procedure has completed, the state is set by GazeMonitorFilter back to 0.
			*<code>FixationDuration</code> - 16-bit state that records the duration of the gaze being continuously fixated. It restarts from 0 every time the fixation is violated. Its units are the same as SourceTime.

	==Gaze Correction Mode==		==Gaze Correction Mode==

Wengelhardt: Added ChangeFixation

2021-07-02T17:11:00Z

Added ChangeFixation

← Older revision		Revision as of 17:11, 2 July 2021
Line 7:		Line 7:
	==Versioning==		==Versioning==
	===Authors===		===Authors===
	Griffin Milsap (griffin.milsap@gmail.com).		Griffin Milsap (griffin.milsap@gmail.com)

			William Engelhardt (engelhardt@neurotechcenter.org)
	===Version History===		===Version History===
	07/08/2011: Initial release		*07/08/2011: Initial release
			*07/02/2021: Addition of ChangeFixation and EyeLink eye tracker implementation

	===Source Code Revisions===		===Source Code Revisions===
	*Initial development: 3389		*Initial development: 3389
	*Tested under: 3389		*Tested under: 3389
	*Known to compile under: ~~3389~~		*Known to compile under: 6327
	*Broken since: --		*Broken since: --

Line 49:		Line 52:
	*<code>FixationViolationSound</code> - The sound played every time fixation has just been violated.		*<code>FixationViolationSound</code> - The sound played every time fixation has just been violated.
	*<code>LogGazeInformation</code> - Log information about eye validity and fixation enforcement to the ApplicationLog.		*<code>LogGazeInformation</code> - Log information about eye validity and fixation enforcement to the ApplicationLog.
			*<code>ChangeFixation</code> - Allows for multiple fixations during one run.

	===Notes===		===Notes===
	*For <code>FixationX</code> and <code>FixationY</code>, the top left corner of the screen is (0.0, 0.0) and the bottom right corner of the screen is (1.0, 1.0)		*For <code>FixationX</code> and <code>FixationY</code>, the top left corner of the screen is (0.0, 0.0) and the bottom right corner of the screen is (1.0, 1.0)
			*<code>FixationX</code> and <code>FixationY</code> can each be a list if <code>ChangeFixation</code> is on. Otherwise, they should just be a scalar.
			*<code>ChangeFixation</code> is ordered according to the expression <code>StimulusCode</code>. For example, when <code>StimulusCode==2</code>, the second number of both <code>FixationX</code> and <code>FixationY</code> will be the new fixation zone. Therefore, if <code>ChangeFixation</code> is on, <code>StimulusCode</code> should not equal 0.
	*Specifying large images for <code>FixationImage</code> and <code>FixationViolationImage</code> is not recommended as it may have a detrimental impact on overall system timing.		*Specifying large images for <code>FixationImage</code> and <code>FixationViolationImage</code> is not recommended as it may have a detrimental impact on overall system timing.
	*If either of the timing parameters (<code>BlinkTime</code> and <code>SaccadeTime</code>) trigger a fixation violation, fixation violation will not occur again when the other timing parameter triggers if fixation has not been acquired again. (Example: One second is allotted for <code>BlinkTime</code> and 4 seconds is allotted for <code>SaccadeTime</code>. Gaze moves outside of fixation and eyes close immediately thereafter and remain closed. <code>FixationViolated</code> is set after one second of the eyes being closed, and is not thrown again when the four seconds of gaze existing outside the allowed fixation radius elapse.)		*If either of the timing parameters (<code>BlinkTime</code> and <code>SaccadeTime</code>) trigger a fixation violation, fixation violation will not occur again when the other timing parameter triggers if fixation has not been acquired again. (Example: One second is allotted for <code>BlinkTime</code> and 4 seconds is allotted for <code>SaccadeTime</code>. Gaze moves outside of fixation and eyes close immediately thereafter and remain closed. <code>FixationViolated</code> is set after one second of the eyes being closed, and is not thrown again when the four seconds of gaze existing outside the allowed fixation radius elapse.)

Gmilsap: /* Parameters */ New image size parameter

2011-07-19T15:58:17Z

Parameters: New image size parameter

← Older revision		Revision as of 15:58, 19 July 2011
Line 46:		Line 46:
	*<code>FixationImage</code> - The image displayed at the center of fixation while fixation is not violated.		*<code>FixationImage</code> - The image displayed at the center of fixation while fixation is not violated.
	*<code>FixationViolationImage</code> - The image displayed at the center of fixation while fixation is violated.		*<code>FixationViolationImage</code> - The image displayed at the center of fixation while fixation is violated.
			*<code>FixationImageSize</code> - The fixation image size in percentage of the screen height
	*<code>FixationViolationSound</code> - The sound played every time fixation has just been violated.		*<code>FixationViolationSound</code> - The sound played every time fixation has just been violated.
	*<code>LogGazeInformation</code> - Log information about eye validity and fixation enforcement to the ApplicationLog.		*<code>LogGazeInformation</code> - Log information about eye validity and fixation enforcement to the ApplicationLog.

Gmilsap: /* Reacting to Fixation Violation Within a Task */

2011-07-08T15:19:12Z

Reacting to Fixation Violation Within a Task

← Older revision		Revision as of 15:19, 8 July 2011
Line 136:		Line 136:
	</pre>		</pre>

	*Read the state wherever you need to react to it ~~this way~~:		*Read the state this way wherever you need to react to it:
	<pre>		<pre>
	if( OptionalState( "FixationViolated", 0 ) )		if( OptionalState( "FixationViolated", 0 ) )

Gmilsap: Added Documentation for GazeMonitorFilter

2011-07-08T15:17:39Z

Added Documentation for GazeMonitorFilter

New page

==Synopsis==
An application filter which greatly eases using the [[Contributions:EyetrackerLogger|EyetrackerLogger]] extension which is capable of visualizing eye tracker states in real time, manages fixation enforcement, and provides functionality for re-alignment of the subject.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/GazeMonitorFilter

==Versioning==
===Authors===
Griffin Milsap (griffin.milsap@gmail.com).
===Version History===
07/08/2011: Initial release

===Source Code Revisions===
*Initial development: 3389
*Tested under: 3389
*Known to compile under: 3389
*Broken since: --

==Functional Description==
GazeMonitorFilter is a "drop-in" application module extension which automatically performs tasks commonly associated with using an eye tracker. It has been designed for use with the [[Contributions:EyetrackerLogger|EyetrackerLogger]] extension. When added into an application module, the GazeMonitorFilter is capable of drawing to the application window or in a layer on top of the application visualization screen.

===Fixation Management===
Even without eyetracker states, the GazeMonitorFilter is capable of drawing fixation images on the screen, but with Eyetracker<Left/Right>EyeGaze<X/Y> states, GazeMonitorFilter is capable of enforcing this fixation and setting the <code>FixationViolated</code> state which indicates violation of the fixation should it occur. The fixation is entirely parameterized and allows for detailed configuration of fixation management.

===Visualization===
GazeMonitorFilter is also capable of drawing a visualization of eye position (if it's logged) and gaze location (if it's logged) to the application window visualization screen. This enables the experimenter to monitor the eye tracker states visually in realtime for early detection (and later correction) of acquiring poor gaze data.

===Subject Correction===
With many eye trackers, accuracy diminishes as gaze diverts from the center of the screen. Even if the eye tracker is well calibrated, a sizable difference can exist between where the subject is actually looking and where the eye tracker gaze data reports the subject is looking. With Tobii eye trackers, this was seen more prominently as the subject's head changed position or orientation. GazeMonitorFilter provides functionality for giving the subject visual feedback and prompts which direct the subject to move back to the position they calibrated in.

If asked nicely, the GazeMonitorFilter may also brew you a cup of coffee.

==Integration into BCI2000==
Compile the extension into your application modules by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_GAZEMONITORFILTER'''.

==Parameters==
The GazeMonitorFilter is configured in the Application tab within the GazeMonitor section. The configurable parameters are:

*<code>VisualizeGazeMonitorFilter</code> - Enables/Disables visualization of eye tracker states on the application visualization window
*<code>EnforceFixation</code> - Enables/Disables fixation management.
*<code>FixationX</code> - Expression which defines requested fixation location X coordinate. (0.0 - 1.0)
*<code>FixationY</code> - Expression which defines requested fixation location Y coordinate. (0.0 - 1.0)
*<code>BlinkTime</code> - The amount of time allowed for which eye states reported by [[Contributions:EyetrackerLogger|EyetrackerLogger]] can remain "invalid" before fixation has been violated.
*<code>SaccadeTime</code> - The amount of time allowed for which valid gaze data reported by [[Contributions:EyetrackerLogger|EyetrackerLogger]] can exist outside of the designated fixation before fixation has been violated.
*<code>FixationRadius</code> - The maximum distance from the center of fixation (FixationX, FixationY) from which the gaze data can deviate without violating fixation.
*<code>FixationImage</code> - The image displayed at the center of fixation while fixation is not violated.
*<code>FixationViolationImage</code> - The image displayed at the center of fixation while fixation is violated.
*<code>FixationViolationSound</code> - The sound played every time fixation has just been violated.
*<code>LogGazeInformation</code> - Log information about eye validity and fixation enforcement to the ApplicationLog.

===Notes===
*For <code>FixationX</code> and <code>FixationY</code>, the top left corner of the screen is (0.0, 0.0) and the bottom right corner of the screen is (1.0, 1.0)
*Specifying large images for <code>FixationImage</code> and <code>FixationViolationImage</code> is not recommended as it may have a detrimental impact on overall system timing.
*If either of the timing parameters (<code>BlinkTime</code> and <code>SaccadeTime</code>) trigger a fixation violation, fixation violation will not occur again when the other timing parameter triggers if fixation has not been acquired again. (Example: One second is allotted for <code>BlinkTime</code> and 4 seconds is allotted for <code>SaccadeTime</code>. Gaze moves outside of fixation and eyes close immediately thereafter and remain closed. <code>FixationViolated</code> is set after one second of the eyes being closed, and is not thrown again when the four seconds of gaze existing outside the allowed fixation radius elapse.)
*A Fixation image can be drawn when there is no gaze data available to enforce the fixation. That said, FixationViolationImage, FixationViolationSound are not ever presented and the fixation timing and radius parameters remain unused due to lack of ability to determine if fixation has indeed been violated.
*Real time visualization of gaze data on the application visualization screen is controlled by the <code>VisualizeGazeMonitorFilter</code> parameter declared by GazeMonitorFilter and the <code>AppWindow<Spatial/Temporal>Decimation</code> parameters declared by the ApplicationWindow class. Control the performance of your system by decimating how often and how large GazeMonitorFilter visualization updates are.

==State Variables==
*<code>FixationViolated</code> - This state is set to "1" when the GazeMonitorFilter has determined that fixation is violated and is set back to 0 when fixation is acquired again.
*<code>GazeCorrectionMode</code> - This state is monitored by GazeMonitorFilter. When this state is set to "1", GazeMonitorFilter will perform the gaze correction procedure. When the procedure has completed, the state is set by GazeMonitorFilter back to 0.

==Gaze Correction Mode==
Gaze correction mode is initiated by setting the state <code>GazeCorrectionMode</code> to "1". GazeMonitorFilter will then perform the gaze correction procedure and set the state back to "0" when the procedure has concluded.

During the procedure, a prompt will be displayed to the subject on the application window at their current gaze location. The prompt position is "smoothed" to increase readability of the prompt and is not an accurate representation of where the subject's gaze is located at any particular frame.

===Gaze Correction Procedure===
#Subject is prompted to "Fixate". The subject will need to move his/her gaze into the fixation position/radius in order to continue in the procedure.
#Subject is prompted to move "Closer" to the screen or "Further" from the screen. The subject will need to move his/her eyes to between 550mm and 600mm away from the screen in order to continue in the procedure. Once the subject is fixated and at the correct distance from the screen, the fixation radius indicator will turn green.
#Subject must hold this position for four seconds. After four seconds (and a visual count down prompt) the procedure will be complete and the <code>GazeCorrectionMode</code> will be set back to "0"

*Note -- Eye position data is displayed to the experimenter through the application visualization window through the use of the <code>VisualizeGazeMonitorFilter</code> parameter if and only if eye position data is being logged. If the subject calibrated with their eyes centered in the eye tracker's cameras, the experimenter can re-position the subject's head during this procedure based on the feedback provided by the application visualization window. This eye position data was not included explicitly as part of the gaze correction procedure for ease of use.

==Integration of GazeMonitorFilter Capabilities==
If you wish for your task to interact with the GazeMonitorFilter, you may need to make a few small source code modifications to your task.

===Triggering Gaze Correction Mode from Within a Task===
Integration of gaze correction mode into a task consists of setting the GazeCorrectionMode state to "1" if it exists, and waiting for the state to be set back to "0" before continuing with the run. This is done as follows:

*Check for the existence of the GazeCorrectionMode state in <code>Preflight()</code>
<pre>
void
MyTask::Preflight( const SignalProperties&, SignalProperties& ) const
{
...
OptionalState( "GazeCorrectionMode" );
...
}
</pre>

*To turn on gaze correction mode
<pre>
if( States->Exists( "GazeCorrectionMode" ) )
{
State( "GazeCorrectionMode" ) = 1;
// Disable drawing of your stimuli in here
}
</pre>

*To wait for gaze correction mode to complete
<pre>
void
MyTask::Process( const GenericSignal&, GenericSignal& )
{
...
if( !OptionalState( "GazeCorrectionMode", 0 ) )
{
// Update stimuli and continue performing task related things
}
...
}
</pre>

===Triggering Gaze Correction Mode Manually===
The BCI2000 Operator provides "function" buttons which can be scripted to modify the environment. The following changes are necessary to set one of the "function" buttons to modify the <code>GazeCorrectionMode</code> state in order to allow the experimenter to trigger this mode at will:

*Open Operator.exe
*File->Preferences
*In the "Function Buttons" choose a button to modify and set the Name to "Correction" and the command to:
<pre>
SET STATE GazeCorrectionMode 1
</pre>

===Reacting to Fixation Violation Within a Task===
It may be the case that you want your task to react to a fixation violation event; for example, you may end a trial if fixation has been violated. To do this, make the following changes in your task's source code:

*Check for the existence of the <code>FixationViolated</code> state in <code>Preflight()</code>
<pre>
void
MyTask::Preflight( const SignalProperties&, SignalProperties& ) const
{
...
OptionalState( "FixationViolated" );
...
}
</pre>

*Read the state wherever you need to react to it this way:
<pre>
if( OptionalState( "FixationViolated", 0 ) )
{
// React to the fixation being violated
}
</pre>

==See also==
[[Contributions:EyetrackerLogger]], [[Contributions:Extensions]]

[[Category:Contributions]][[Category:Extension]]