ELApi Class Reference

main class for communication with the EyeLogic server More...

Classes
class	DeviceConfig
	configuration of the eye tracker More...
class	DeviceGeometry
	geometric position of the device related to the active monitor More...
class	ReturnCalibrate
	return values of calibrate( ) More...
class	ReturnConnect
	return values of connect( ) More...
class	ReturnNextData
	return values of getNextDeviceEvent( ), getNextGazeSample( ) and getNextEyeImage( ) More...
class	ReturnSetActiveScreen
	return values of setActiveScreen( ) More...
class	ReturnStart
	return values of requestTracking( ) More...
class	ReturnStreamEyeImages
	return values of streamEyeImages( ) More...
class	ReturnValidate
	return values of validate( ) More...
class	ScreenConfig
	configuration of the stimulus screen More...
class	ServerInfo
	connection information for an EyeLogic server More...
class	ValidationPointResult
	ValidationPointResult. More...
class	ValidationResult
	ValidationResult. More...

Public Member Functions
def	__init__ (self, str clientName)
	constructor More...
def	__del__ (self)
	destructor
def	registerGazeSampleCallback (self, GazeSampleCallback sampleCallback)
	registers sample callback listener More...
def	registerEyeImageCallback (self, EyeImageCallback eyeImageCallback)
	registers eye image callback listener More...
def	registerDeviceEventCallback (self, DeviceEventCallback deviceEventCallback)
	registers event callback listener More...
ReturnConnect	connect (self)
	initialize connection to the server (method is blocking until connection established). More...
ReturnConnect	connectRemote (self, ServerInfo server)
	initialize connection to a remote server (method is blocking until connection established) More...
[ServerInfo]	requestServerList (self, c_int32 blockingDurationMS, c_int32 maxNumServer)
	Ping all running EyeLogic servers in the local network and wait some time for their response. More...
def	disconnect (self)
	closes connection to the server
bool	isConnected (self)
	whether a connection to the server is established
ScreenConfig	getActiveScreen (self)
	get stimulus screen configuration More...
[ScreenConfig]	getAvailableScreens (self)
	Get a list of screens connected to the local machine. More...
ReturnSetActiveScreen	setActiveScreen (self, str id, DeviceGeometry deviceGeometry)
	Make a screen connected to this machine to the active screen. More...
DeviceConfig	getDeviceConfig (self)
	get configuration of actual eye tracker device More...
ReturnStreamEyeImages	streamEyeImages (self, c_bool enable)
	Enabled/disables eye image stream. More...
(ReturnNextData, ELDeviceEvent)	getNextDeviceEvent (self, c_int timeoutMillis)
	Obtains the next unread event or blocks until a new event occurs or the given timeout is reached. More...
(ReturnNextData, ELGazeSample)	getNextGazeSample (self, c_int timeoutMillis)
	Obtains the next unread gazeSample or blocks until a new GazeSample is received or the given timeout is reached. More...
(ReturnNextData, ELEyeImage)	getNextEyeImage (self, c_int timeoutMillis)
	Obtains the next unread eye image or blocks until a new eye image is received or the given timeout is reached. More...
ReturnStart	requestTracking (self, c_int frameRateModeInd)
	request tracking More...
def	unrequestTracking (self)
	unrequest tracking More...
def	calibrate (self, c_int calibrationModeInd)
	perform calibration (method is blocking until calibration finished) More...
def	calibrateCustom (self, c_int calibrationModeInd, c_int backgroundColor, str targetFilename)
	perform calibration (method is blocking until calibration finished) More...
def	abortCalibValidation (self)
	abort a running calibration / validation
(ReturnValidate, ValidationResult)	validate (self)
	perform validation (method is blocking until calibration finished) - calibration must be performed prior More...
(ReturnValidate, ValidationResult)	validateCustom (self, c_int backgroundColor, str targetFilename)
	perform validation (method is blocking until calibration finished) - calibration must be performed prior More...

Detailed Description

main class for communication with the EyeLogic server

Constructor & Destructor Documentation

__init__()

def __init__	(		self,
		str	clientName
	)

constructor

Parameters

clientName

string identifier of the client (shown in the server tool window), may be null

Member Function Documentation

calibrate()

def calibrate	(		self,
		c_int	calibrationModeInd
	)

perform calibration (method is blocking until calibration finished)

