Overview

Reads ASL/serial port gaze and pupil size data.

dotsReadableEyeASL extends the dotsReadableEye superclass to acquire point of gaze and pupil size data from an ASL eye tracker connected via the serial port.

It uses the as() mex funciton (which is only for Mac OS X) to buffer and decode the streaming serial port data. as() makes a number of assumptions about the data format, including that the data frames are 12 bytes and include the frame number.

Inheritance diagram for dotsReadableEyeASL:

[legend]

Properties and Events
Property	timedFrames = []
	nx2 matrix of ASL frame numbers and clockFunction timestamps More...

Property	frameMaxInt = (2^16)-1
	the largest frame number integer that ASL can represent More...

Properties and Events inherited from dotsReadableEye
Property	x
	the current "x" position of the eye in user-defined coordinates.

Property	y
	the current "y" position of the eye in user-defined coordinates.

Property	pupil
	the current pupil size, offset and scaled

Property	time
	The time of the most-recent sample (in ui time)

Property	sampleFrequency
	frequency in Hz of eye tracker data samples More...

Property	readEventsOnly = true
	Flag determining whether only to read event data see readNewData for details. More...

Property	helpers
	helper objects including screen ensemble

	gazeMonitor
	Gaze monitor properties.

Properties and Events inherited from dotsReadable
Property	isAvailable = false
	whether or not the object is ready to read() from

Property	components
	struct array with details about each component

Property	state
	matrix of ID, latest value, and latest time indexed by ID

Property	history
	matrix of component ID, value, and time from previous read()

Property	isAutoRead = true
	whether or not to to invoke read() during getValue(), etc.

Property	eventDefinitions
	struct array defining events of interest, indexed by ID

Property	initialEventQueueSize = 100
	initial size of queue for events of interest

Property	clockFunction
	any function that returns the current time as a number

Property	filename
	name of the data file for devices that store their own data

Property	filepath
	where the file is

Property	recordDuringCalibration = true
	controls whether or not to stop recording during calibration

Property	useGUI = false
	Flag to use GUI for feedback, etc.

Property	useExistingCalibration = false
	Flag to skip calibration routine.

Property	calibrationUI
	Possibly use a keyboard or other UI to help with calibration.

Property	deactivateEventsAtStartTrial =false
	Flag to deactivate all events at the beginning of each trial.

Methods
self	dotsReadableEyeASL ()
	Constructor takes no arguments.

	flushData (self)
	Clear data from this object and the as() internal buffer. More...

Methods inherited from dotsReadable
self	dotsReadable ()
	Constructor takes no arguments.

	initialize (self)
	Locate, acquire, configure, etc. device and component resources.

	calibrate (self, varargin)
	Calibrate the device More...

	record (self, onFlag, filename)
	Open/close data file associated with the device Arguments: onFlag ... More...

	reset (self, varargin)
	reset device More...

	close (self)
	Release any resources acquired by initialize().

	delete (self)
	Automatically close when Matlab is done with this object.

	read (self)
	Add incoming data to history and detect events of interest. More...

	flushData (self, waitForNoEvents)
	Delete historical data and reset the current state. More...

	logData (self)
	Record current and historical data in topsDataLog. More...

stateAtTime	getState (self, time)
	Get the state of device components as of the given time. More...

value data	getValue (self, ID)
	Get the latest value for the given component. More...

event	defineEvent (self, name, varargin)
	Define the event of interest for one of the input components. More...

	defineEventsFromComponents (self, names, varargin)
	defineEventsFromComponents More...

	defineEventsFromStruct (self, eventStruct, setName, keepExisting, inactivate)
	defineEventsFromStruct More...

	showActiveEvents (self)
	Mostly for debugging.

	activateEventSet (self, name)
	Swap in a set of events.

	activateEvents (self)
	Activate all events. More...

	deactivateEvents (self)
	Deactivate all events. More...

