Opticka 2.16.1
Opticka is an experiment manager for behavioral research.
|
class for all eyetrackers Class methods enable the user to test for common behavioural eye tracking tasks with single commands. For example, to initiate a task we normally place a fixation cross on the screen and ask the subject to saccade to the cross and maintain fixation for a particular duration. This is achieved using testSearchHoldFixation('yes','no'), using the properties: fixation.initTime to time how long the subject has to saccade into the window, fixation.time for how long they must maintain fixation, fixation.radius for the radius around fixation.X and fixation.Y position. The method returns the 'yes' string if the rules are matched, and 'no' if they are not, thus enabling experiment code to simply call this method until it returns 'yes''. Other methods include isFixated(), testFixationTime(), testHoldFixation().
This class enables several types of behavioural control:
Try using the demo mode to see it in action (read the runDemo() code to understand how to use the class):
Multiple fixation windows can be assigned (either circular or rectangular), and in addition multiple exclusion windows (exclusionZone) can ensure a subject doesn't saccade to particular parts of the screen. fixInit allows you to define a minimum time with which the subject can initiate a saccade away from a position (which stops a subject cheating by moving the eyes too soon).
For the eyelink we also allow the use of remote calibration and can call a reward systems during calibration / validation to improve subject performance compared to the eyelink toolbox alone.
Copyright ©2014-2023 Ian Max Andolina — released: LGPL3, see LICENCE.md
Public Member Functions | |
virtual | initialise (in in) |
ALL Children must implement these methods! | |
virtual | close (in in) |
virtual | checkConnection (in in) |
virtual | updateDefaults (in in) |
virtual | trackerSetup (in in) |
virtual | startRecording (in in) |
virtual | stopRecording (in in) |
virtual | getSample (in in) |
virtual | trackerMessage (in in) |
virtual | statusMessage (in in) |
virtual | runDemo (in in) |
function | eyetrackerCore (in varargin) |
This is the constructor for this class. | |
function | getMouseSample (in me) |
get mouse sample as eye data | |
function | resetAll (in me) |
reset all fixation/exclusion data | |
function | resetFixation (in me, in removeHistory) |
reset the fixation counters ready for a new trial | |
function | resetExclusionZones (in me) |
reset the exclusion state ready for a new trial | |
function | resetFixationTime (in me) |
reset the fixation time ready for a new trial | |
function | resetFixationHistory (in me) |
reset the recent fixation history: xAll yAll pupilAll | |
function | resetFixInit (in me) |
reset the fixation initiation to 0 | |
function | resetOffset (in me) |
reset the fixation offset to 0 | |
function | driftOffset (in me) |
our own version of eyelink's drift correct | |
function | updateFixationValues (in me, in x, in y, in inittime, in fixtime, in radius, in strict) |
function | updateExclusionZones (in me, in x, in y, in radius) |
Sinlge method to update the exclusion zones, can pass multiple x & y values for multiple exclusion zones, sharing the same radius. | |
function | isFixated (in me) |
isFixated tests for fixation and updates the fixLength time | |
function | testExclusion (in me) |
testExclusion | |
function | testSearchHoldFixation (in me, in yesString, in noString) |
Checks for both searching and then maintaining fix. Input is 2 strings, either one is returned depending on success or failure, 'searching' may also be returned meaning the fixation window hasn't been entered yet, and 'fixing' means the fixation time is not yet met... 'blinking' can be returned when ignoreBlinks = true and we think a blink may be occuring. | |
function | testHoldFixation (in me, in yesString, in noString) |
Checks if we're still within fix window. Input is 2 strings, either one is returned depending on success or failure, 'fixing' means the fixation time is not yet met... | |
function | testWithinFixationWindow (in me, in yesString, in noString) |
testWithinFixationWindow simply tests we are in fixwindow | |
function | testFixationTime (in me, in yesString, in noString) |
Checks if we've maintained fixation for correct time, if true return yesString, if not return noString. This allows an external code to quickly select a string based on this. Use. | |
function | checkEye (in me) |
checks which eye is available, force left eye if binocular is enabled | |
function | drawEyePosition (in me, in ignoredArg) |
draw the current eye position on the main PTB display | |
function | drawEyePositions (in me) |
draw the sampled eye positions in xAll yAll on the subject screen | |
function | trackerTrialStart (in me, in trialNumber, in task, in stimuli) |
Send trial start information to tracker. | |
function | trackerTrialEnd (in me, in result) |
Send trial end information to tracker. | |
function | trackerClearScreen (in me) |
draw the background colour | |
function | trackerFlip (in me, in dontclear, in force) |
flip the tracker display, always use dontsync | |
function | trackerDrawStatus (in me, in comment, in stimPos, in dontClear, in dontFlip) |
draw general status | |
function | trackerDrawStimuli (in me, in ts, in dontClear) |
draw the stimuli boxes on the tracker display | |
function | trackerDrawFixation (in me) |
draw the fixation box on the tracker display | |
function | trackerDrawExclusion (in me) |
draw the fixation box on the tracker display | |
function | trackerDrawEyePosition (in me) |
draw the fixation position on the tracker display | |
function | trackerDrawEyePositions (in me) |
draw the sampled eye positions in xAll yAll | |
function | trackerDrawText (in me, in textIn) |
draw the fixation box on the tracker display | |
function | doFlip (in me) |
function | edfMessage (in me, in message) |
send message to store in EDF data | |
function | getEvent (in me) |
TODO. | |
function | saveData (in me, in args) |
compatibility with tobiiManager | |
Public Member Functions inherited from optickaCore | |
function | optickaCore (in varargin) |
Class constructor. | |
function get | fullName (in me) |
function | getALF (in me, in subject, in sessionPrefix, in lab, in create) |
function | findAttributes (in me, in attrName, in attrValue) |
function | findAttributesandType (in me, in attrName, in attrValue, in type) |
find properties of object with specific attributes, for example all properties whose GetAcccess attribute is public and type is logical. | |
function | findPropertyDefault (in me, in propName) |
function | clone (in me) |
Use this syntax to make a deep copy of the object, i.e. OBJ_OUT has the same field values, but will not behave as a handle-copy of me anymore. | |
function | checkSuperclasses (in List) |
function | editProperties (in me, in properties) |
method to modify a set of properties | |
function | setProp (in me, in property, in value) |
method to fast change a particular value. This is useful for use in anonymous functions, like in the state machine. | |
function | initialiseGlobals (in me, in doReset, in doOpen) |
function | initialiseSaveFile (in me) |
Initialise Save prefix. | |
function | checkPaths (in me) |
checks the paths are valid | |
Public Attributes | |
Property | type |
type of eyetracker | |
Property | fixation |
Property | exclusionZone |
Property | fixInit |
Property | offset |
Property | sampleRate |
tracker update speed (Hz) | |
Property | isDummy |
start eyetracker in dummy mode? | |
Property | recordData |
do we record and/or retrieve eyetracker data with remote interface? | |
Property | useOperatorScreen |
use an operator screen for online display etc. | |
Property | ignoreBlinks |
Property | saveFile |
name of eyetracker EDF file | |
Property | subjectName |
subject name | |
Property | verbose |
do we log debug messages to the command window? | |
Property | calibration |
info for setup / calibration | |
Property | stimulusPositions |
stimulus positions to draw on screen | |
Property | screen |
the PTB screen to work on, passed in during initialise | |
Property | operatorScreen |
operator screen used during calibration | |
Property | win |
the PTB screen handle, normally set by screenManager but can force it to use another screen | |
Property | secondScreen |
is operator screen being used? | |
Property | eyeSize |
size to draw eye position on screen | |
Property | skipFlips |
for trackerFlip, we can only flip every X frames | |
Property | isOff |
make the eyetracker not useable | |
Property | debug |
lots of logging if debug = true | |
Property | x |
Gaze X position in degrees. | |
Property | y |
Gaze Y position in degrees. | |
Property | pupil |
pupil size | |
Property | isFix |
last isFixated true/false result | |
Property | isInitFail |
did the fixInit test fail or not? | |
Property | isBlink |
are we in a blink? | |
Property | isExclusion |
are we in an exclusion zone? | |
Property | fixTotal |
total time searching for and holding fixation | |
Property | fixInitLength |
Initiate fixation length. | |
Property | fixLength |
how long have we been in the fixation window? | |
Property | fixBuffer |
when ~strict, we accumulate the total time in the window | |
Property | fixInitStartTime |
Initiate fixation time. | |
Property | fixStartTime |
Property | fixWindow |
which fixation window matched the last fixation? | |
Property | currentOffset |
last time offset betweeen tracker and display computers | |
Property | trackerTime |
tracker time stamp | |
Property | currentSample |
Property | currentEvent |
Property | isConnected |
Property | isRecording |
Property | eyeUsed |
Property | version |
Property | xAll |
All gaze X position in degrees reset using resetFixation. | |
Property | yAll |
Last gaze Y position in degrees reset using resetFixation. | |
Property | pupilAll |
all pupil size reset using resetFixation | |
Property | data |
data streamed out from the Tobii | |
Property | validationData |
validation data | |
Property | xAllRaw |
Property | yAllRaw |
Property | flipTick |
flipTick | |
Property | sampleTemplate |
currentSample template | |
Property | ppd_ |
Property | fixN |
Property | fixSelection |
Property | allowedPropertiesBase |
allowed properties passed to object upon construction | |
Public Attributes inherited from optickaCore | |
Property | name |
object name | |
Property | comment |
comment | |
Property | verbose |
verbose logging, subclasses must assign this. This is normally logical true/false | |
Property | dateStamp |
clock() dateStamp set on construction | |
Property | uuid |
universal ID | |
Property | paths |
storage of various paths | |
Property | fullName |
The fullName is the object name combined with its uuid and class name. | |
Protected Member Functions | |
function | drawValidationResults (in me, in n) |
function | toDegrees (in me, in in, in axis, in inputtype) |
to visual degrees from pixels | |
function | toPixels (in me, in in, in axis, in inputtype) |
to pixels from visual degrees / relative input can be [x] [y] [-x -y +x +y]('rect') [xy] or [-x +x -y +y] | |
Protected Member Functions inherited from optickaCore | |
function | parseArgs (in me, in args, in allowedProperties) |
Sets properties from a structure or normal arguments pairs, ignores invalid or non-allowed properties. | |
function | addArgs (in me, in args) |
function | setPaths (in me) |
Sets properties from a structure or normal arguments pairs, ignores invalid or non-allowed properties. | |
function | getFonts (in me) |
set paths for object | |
function | toStructure (in me) |
Converts properties to a structure. | |
function | getType (in me, in in) |
function | logOutput (in me, in in, in message, in override) |
Give a metaproperty return the likely property class. | |
function | salutation (in me, in varargin) |
Prints messages dependent on verbosity. | |
Additional Inherited Members | |
Static Public Member Functions inherited from optickaCore | |
static function | makeArgs (in args) |
Converts cell args to structure array. | |
static function | addDefaults (in args, in defs) |
add default options to arg input | |
static function | hasKey (in in, in key) |
check if a struct / object has a propery / field | |
static function | getKeys (in device) |
PTB Get key presses, stops key bouncing. | |
Protected Attributes inherited from optickaCore | |
Property | cloning |
are we cloning this from another object | |
Property | mversion |
Matlab version number, this is transient so it is not saved. | |
Property | sansFont |
sans font | |
Property | monoFont |
monoFont | |
Property | className |
class name | |
Property | savePrefix |
save prefix generated from clock time | |
Property | fullName_ |
cached full name | |
function eyetrackerCore::eyetrackerCore | ( | in | varargin | ) |
This is the constructor for this class.
|
virtual |
Reimplemented in eyelinkManager, iRecManager, pupilCoreManager, and tobiiManager.
function eyetrackerCore::checkEye | ( | in | me | ) |
checks which eye is available, force left eye if binocular is enabled
|
virtual |
Reimplemented in eyelinkManager, iRecManager, pupilCoreManager, and tobiiManager.
function eyetrackerCore::doFlip | ( | in | me | ) |
eyetrackerCore::drawEyePosition | ( | in | me, |
in | ignoredArg | ||
) |
draw the current eye position on the main PTB display
function eyetrackerCore::drawEyePositions | ( | in | me | ) |
draw the sampled eye positions in xAll yAll on the subject screen
|
protected |
eyetrackerCore::driftOffset | ( | in | me | ) |
our own version of eyelink's drift correct
function eyetrackerCore::edfMessage | ( | in | me, |
in | message | ||
) |
send message to store in EDF data
function eyetrackerCore::getEvent | ( | in | me | ) |
TODO.
function eyetrackerCore::getMouseSample | ( | in | me | ) |
get mouse sample as eye data
|
virtual |
Reimplemented in eyelinkManager, iRecManager, pupilCoreManager, and tobiiManager.
|
virtual |
ALL Children must implement these methods!
function eyetrackerCore::isFixated | ( | in | me | ) |
isFixated tests for fixation and updates the fixLength time
function eyetrackerCore::resetAll | ( | in | me | ) |
reset all fixation/exclusion data
function eyetrackerCore::resetExclusionZones | ( | in | me | ) |
reset the exclusion state ready for a new trial
function eyetrackerCore::resetFixation | ( | in | me, |
in | removeHistory | ||
) |
reset the fixation counters ready for a new trial
removeHistory | remove the history of recent eye position? |
function eyetrackerCore::resetFixationHistory | ( | in | me | ) |
reset the recent fixation history: xAll yAll pupilAll
function eyetrackerCore::resetFixationTime | ( | in | me | ) |
reset the fixation time ready for a new trial
function eyetrackerCore::resetFixInit | ( | in | me | ) |
reset the fixation initiation to 0
function eyetrackerCore::resetOffset | ( | in | me | ) |
reset the fixation offset to 0
|
virtual |
function eyetrackerCore::saveData | ( | in | me, |
in | args | ||
) |
compatibility with tobiiManager
|
virtual |
|
virtual |
|
virtual |
function eyetrackerCore::testExclusion | ( | in | me | ) |
testExclusion
function eyetrackerCore::testFixationTime | ( | in | me, |
in | yesString, | ||
in | noString | ||
) |
Checks if we've maintained fixation for correct time, if true return yesString, if not return noString. This allows an external code to quickly select a string based on this. Use.
function eyetrackerCore::testHoldFixation | ( | in | me, |
in | yesString, | ||
in | noString | ||
) |
Checks if we're still within fix window. Input is 2 strings, either one is returned depending on success or failure, 'fixing' means the fixation time is not yet met...
yesString | if this function succeeds return this string |
noString | if this function fails return this string |
function eyetrackerCore::testSearchHoldFixation | ( | in | me, |
in | yesString, | ||
in | noString | ||
) |
Checks for both searching and then maintaining fix. Input is 2 strings, either one is returned depending on success or failure, 'searching' may also be returned meaning the fixation window hasn't been entered yet, and 'fixing' means the fixation time is not yet met... 'blinking' can be returned when ignoreBlinks = true and we think a blink may be occuring.
yesString | if this function succeeds return this string |
noString | if this function fails return this string |
function eyetrackerCore::testWithinFixationWindow | ( | in | me, |
in | yesString, | ||
in | noString | ||
) |
testWithinFixationWindow simply tests we are in fixwindow
|
protected |
to visual degrees from pixels
|
protected |
to pixels from visual degrees / relative input can be [x] [y] [-x -y +x +y]('rect') [xy] or [-x +x -y +y]
function eyetrackerCore::trackerClearScreen | ( | in | me | ) |
draw the background colour
function eyetrackerCore::trackerDrawExclusion | ( | in | me | ) |
draw the fixation box on the tracker display
function eyetrackerCore::trackerDrawEyePosition | ( | in | me | ) |
draw the fixation position on the tracker display
function eyetrackerCore::trackerDrawEyePositions | ( | in | me | ) |
draw the sampled eye positions in xAll yAll
function eyetrackerCore::trackerDrawFixation | ( | in | me | ) |
draw the fixation box on the tracker display
function eyetrackerCore::trackerDrawStatus | ( | in | me, |
in | comment, | ||
in | stimPos, | ||
in | dontClear, | ||
in | dontFlip | ||
) |
draw general status
function eyetrackerCore::trackerDrawStimuli | ( | in | me, |
in | ts, | ||
in | dontClear | ||
) |
draw the stimuli boxes on the tracker display
function eyetrackerCore::trackerDrawText | ( | in | me, |
in | textIn | ||
) |
draw the fixation box on the tracker display
function eyetrackerCore::trackerFlip | ( | in | me, |
in | dontclear, | ||
in | force | ||
) |
flip the tracker display, always use dontsync
remember: dontclear affects the NEXT flip, not this one!
|
virtual |
|
virtual |
Reimplemented in eyelinkManager.
function eyetrackerCore::trackerTrialEnd | ( | in | me, |
in | result | ||
) |
Send trial end information to tracker.
result | a code at the trial end |
function eyetrackerCore::trackerTrialStart | ( | in | me, |
in | trialNumber, | ||
in | task, | ||
in | stimuli | ||
) |
Send trial start information to tracker.
trialNumber | the unique number or string for this trial |
|
virtual |
Reimplemented in eyelinkManager, tobiiManager, iRecManager, and pupilCoreManager.
function eyetrackerCore::updateExclusionZones | ( | in | me, |
in | x, | ||
in | y, | ||
in | radius | ||
) |
Sinlge method to update the exclusion zones, can pass multiple x & y values for multiple exclusion zones, sharing the same radius.
x | x position[s] in degrees |
y | y position[s] in degrees |
radius | the radius of the exclusion zone, if length=2 becomes WxH |
eyetrackerCore::updateFixationValues | ( | in | me, |
in | x, | ||
in | y, | ||
in | inittime, | ||
in | fixtime, | ||
in | radius, | ||
in | strict | ||
) |
Sinlge method to update the fixation parameters. See property descriptions for full details. You can pass empty values if you only need to update one parameter, e.g. me.updateFixationValues([],[],1);
x | X position |
y | Y position |
inittime | time to initiate fixation |
fixtime | time to maintain fixation @paran radius radius of fixation window |
strict | allow or disallow re-entering the fixation window |
Property eyetrackerCore::allowedPropertiesBase |
allowed properties passed to object upon construction
Property eyetrackerCore::calibration |
info for setup / calibration
Property eyetrackerCore::currentEvent |
Property eyetrackerCore::currentOffset |
last time offset betweeen tracker and display computers
Property eyetrackerCore::currentSample |
Property eyetrackerCore::data |
data streamed out from the Tobii
Property eyetrackerCore::debug |
lots of logging if debug = true
Property eyetrackerCore::exclusionZone |
Use exclusion zones where no eye movement allowed: [-degX +degX -degY +degY] Add rows to generate multiple exclusion zones.
Property eyetrackerCore::eyeSize |
size to draw eye position on screen
Property eyetrackerCore::eyeUsed |
Property eyetrackerCore::fixation |
fixation window in deg with 0,0 being the screen center:
if X and Y have multiple rows, assume each row is a different fixation window. so that multiple fixtation windows can be used.
if radius has as single value, assume circular window if radius has 2 values assume width × height rectangle (not strictly a radius I know!)
initTime is the time the subject has to initiate fixation
time is the time the subject must maintain fixation within the window
strict = false allows subject to exit and enter window without failure, useful during training
Property eyetrackerCore::fixBuffer |
when ~strict, we accumulate the total time in the window
Property eyetrackerCore::fixInit |
we can define an optional window that the subject must stay inside before they saccade to other targets. This restricts guessing and "cheating", by forcing a minimum delay (default = 100ms / 0.1s) before initiating a saccade. Only used if X position is not empty.
Property eyetrackerCore::fixInitLength |
Initiate fixation length.
Property eyetrackerCore::fixInitStartTime |
Initiate fixation time.
Property eyetrackerCore::fixLength |
how long have we been in the fixation window?
Property eyetrackerCore::fixN |
Property eyetrackerCore::fixSelection |
Property eyetrackerCore::fixStartTime |
Property eyetrackerCore::fixTotal |
total time searching for and holding fixation
Property eyetrackerCore::fixWindow |
which fixation window matched the last fixation?
Property eyetrackerCore::flipTick |
flipTick
Property eyetrackerCore::ignoreBlinks |
do we ignore blinks, if true then we do not update X and Y position from previous eye location, meaning the various methods will maintain position, e.g. if you are fixated and blink, the within-fixation X and Y position are retained so that a blink does not "break" fixation.
Property eyetrackerCore::isBlink |
are we in a blink?
Property eyetrackerCore::isConnected |
Property eyetrackerCore::isDummy |
start eyetracker in dummy mode?
Property eyetrackerCore::isExclusion |
are we in an exclusion zone?
Property eyetrackerCore::isFix |
last isFixated true/false result
Property eyetrackerCore::isInitFail |
did the fixInit test fail or not?
Property eyetrackerCore::isOff |
make the eyetracker not useable
Property eyetrackerCore::isRecording |
Property eyetrackerCore::offset |
add a manual offset to the eye position, similar to a drift correction but handled by the eyelinkManager.
Property eyetrackerCore::operatorScreen |
operator screen used during calibration
Property eyetrackerCore::ppd_ |
Property eyetrackerCore::pupil |
pupil size
Property eyetrackerCore::pupilAll |
all pupil size reset using resetFixation
Property eyetrackerCore::recordData |
do we record and/or retrieve eyetracker data with remote interface?
Property eyetrackerCore::sampleRate |
tracker update speed (Hz)
Property eyetrackerCore::sampleTemplate |
currentSample template
Property eyetrackerCore::saveFile |
name of eyetracker EDF file
Property eyetrackerCore::screen |
the PTB screen to work on, passed in during initialise
Property eyetrackerCore::secondScreen |
is operator screen being used?
Property eyetrackerCore::skipFlips |
for trackerFlip, we can only flip every X frames
Property eyetrackerCore::stimulusPositions |
stimulus positions to draw on screen
Property eyetrackerCore::subjectName |
subject name
Property eyetrackerCore::trackerTime |
tracker time stamp
Property eyetrackerCore::type |
type of eyetracker
Property eyetrackerCore::useOperatorScreen |
use an operator screen for online display etc.
Property eyetrackerCore::validationData |
validation data
Property eyetrackerCore::verbose |
do we log debug messages to the command window?
Property eyetrackerCore::version |
Property eyetrackerCore::win |
the PTB screen handle, normally set by screenManager but can force it to use another screen
Property eyetrackerCore::x |
Gaze X position in degrees.
Property eyetrackerCore::xAll |
All gaze X position in degrees reset using resetFixation.
Property eyetrackerCore::xAllRaw |
Property eyetrackerCore::y |
Gaze Y position in degrees.
Property eyetrackerCore::yAll |
Last gaze Y position in degrees reset using resetFixation.
Property eyetrackerCore::yAllRaw |