Manages the Pupil Labs Core. More...

Detailed Description

Manages the Pupil Labs Core.

The eyetrackerCore methods enable the user to test for common behavioural eye tracking tasks with single commands.

Multiple fixation windows can be assigned, the windows can be either circular or rectangular. In addition rectangular exclusion windows 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 must initiate a saccade away from a position (which stops a subject cheating in a trial).

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 define what happened. Other methods include isFixated(), testFixationTime(), testHoldFixation().

Inheritance diagram for pupilCoreManager:

Public Member Functions
function	pupilCoreManager (in varargin)

function	initialise (in me, in sM, in sM2)
	initialise

function	trackerSetup (in me, in varargin)
	calibration + validation

function	startRecording (in me, in ignoredArg)
	startRecording - for iRec this just starts TCP online access, all data is saved to CSV irrespective of this

function	stopRecording (in me, in ignoredArg)
	stopRecording - for iRec this just stops TCP online access, all data is saved to CSV irrespective of this

function	getSample (in me)
	get latest sample from the tracker, if dummymode=true then use the mouse as an eye signal

function	trackerMessage (in me, in message, in ignoredArg)
	Send message to store in tracker data.

function	close (in me)
	close the iRec and cleanup, call after experiment finishes

function	runDemo (in me, in forcescreen)
	runs a demo of this class, useful for testing

function	remoteCommand (in me, in cmd)

function	checkRoundTrip (in me)

function	setPupilTime (in me, in t)

function	syncTrackerTime (in varargin)
	Sync time with tracker.

function	saveData (in varargin)
	Save the data.

function	updateDefaults (in varargin)

function	checkEye (in me)
	checks which eye is available, force left eye if binocular is enabled

function	statusMessage (in me, in message)
	displays status message on tracker, only sets it if message is not the previous message, so loop safe.

function	edfMessage (in me, in message)
	send message to store in tracker data (compatibility)

function	setup (in me)

function	setOffline (in me)
	set into offline / idle mode

function	checkConnection (in me)
	check the connection with the tobii

function	driftCorrection (in me)
	wrapper for EyelinkDoDriftCorrection

function	currentMode (in me)
	check what mode the is in

function	syncTime (in me)
	Sync time with tracker: send int32(-1000)

function	getTimeOffset (in me)
	Get offset between tracker and display computers.

function	getTrackerTime (in me)
	Get tracker time.

function	checkRecording (in me)

function	subscribe (in me)

function	unsubscribe (in me)

function	receiveMessage (in me)

function	sendNotification (in me, in notification, in time)

function	sendAnnotation (in me, in annotation, in time)

function	flushBuffer (in me)

Public Member Functions inherited from eyetrackerCore
virtual	initialise (in in)
	ALL Children must implement these methods!

virtual	trackerSetup (in in)

virtual	startRecording (in in)