activeFlags	getActiveFlags (self)
	Get all active flags.

	setActiveFlags (self, activeFlags)
	Set all active flags from array.

	setEventsActiveFlag (self, activateList, deactivateList)
	Set/unset activeFlag. More...

name data	getNextEvent (self, isPeek, acceptedEvents)
	Get the next event that was detected in read(). More...

lastName lastID names IDs	getHappeningEvent (self, time)
	Get events that are happening at the current time. More...

name waitTime data	waitForEvents (self, eventNames, maxWait)
	Wait for event(s)

nEvents	getNumberOfEvents (self)
	Get the number of events in eventQueue. More...

IDs	getComponentIDs (self)
	Get an array of unique integer component IDs. More...

ID	getComponentID (self, nameOrID)
	Get ID of component by name or ID

name	getComponentName (self, nameOrID)
	Get name of component by name or ID

indices	getComponentIndicesByID (self, IDs)
	Get array of indices for the given component IDs

indices	getComponentIndicesByName (self, names)
	Get array of indices for the given component names

time	getDeviceTime (self)
	Get the current time from clockFunction.

	setDeviceTime (self, val)
	Set the device time

	startTrial (self, varargin)
	startTrial() More...

	finishTrial (self, varargin)
	finishTrial() More...

	plotData (self)
	Open a figure with continuously read device data. More...

	startTrialDevice (self, varargin)
	Overloaded methods.

Protected Methods
isOpen	openDevice (self)
	Acquire ASL serial port resources. More...

	closeDevice (self)
	Release ASL serial port resources. More...

newData	readRawEyeData (self)
	Read raw ASL data from the serial port. More...

Protected Methods inherited from dotsReadable
isOpen	openDevice (self)
	Locate and acquire input device resources (for subclasses). More...

	closeDevice (self)
	Release input device resources (for subclasses). More...

	resetDevice (self, varargin)
	Reset the device.

status	calibrateDevice (self, varargin)
	Calibrate the device (for subclasses). More...

isRecording	startRecording (self)
	Turn on data recording from the device (for subclasses).

isRecording	stopRecording (self)
	Turn off data recording from the device (for subclasses).

components	openComponents (self)
	Locate and acquire device components (for subclasses). More...

	closeComponents (self)
	Release device components (for subclasses). More...

newData	readNewData (self)
	Read and format incoming data (for subclasses). More...

isEvent	detectEvents (self, data)
	Use new data to look up events of interest (used internally). More...

newSize	resizeEventQueue (self, minSize, doClear)
	Resize and optionally clear the event queue (used internally). More...

nEvents	enqueueEvents (self, eventValues)
	Add events of interest to the event queue (used internally). More...

eventValue nEvents	dequeueEvent (self, isPeek)
	Remove the next queued event of interest (used internally). More...

Static Methods
static frameNumbers	correctOverflow (frameNumbers, maxInt)
	Try to correct frame numbers which overflowed. More...

static frameTimes	computeFrameTimes (frameNumbers, nowTime, sampleFrequency)
	Compute frame times based on frame numbers. More...

static frameNumbers	reconstructFrameNumbers (frameTimes, timedFrames, sampleFrequency)
	Reconstruct ASL integer frame numbers from frame timestamps. More...

Static Methods inherited from dotsReadable
static isHappening data readable	isEventHappening (readables, eventName)
	Is the named event happening now? More...

static didHappen waitTime data readable name	waitForEvent (readables, eventName, maxWait)
	Wait for the named event to happen. More...

static data	loadDataFile (filename, varargin)
	Load data from file. More...

Additional Inherited Members
Protected Properties inherited from dotsReadable
Property	eventQueue
	array of queued events (row indices into history)

Property	queueNext
	queue index of the next event to be dequeued

Property	queueLast =0
	queue index of the last event enqueued

Property	isRecording =false
	keep track of whether device is currenly writing to a data file