Parameters

calibrationModeInd

index of the requested calibration method (0 ... #calibrationMethods-1)

Returns

success state

calibrateCustom()

def calibrateCustom	(		self,
		c_int	calibrationModeInd,
		c_int	backgroundColor,
		str	targetFilename
	)

perform calibration (method is blocking until calibration finished)

Parameters

calibrationModeInd	index of the requested calibration method (0 ... #calibrationMethods-1)
backgroundColor	graylevel of the screen background color while calibrating. Note: The background color influences the eye and has therefore impact on the calibration. Choose a background color that has an almost similar brightness as the content of your experiment.
targetFilename	filename (optional, may be "") Filename of an image or animation of the calibration point target. File must be a .gif with resolution not more than 128x128 px.

Returns

success state

connect()

ReturnConnect connect

(

self

)

initialize connection to the server (method is blocking until connection established).

The connection is only established for a local server (running on this machine). For connections to a remote server,

See also

connectRemote( ).

Returns

success state

connectRemote()

ReturnConnect connectRemote	(		self,
		ServerInfo	server
	)

initialize connection to a remote server (method is blocking until connection established)

Parameters

server

Server to connect to

Returns

success state

See also

acquireServerList( ) to obtain IP address and port of a remote server

getActiveScreen()

ScreenConfig getActiveScreen

(

self

)

get stimulus screen configuration

Returns

screen configuration

getAvailableScreens()

[ScreenConfig] getAvailableScreens

(

self

)

Get a list of screens connected to the local machine.

If there are more screens than 'numScreenConfigs' found, then only the first 'numScreenConfigs' ones are filled.

Returns

list of screen configurations

getDeviceConfig()

DeviceConfig getDeviceConfig

(

self

)

get configuration of actual eye tracker device

Returns

device configuration

getNextDeviceEvent()

(ReturnNextData, ELDeviceEvent) getNextDeviceEvent	(		self,
		c_int	timeoutMillis
	)

Obtains the next unread event or blocks until a new event occurs or the given timeout is reached.

The last incoming event is buffered internally and can be obtained by calling this method in a consecutive order. If there is no new event, the method blocks until an event occurs or the given timeout is reached. The method returns SUCCESS if and only if a new event is provided which was not returned before. Therefore, by checking the return value, you can assure to not handle any event twice.

If you want to catch events in a loop, be careful to not wait too long between the calls to this method. Otherwise, you may miss events. If you want to be 100% sure to not miss any event, consider to use the ELEventCallback mechanism.

See also

registerEventListener

Parameters

timeoutMillis

duration in milliseconds, method returns at the latest after this time. May be 0 if the method should return immediatly.

Returns

first: new (yet unhandled) event. second: whether an event was received (SUCCESS) or the method terminated without a new event

getNextEyeImage()

(ReturnNextData, ELEyeImage) getNextEyeImage	(		self,
		c_int	timeoutMillis
	)

Obtains the next unread eye image or blocks until a new eye image is received or the given timeout is reached.

The last incoming eye image is buffered internally and can be obtained by calling this method in a consecutive order. If there is no new eye image, the method blocks until an eye image is received or the given timeout is reached. The method returns SUCCESS if and only if a new eye image is provided which was not returned before. Therefore, by checking the return value, you can assure to not handle any eye image twice.

If you want to catch EyeImages in a loop, be careful to not wait too long between the calls to this method (at least once per frame). Otherwise, you may miss EyeImages. If you want to be 100% sure to not miss any EyeImages, consider to use the ELEyeImagesCallback mechanism.

See also

registerEyeImagesListener

Parameters

timeoutMillis

duration in milliseconds, method returns at the latest after this time. May be 0 if the method should return immediatly.

Returns

first: new (yet unhandled) EyeImages. second: whether an event was received (SUCCESS)

getNextGazeSample()

(ReturnNextData, ELGazeSample) getNextGazeSample	(		self,
		c_int	timeoutMillis
	)

Obtains the next unread gazeSample or blocks until a new GazeSample is received or the given timeout is reached.

The last incoming GazeSample is buffered internally and can be obtained by calling this method in a consecutive order. If there is no new GazeSample, the method blocks until a GazeSample arrives or the given timeout is reached. The method returns SUCCESS if and only if a new GazeSample is provided which was not returned before. Therefore, by checking the return value, you can assure to not handle any GazeSample twice.

If you want to catch GazeSamples in a loop, be careful to not wait too long between the calls to this method (at least once per frame). Otherwise, you may miss GazeSamples. If you want to be 100% sure to not miss any GazeSample, consider to use the ELGazeSampleCallback mechanism.

See also

registerGazeSampleListener

Parameters

timeoutMillis

duration in milliseconds, method returns at the latest after this time. May be 0 if the method should return immediatly.

Returns

first: new (yet unhandled) GazeSample. second: whether an event was received (SUCCESS) or the method terminated without a new GazeSample

registerDeviceEventCallback()

def registerDeviceEventCallback	(		self,
		DeviceEventCallback	deviceEventCallback
	)

registers event callback listener

Parameters

eventCallback

this callback function is called on eye tracking events, may be null

registerEyeImageCallback()

def registerEyeImageCallback	(		self,
		EyeImageCallback	eyeImageCallback
	)

registers eye image callback listener

Parameters

eyeImageCallback

this callback function is called on new eye images, may be null

registerGazeSampleCallback()

def registerGazeSampleCallback	(		self,
		GazeSampleCallback	sampleCallback
	)

registers sample callback listener

Parameters

sampleCallback

this callback function is called on new gaze samples, may be null

requestServerList()

[ServerInfo] requestServerList	(		self,
		c_int32	blockingDurationMS,
		c_int32	maxNumServer
	)

Ping all running EyeLogic servers in the local network and wait some time for their response.

Parameters

blockingDurationMS	waiting duration in milliseconds. Method returns after this time, or if 'serverListLength' many servers responded.
maxNumServer	maximum number of server to be waited for

Returns

List of responding EyeLogic servers

requestTracking()

ReturnStart requestTracking	(		self,
		c_int	frameRateModeInd
	)

request tracking

If tracking is not yet ongoing, tracking is started in the device. If tracking is already running (e.g. started from another client) with the same frame-rate as requested, all gaze samples are reported to this client as well.

Parameters

frameRateModeInd

index of the requested frame rate mode (0 .. #frameRateModes-1)

Returns

success state

setActiveScreen()

ReturnSetActiveScreen setActiveScreen	(		self,
		str	id,
		DeviceGeometry	deviceGeometry
	)

Make a screen connected to this machine to the active screen.

Recording is from now on performed on the new active screen. Remember to perform a calibration on the new screen, otherwise it remains in an uncalibrated state.

Parameters

id	ID of the new active screen on this machine (even works if the connection to the server is remote). If null, the primary screen of this machine is set as active.
deviceGeometry	Geometry of the device which is mounted to the screen.

Returns

success/error code

streamEyeImages()

ReturnStreamEyeImages streamEyeImages	(		self,
		c_bool	enable
	)

Enabled/disables eye image stream.

If enabled, eye images are received from eye image listeners,

See also

registerEyeImageListener() and

getNextEyeImage(). Note, that enabling eye images can lead to noticable CPU load and a loss of gaze samples. Always disable it before running your experiment. Eye images can not be received via remote connections.

unrequestTracking()

def unrequestTracking

(

self

)

unrequest tracking

Note that the tracking device may continue if other processes still request tracking. Check the EyeLogic server window to observe the actual state.

validate()

(ReturnValidate, ValidationResult) validate

(

self

)

perform validation (method is blocking until calibration finished) - calibration must be performed prior

Returns

whether was completed successfully (SUCCESS) or error value and an instance of ValidationResult. Upon SUCCESS ValidationResult.pointsData will contain each stimulus point's validation data, empty list otherwise.

validateCustom()

(ReturnValidate, ValidationResult) validateCustom	(		self,
		c_int	backgroundColor,
		str	targetFilename
	)

perform validation (method is blocking until calibration finished) - calibration must be performed prior

Parameters

backgroundColor	graylevel of the screen background color while validating. Note: The background color influences the eye and has therefore impact on the validation. Choose a background color that has an almost similar brightness as the performed calibration.
targetFilename	filename (optional, may be "") Filename of an image or animation of the validation point target. File must be a .gif with resolution not more than 128x128 px.

Returns

whether was completed successfully (SUCCESS) or error value and an instance of ValidationResult. Upon SUCCESS ValidationResult.pointsData will contain each stimulus point's validation data, empty list otherwise.