virtual	stopRecording (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 Member Functions inherited from eyetrackerSmooth
function	eyetrackerSmooth ()
	This is the constructor for this class.

function get	smoothingTime (in me)
	calculate smoothing Time in ms

function	doSmoothing (in me, in in)
	smooth data in M x N where M = 2 (x&y trace) or M = 4 is x&y for both eyes. Output is 2 x 1 x + y average position

Public Attributes
Property	type
	type of eyetracker

Property	calibration
	initial setup and calibration values

Property	socket
	communication socket

Property	sub
	subscription socket

Property	pub
	publishing socket

Property	endpoint
	endpoint

Property	subEndpoint
	subscribe endpoint

Property	pubEndpoint
	subscribe endpoint

Property	startPin

Public Attributes inherited from eyetrackerCore
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.

Public Attributes inherited from eyetrackerSmooth
Property	smoothing
	options for online smoothing of peeked data

Property	smoothingTime
	calculates the smoothing in ms

Protected Attributes
Property	rawSamples

Property	ctx

Property	sv

Property	systemTime
	tracker time stamp

Property	calStim

Property	allowedProperties
	allowed properties passed to object upon construction

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

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.

Static Public Member Functions inherited from eyetrackerSmooth
static function	heuristicFilter (in indata, in level, in steps)
	Stampe 1993 heuristic filter as used by Eyelink.

Protected Member Functions inherited from eyetrackerCore
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.

Constructor & Destructor Documentation

◆ pupilCoreManager()

pupilCoreManager::pupilCoreManager ( in varargin )

pupilCoreManager CONSTRUCTOR

Parameters

varargin can be passed as a structure, or name+arg pairs

Returns: instance of the class.

Member Function Documentation

◆ checkConnection()

function pupilCoreManager::checkConnection ( in me )

virtual

check the connection with the tobii

Reimplemented from eyetrackerCore.

◆ checkEye()

function pupilCoreManager::checkEye ( in me )

checks which eye is available, force left eye if binocular is enabled

◆ checkRecording()

function pupilCoreManager::checkRecording ( in me )

◆ checkRoundTrip()

function pupilCoreManager::checkRoundTrip ( in me )

◆ close()

pupilCoreManager::close ( in me )

virtual

close the iRec and cleanup, call after experiment finishes

Reimplemented from eyetrackerCore.

◆ currentMode()

function pupilCoreManager::currentMode ( in me )

check what mode the is in

◆ driftCorrection()

function pupilCoreManager::driftCorrection ( in me )

wrapper for EyelinkDoDriftCorrection

◆ edfMessage()

function pupilCoreManager::edfMessage	(	in	me,
		in	message
	)

send message to store in tracker data (compatibility)

◆ flushBuffer()

function pupilCoreManager::flushBuffer ( in me )

◆ getSample()

pupilCoreManager::getSample ( in me )

virtual

get latest sample from the tracker, if dummymode=true then use the mouse as an eye signal

Reimplemented from eyetrackerCore.

◆ getTimeOffset()

function pupilCoreManager::getTimeOffset ( in me )

Get offset between tracker and display computers.

◆ getTrackerTime()

function pupilCoreManager::getTrackerTime ( in me )

Get tracker time.

◆ initialise()

pupilCoreManager::initialise	(	in	me,
		in	sM,
		in	sM2
	)

initialise

Parameters

sM	- screenManager for the subject
sM2	- a second screenManager used for operator, if none is provided a default will be made.

◆ receiveMessage()

function pupilCoreManager::receiveMessage ( in me )

◆ remoteCommand()

function pupilCoreManager::remoteCommand	(	in	me,
		in	cmd
	)

◆ runDemo()

pupilCoreManager::runDemo	(	in	me,
		in	forcescreen
	)

runs a demo of this class, useful for testing

Parameters

forcescreen forces to use a specific screen number

◆ saveData()

function pupilCoreManager::saveData ( in varargin )

Save the data.

◆ sendAnnotation()

function pupilCoreManager::sendAnnotation	(	in	me,
		in	annotation,
		in	time
	)

◆ sendNotification()

function pupilCoreManager::sendNotification	(	in	me,
		in	notification,
		in	time
	)

◆ setOffline()

function pupilCoreManager::setOffline ( in me )

set into offline / idle mode

◆ setPupilTime()

function pupilCoreManager::setPupilTime	(	in	me,
		in	t
	)

◆ setup()

function pupilCoreManager::setup ( in me )

◆ startRecording()

pupilCoreManager::startRecording	(	in	me,
		in	ignoredArg
	)

startRecording - for iRec this just starts TCP online access, all data is saved to CSV irrespective of this

◆ statusMessage()

function pupilCoreManager::statusMessage	(	in	me,
		in	message
	)

displays status message on tracker, only sets it if message is not the previous message, so loop safe.

◆ stopRecording()

pupilCoreManager::stopRecording	(	in	me,
		in	ignoredArg
	)

stopRecording - for iRec this just stops TCP online access, all data is saved to CSV irrespective of this

◆ subscribe()

function pupilCoreManager::subscribe ( in me )

◆ syncTime()

function pupilCoreManager::syncTime ( in me )

Sync time with tracker: send int32(-1000)

◆ syncTrackerTime()

function pupilCoreManager::syncTrackerTime ( in varargin )

Sync time with tracker.

◆ trackerMessage()

pupilCoreManager::trackerMessage	(	in	me,
		in	message,
		in	ignoredArg
	)

Send message to store in tracker data.

◆ trackerSetup()

pupilCoreManager::trackerSetup	(	in	me,
		in	varargin
	)

calibration + validation

◆ unsubscribe()

function pupilCoreManager::unsubscribe ( in me )

◆ updateDefaults()

function pupilCoreManager::updateDefaults ( in varargin )

virtual

Reimplemented from eyetrackerCore.

Member Data Documentation

◆ allowedProperties

Property pupilCoreManager::allowedProperties

protected

allowed properties passed to object upon construction

◆ calibration

Property pupilCoreManager::calibration

initial setup and calibration values

◆ calStim

Property pupilCoreManager::calStim

protected

◆ ctx

Property pupilCoreManager::ctx

protected

◆ endpoint

Property pupilCoreManager::endpoint

endpoint

◆ pub

Property pupilCoreManager::pub

publishing socket

◆ pubEndpoint

Property pupilCoreManager::pubEndpoint

subscribe endpoint

◆ rawSamples

Property pupilCoreManager::rawSamples

protected

◆ socket

Property pupilCoreManager::socket

communication socket

◆ startPin

Property pupilCoreManager::startPin

◆ sub

Property pupilCoreManager::sub

subscription socket

◆ subEndpoint

Property pupilCoreManager::subEndpoint

subscribe endpoint

◆ sv

Property pupilCoreManager::sv

protected

◆ systemTime

Property pupilCoreManager::systemTime

protected

tracker time stamp

◆ type

Property pupilCoreManager::type

type of eyetracker

The documentation for this class was generated from the following file:

eyetracker/pupilCoreManager.m

Detailed Description

Public Member Functions

Public Attributes

Protected Attributes

Additional Inherited Members

Constructor & Destructor Documentation

◆ pupilCoreManager()

Member Function Documentation

◆ checkConnection()

◆ checkEye()

◆ checkRecording()

◆ checkRoundTrip()

◆ close()

◆ currentMode()

◆ driftCorrection()

◆ edfMessage()

◆ flushBuffer()

◆ getSample()

◆ getTimeOffset()

◆ getTrackerTime()

◆ initialise()

◆ receiveMessage()

◆ remoteCommand()

◆ runDemo()

◆ saveData()

◆ sendAnnotation()

◆ sendNotification()

◆ setOffline()

◆ setPupilTime()

◆ setup()

◆ startRecording()

◆ statusMessage()

◆ stopRecording()

◆ subscribe()

◆ syncTime()

◆ syncTrackerTime()

◆ trackerMessage()

◆ trackerSetup()

◆ unsubscribe()

◆ updateDefaults()

Member Data Documentation

◆ allowedProperties

◆ calibration

◆ calStim

◆ ctx

◆ endpoint

◆ pub

◆ pubEndpoint

◆ rawSamples

◆ socket

◆ startPin

◆ sub

◆ subEndpoint

◆ sv

◆ systemTime

◆ type