Property	didCalibrate = true
	Keep track of whether calibration occurs.

Property	defaultEventPrefix = 'event'
	Default prefix for event names: <prefix>_<componentName>

Property	eventSets
	Strutures with different named event definitions, in case we want to quickly swap between them.

Methods

◆ flushData()

flushData ( self )

Clear data from this object and the as() internal buffer.

Extends the dotsReadable flushData() method to also clear out the as() internal data buffer and discard old frame timestamps.

◆ openDevice()

isOpen openDevice ( self )

protected

Acquire ASL serial port resources.

Initializes the the as() mex function, returns true if successful, otherwise returns false.

◆ closeDevice()

closeDevice ( self )

protected

Release ASL serial port resources.

Closes the as() mex function.

◆ readRawEyeData()

newData readRawEyeData ( self )

protected

Read raw ASL data from the serial port.

Reads out any buffered data frames from the as() mex function's internal buffer. Reformats the data in the dotsReadable style.

as() reports data frames in four columns as

[x y pupil frameNumber]

Converts these to the dotsReadable three-column style as

[xID, x, timestamp]
[yID, y, timestamp]
[pupilID, pupilSize, timestamp]

where timestamp is derived from the ASL frameNumber, sampleFrequency, and the current time.

Appends the latest frameNumber and the current time to timedFrames.

◆ correctOverflow()

static frameNumbers correctOverflow	(	frameNumbers	,
		maxInt
	)

static

Try to correct frame numbers which overflowed.

Parameters

frameNumbers	ASL integer frame numbers
maxInt	the largest integer ASL can represent

Attempts to correct frame numbers that overflowed their integer representation. Assumes that frame numbers should always increase. Where they decrease, adds maxInt + 1 as though the next more significant digit were present.

◆ computeFrameTimes()

static frameTimes computeFrameTimes	(	frameNumbers	,
		nowTime	,
		sampleFrequency
	)

static

Compute frame times based on frame numbers.

Parameters

frameNumbers	ASL integer frame numbers
nowTime	the time to align with the last frame number
sampleFrequency	ASL sample frequency

Appends the lasts frame number in frameNumbers and the given localTime to timedFrames. Uses this pair and the ASL sample frequency to compute a frame time for each frame number in in frameNumbers.

◆ reconstructFrameNumbers()

static frameNumbers reconstructFrameNumbers	(	frameTimes	,
		timedFrames	,
		sampleFrequency
	)

static

Reconstruct ASL integer frame numbers from frame timestamps.

Parameters

frameTimes	frame times from computeFrameTimes()
timedFrames	nx2 pairs of [frameNumber frameTime]
sampleFrequency	ASL sample frequency

Reconstructs the "raw" frame numbers reported by ASL, based on data saved in the nx3 dotsReadable format. This is intended to help with post-hoc validation and analysis.

Returns the frame number for each frame time in frameTimes.

Properties and Events

◆ timedFrames

Property timedFrames = []

nx2 matrix of ASL frame numbers and clockFunction timestamps

Each call to readRawData() adds a row to timedFrames. The first column contains frame numbers returned from as(). The second column contains a timestamp from clockFunction. dotsReadableEyeASL assumes that the numbered frame coincided with the timestamp.

◆ frameMaxInt

Property frameMaxInt = (2^16)-1

the largest frame number integer that ASL can represent

ASL reports frame numbers as integers which overflow periodically. readRawEyeData() uses frameMaxInt to correct for the overflow, even if frames are dropped.

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

dotsReadableEyeASL.m

Overview

Properties and Events

Methods

Protected Methods

Static Methods

Additional Inherited Members

Methods

◆ flushData()

◆ openDevice()

◆ closeDevice()

◆ readRawEyeData()

◆ correctOverflow()

◆ computeFrameTimes()

◆ reconstructFrameNumbers()

Properties and Events

◆ timedFrames

◆ frameMaxInt