pytribe.py

# PyTribe: classes to communicate with EyeTribe eye trackers
#
# author: Edwin Dalmaijer
# email: edwin.dalmaijer@psy.ox.ac.uk
#
# version 4 (21-Jun-2016)

import os
import copy
import json
import time
import socket
import codecs
from threading import Lock, Thread
from multiprocessing import Event, Process, Queue
from py3compat import *


# # # # #
# EYETRIBE CLASS

# The original EyeTribe class from earlier versions of PyTribe.
class EyeTribe:

	"""class for eye tracking and data collection using an EyeTribe tracker
	"""

	def __init__(self, logfilename='default', host='localhost', port=6555):

		"""Initializes an EyeTribe instance

		keyword arguments

		logfilename	--	string indicating the log file name, including
						a full path to it's location and an extension
						(default = 'default.txt')
		"""
		
		# initialize data collectors
		self._logfile = codecs.open('%s.tsv' % (logfilename), 'w', u'utf-8')
		self._separator = u'\t'
		self._log_header()
		self._queue = Queue()

		# initialize connection
		self._connection = connection(host=host, port=port)
		self._tracker = tracker(self._connection)
		self._heartbeat = heartbeat(self._connection)

		# create a new Lock
		self._lock = Lock()

		# initialize heartbeat thread
		self._beating = True
		self._heartbeatinterval = self._tracker.get_heartbeatinterval() / 1000.0
		self._hbthread = Thread(target=self._heartbeater, args=[self._heartbeatinterval])
		self._hbthread.daemon = True
		self._hbthread.name = 'heartbeater'

		# initialize sample streamer
		self._streaming = True
		self._samplefreq = self._tracker.get_framerate()
		self._intsampletime = 1.0 / self._samplefreq
		self._clockdiff = None
		self._newestframe = self._tracker.get_frame()
		self._ssthread = Thread(target=self._stream_samples, args=[self._queue])
		self._ssthread.daemon = True
		self._ssthread.name = 'samplestreamer'

		# initialize data processer
		self._processing = True
		self._logdata = False
		self._currentsample = copy.deepcopy(self._newestframe)
		self._dpthread = Thread(target=self._process_samples, args=[self._queue])
		self._dpthread.daemon = True
		self._dpthread.name = 'dataprocessor'

		# start all threads
		self._hbthread.start()
		self._ssthread.start()
		self._dpthread.start()

		# initialize calibration
		self.calibration = calibration(self._connection)

	def start_recording(self):

		"""Starts data recording
		"""

		# set self._logdata to True, so the data processing thread starts
		# writing samples to the log file
		if not self._logdata:
			self._logdata = True
			self.log_message("start_recording")

	def stop_recording(self):

		"""Stops data recording
		"""

		# consolidate the data file on the hard drive
		# internal buffer to RAM
		self._logfile.flush()
		# RAM file cache to disk
		os.fsync(self._logfile.fileno())

		# set self._logdata to False, so the data processing thread does not
		# write samples to the log file
		if self._logdata:
			self.log_message("stop_recording")
			self._logdata = False

	def log_message(self, message):

		"""Logs a message to the logfile, time locked to the most recent
		sample
		"""
		
		# Get the current time.
		t = time.time()
		# Make a string in the specific format that the EyeTribe uses:
		# yyyy-mm-dd HH:MM:SS.000
		ts = '%s.%d' % (time.strftime('%Y-%m-%d %H:%M:%S'), round(t % 1, 3)*1000)
		
		# Correct the time to EyeTribe time
		if self._clockdiff != None:
			t = int(t + self._clockdiff)
		else:
			t = ''
		# assemble line
		line = self._separator.join(map(str,[u'MSG', ts, t, safe_decode(message)]))
		# write message
		self._logfile.write(line + u'\n') # to internal buffer

	def sample(self):

		"""Returns the most recent point of regard (=gaze location on screen)
		coordinates (smoothed signal)

		arguments

		None

		returns

		gaze		--	a (x,y) tuple indicating the point of regard
		"""

		if self._newestframe == None:
			return None, None
		else:
			return (self._newestframe['avgx'],self._newestframe['avgy'])

	def pupil_size(self):

		"""Returns the most recent pupil size sample (an average of the size
		of both pupils)

		arguments

		None

		returns

		pupsize	--	a float indicating the pupil size (in arbitrary units)
		"""

		if self._currentsample == None:
			return None
		else:
			return self._newestframe['psize']

	def close(self):

		"""Stops all data streaming, and closes both the connection to the
		tracker and the logfile
		"""

		# if we are currently recording, stop doing so
		if self._logdata:
			self.stop_recording()

		# signal all threads to halt
		self._beating = False
		self._streaming = False
		self._processing = False

		# close the log file
		self._logfile.close()

		# close the connection
		self._connection.close()

	def _wait_while_calibrating(self):

		"""Waits until the tracker is not in the calibration state
		"""

		while self._tracker.get_iscalibrating():
			pass

		return True

	def _heartbeater(self, heartbeatinterval):

		"""Continuously sends heartbeats to the tracker, to let it know the
		connection is still alive (it seems to think we could die any
		moment now, and is very keen on reassurance of our good health;
		almost like my grandparents...)

		arguments

		heartbeatinterval	--	float indicating the heartbeatinterval in
							seconds; note that this is different from
							the value that the EyeTribe tracker reports:
							that value is in milliseconds and should be
							recalculated to seconds here!
		"""

		# keep beating until it is signalled that we should stop
		while self._beating:
			# do not bother the tracker when it is calibrating
			#self._wait_while_calibrating()
			# wait for the Threading Lock to be released, then lock it
			self._lock.acquire(True)
			# send heartbeat
			self._heartbeat.beat()
			# release the Threading Lock
			self._lock.release()
			# wait for a bit
			time.sleep(heartbeatinterval)

	def _stream_samples(self, queue):

		"""Continuously polls the device, and puts all new samples in a
		Queue instance

		arguments

		queue		--	a multithreading.Queue instance, to put samples
						into
		"""

		# keep streaming until it is signalled that we should stop
		while self._streaming:
			# do not bother the tracker when it is calibrating
			#self._wait_while_calibrating()
			# wait for the Threading Lock to be released, then lock it
			self._lock.acquire(True)
			# get a new sample
			sample = self._tracker.get_frame()
			t1 = time.time()
			# put the sample in the Queue
			queue.put(sample)
			# release the Threading Lock
			self._lock.release()
			# Update the newest frame
			self._newestframe = copy.deepcopy(sample)
			# Calculate the clock difference
			self._clockdiff = sample['time'] - t1
			# pause for half the intersample time, to avoid an overflow
			# (but to make sure to not miss any samples)
			time.sleep(self._intsampletime/2)

	def _process_samples(self, queue):

		"""Continuously processes samples, updating the most recent sample
		and writing data to a the log file when self._logdata is set to True

		arguments

		queue		--	a multithreading.Queue instance, to read samples
						from
		"""

		# keep processing until it is signalled that we should stop
		while self._processing:
			# wait for the Threading Lock to be released, then lock it
			self._lock.acquire(True)
			# read new item from the queue
			if not queue.empty():
				sample = queue.get()
			else:
				sample = None
			# release the Threading Lock
			self._lock.release()
			# update newest sample
			if sample != None:
				# check if the new sample is the same as the current sample
				if not self._currentsample['timestamp'] == sample['timestamp']:
					# update current sample
					self._currentsample = copy.deepcopy(sample)
					# write to file if data logging is on
					if self._logdata:
						self._log_sample(sample)

	def _log_sample(self, sample):

		"""Writes a sample to the log file

		arguments

		sample		--	a sample dict, as is returned by
						tracker.get_frame
		"""

		# assemble new line
		line = self._separator.join(map(str,[	sample['timestamp'],
										sample['time'],
										sample['fix'],
										sample['state'],
										sample['rawx'],
										sample['rawy'],
										sample['avgx'],
										sample['avgy'],
										sample['psize'],
										sample['Lrawx'],
										sample['Lrawy'],
										sample['Lavgx'],
										sample['Lavgy'],
										sample['Lpsize'],
										sample['Lpupilx'],
										sample['Lpupily'],
										sample['Rrawx'],
										sample['Rrawy'],
										sample['Ravgx'],
										sample['Ravgy'],
										sample['Rpsize'],
										sample['Rpupilx'],
										sample['Rpupily']
								]))
		# write line to log file
		self._logfile.write(line + '\n') # to internal buffer

	def _log_header(self):

		"""Logs a header to the data file
		"""

		# write a header to the data file
		header = self._separator.join(['timestamp','time','fix','state',
								'rawx','rawy','avgx','avgy','psize',
								'Lrawx','Lrawy','Lavgx','Lavgy','Lpsize','Lpupilx','Lpupily',
								'Rrawx','Rrawy','Ravgx','Ravgy','Rpsize','Rpupilx','Rpupily'
								])
		self._logfile.write(header + '\n') # to internal buffer
		self._logfile.flush() # internal buffer to RAM
		os.fsync(self._logfile.fileno()) # RAM file cache to disk
		self._firstlog = False



# # # # # #
# PARALLEL ClASS


# Ugly, but sod it: A global variable for the most recent sample.
global _current_sample


# Class to communicate with an EyeTribe tracker. The actual communications
# and logging actually run in a separate Process. This class just sends
# commands to that Process.
class ParallelEyeTribe:
	
	def __init__(self, logfilename='default'):
		
		# Set some standard stuff (hard coded now, but can potentially
		# be passed to the __init__ method in the future.)
		host = 'localhost'
		port = 6555
		
		# We need an Event that signals whether the connection to the
		# EyeTribe is supposed to be open.
		self._connection_alive = Event()
		self._connection_alive.set()
		
		# We also need a Queue to send commands through.
		self._command_queue = Queue()
		# And we need a Queue to receive commands through.
		self._to_main_queue = Queue()
		
		# Start a parallel process that will take care of all EyeTribe
		# things. It will provide regular heartbeats to keep the connection
		# alive, it will record gaze data to a file, and it will keep the
		# most recent sample updated. This is all done in a separate
		# Process (rather than in Threads) to so that it can be offloaded
		# to a different CPU core. This prevents the ongoing experiment
		# (or whatever you're doing in the main Thread) from interfering
		# with the processing (and recording) of gaze data.
		self.eyetribe_process = Process(target=_run_eyetribe_process, \
			args=[logfilename, host, port, self._connection_alive, \
			self._command_queue])
		self.eyetribe_process.name = u'pygaze_eyetribe'
		self.eyetribe_process.daemon = True
		self.eyetribe_process.start()

	def start_recording(self):

		"""Starts data recording
		"""
		
		# Send a command to the EyeTribe Process
		self._command_queue.put(('start_recording', ()))

	def stop_recording(self):

		"""Stops data recording
		"""

		# Send a command to the EyeTribe Process
		self._command_queue.put(('stop_recording', ()))

	def log_message(self, message):

		"""Logs a message to the logfile, time locked to the most recent
		sample
		"""

		# Send a command to the EyeTribe Process
		self._command_queue.put(('log_message', (message)))

	def sample(self):

		"""Returns the most recent point of regard (=gaze location on screen)
		coordinates (smoothed signal)

		arguments

		None

		returns

		gaze		--	a (x,y) tuple indicating the point of regard
		"""
		
		global _current_sample
		
		if _current_sample == None:
			return None, None
		else:
			return (_current_sample['avgx'], _current_sample['avgy'])

	def pupil_size(self):

		"""Returns the most recent pupil size sample (an average of the size
		of both pupils)

		arguments

		None

		returns

		pupsize	--	a float indicating the pupil size (in arbitrary units)
		"""

		global _current_sample

		if _current_sample == None:
			return None
		else:
			return _current_sample['psize']

	def close(self):

		"""Stops all data streaming, and closes both the connection to the
		tracker and the logfile
		"""

		# Send a command to the EyeTribe Process
		self._command_queue.put(('close', ()))


# Function that can run in a parallel process, to keep a connection with the
# EyeTribe open, and to log data when appropriate.
def _run_eyetribe_process(logfilename, host, port, connection_alive, command_queue):
		
	"""FOR INTERNAL USE ONLY
	"""
	
	# Ugly, but sod it: A global variable for the most recent sample.
	global _current_sample
	
	# Initialise a new _EyeTribe instance to open the connection to the
	# EyeTribe.
	tracker = EyeTribe(logfilename=logfilename, host=host, port=port)
	
	# Run until the connection is closed.
	while connection_alive.is_set():
		
		# Check the incoming Queue.
		if not command_queue.empty():
			# Get the oldest command in the Queue. This is a tuple that
			# contains a string (the command), and a tuple of values
			# (what they are depends on the specific command).
			cmd, value = command_queue.get()
			
			# Start recording.
			if cmd == 'start_recording':
				tracker.start_recording()

			# Stop recording.
			elif cmd == 'stop_recording':
				tracker.stop_recording()

			# Log a message.
			elif cmd == 'log_message':
				tracker.log_message(value[0])

			# Close the connection to the EyeTribe.
			elif cmd == 'close':
				tracker.close()
				# Unset the Event that signals that the connection is
				# alive.
				connection_alive.clear()
		
		# Update the current sample.
		_current_sample = copy.deepcopy(tracker._currentsample)


# # # # #
# SUPPORTING CLASSES

class connection:

	"""class for connections with the EyeTribe tracker"""

	def __init__(self, host='localhost', port=6555):

		"""Initializes the connection with the EyeTribe tracker

		keyword arguments

		host		--	a string indicating the host IP, NOTE: currently only
					'localhost' is supported (default = 'localhost')
		port		--	an integer indicating the port number, NOTE: currently
					only 6555 is supported (default = 6555)
		"""

		# properties
		self.host = host
		self.port = port
		self.resplist = []
		self.DEBUG = False

		# initialize a connection
		self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
		self.sock.connect((self.host,self.port))
		# Create lock
		self._request_lock = Lock()

	def request(self, category, request, values):

		"""Send a message over the connection

		arguments

		category	--	string indicating the query category
		request	--	string indicating the actual request of the message
		values	--	dict or list containing parameters of the request
		"""

		# create a JSON formatted string
		msg = self.create_json(category, request, values)
		# send the message over the connection
		self._request_lock.acquire()
		self.sock.send(msg)
		# print request in DEBUG mode
		if self.DEBUG:
			print("REQUEST: '%s'" % msg)

		# give the tracker a wee bit of time to reply
		time.sleep(0.005)

		# get new responses
		success = self.get_response()
		self._request_lock.release()

		# return the appropriate response
		if success:
			for i in range(len(self.resplist)):
				# check if the category matches
				if self.resplist[i]['category'] == category:
					# if this is a heartbeat, return
					if self.resplist[i]['category'] == 'heartbeat':
						return self.resplist.pop(i)
					# if this is another category, check if the request
					# matches
					elif 'request' in self.resplist[i] and \
						self.resplist[i]['request'] == request:
						return self.resplist.pop(i)
		# on a connection error, get_response returns False and a connection
		# error should be returned
		else:
			return self.parse_json('{"statuscode":901,"values":{"statusmessage":"connection error"}}')

	def get_response(self):

		"""Asks for a response, and adds these to the list of all received
		responses (basically a very simple queue)
		"""

		# try to get a new response
		try:
			response = self.sock.recv(32768)
			# print reply in DEBUG mode
			if self.DEBUG:
				print("REPLY: '%s'" % response)
		# if it fails, revive the connection and return a connection error
		except socket.error:
			print("reviving connection")
			self.revive()
			response = '{"statuscode":901,"values":{"statusmessage":"connection error"}}'
			return False
		# split the responses (in case multiple came in)
		response = response.split('\n')
		# add parsed responses to the internal list
		for r in response:
			if r:
				self.resplist.append(self.parse_json(r))

		return True

	def create_json(self, category, request, values):

		"""Creates a new json message, in the format that is required by the
		EyeTribe tracker; these messages consist of a categort, a request and
		a (list of) value(s), which can be thought of as class.method.value
		(for more info, see: http://dev.theeyetribe.com/api/)

		arguments

		category	--	query category (string), e.g. 'tracker',
					'calibration', or 'heartbeat'
		request	--	the request message (string), e.g. 'get' for the
					'tracker' category
		values	--	a dict of parameters and their values, e.g.
					{"push":True, "version":1}
					OR:
					a list of parameters, e.g. ['push','iscalibrated']
					OR:
					None to pass no values at all

		keyword arguments

		None

		returns

		jsonmsg	--	a string in json format, that can be directly sent to
					the EyeTribe tracker
		"""

		# error if the values are anything other than a dict, tuple or list
		if values is not None and type(values) not in [dict, list, tuple]:
			raise Exception("values should be dict, tuple or list, not '%s' (values = %s)" % (type(values),values))

		# create the json message
		if request == None:
			jsondict = {"category":category}
		elif values == None:
			jsondict = {"category":category, "request":request}
		else:
			jsondict = {"category":category, "request":request, "values":values}

		return json.dumps(jsondict)

	def parse_json(self, jsonmsg):

		"""Parses a json message as those that are usually returned by the
		EyeTribe tracker
		(for more info, see: http://dev.theeyetribe.com/api/)

		arguments

		jsonmsg	--	a string in json format

		keyword arguments

		None

		returns

		msg		--	a dict containing the information in the json message;
					this dict has the following content:
						{	"category":	"tracker",
							"request":	"get",
							"statuscode":	200,
							"values":	{	"push":True,
										"iscalibrated":True
										}
							}
		"""

		# parse json message
		parsed = json.loads(jsonmsg)

		return parsed

	def revive(self):

		"""Re-establishes a connection
		"""

		# close old connection
		self.close()
		# initialize a connection
		self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
		self.sock.connect((self.host,self.port))


	def close(self):

		"""Closes the connection to the EyeTribe tracker
		"""

		# close the socket connection
		self.sock.close()


class tracker:

	"""class for SDK Tracker state and information related requests"""

	def __init__(self, connection):

		"""Initializes a tracker instance

		arguments

		connection	--	a pytribe.connection instance for the currently
						attached EyeTribe tracker
		"""

		self.connection = connection
		self.push = True

	def set_connection(self, connection):

		"""Set a new connection

		arguments

		connection	--	a pytribe.connection instance for the currently
						attached EyeTribe tracker
		"""

		self.connection = connection

	def get_push(self):

		"""Returns a Booleam reflecting the state: True for push mode,
		False for pull mode (Boolean)
		"""

		# send the request
		response = self.connection.request('tracker', 'get', ['push'])
		# return value or error
		if response['statuscode'] == 200:
			return response['values']['push']
		else:
			raise Exception("Error in tracker.get_push: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def get_heartbeatinterval(self):

		"""Returns the expected heartbeat interval in milliseconds
		(integer)
		"""

		# send the request
		response = self.connection.request('tracker', 'get', ['heartbeatinterval'])
		# check if the tracker is in push mode
		if response['statuscode'] == 200:
			return response['values']['heartbeatinterval']
		else:
			raise Exception("Error in tracker.get_heartbeatinterval: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def get_version(self):

		"""Returns the version number (integer)
		"""

		# send the request
		response = self.connection.request('tracker', 'get', ['version'])
		# return value or error
		if response['statuscode'] == 200:
			return response['values']['version']
		else:
			raise Exception("Error in tracker.get_version: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def get_trackerstate(self):

		"""Returns the state of the physcial tracker (integer):
			0:	TRACKER_CONNECTED
				tracker is detected and working
			1:	TRACKER_NOT_CONNECTED
				tracker device is not connected
			2:	TRACKER_CONNECTED_BADFW
				tracker device is connected, but not working due to
				bad firmware
			3:	TRACKER_CONNECTED_NOUSB3
				tracker device is connected, but not working due to
				unsupported USB host
			4:	TRACKER_CONNECTED_NOSTREAM
				tracker device is connected, but no stream could be
				received
		"""

		# send the request
		response = self.connection.request('tracker', 'get', ['trackerstate'])
		# return value of error
		if response['statuscode'] == 200:
			return response['values']['trackerstate']
		else:
			raise Exception("Error in tracker.get_trackerstate: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def get_framerate(self):

		"""Returns the frame rate that the tracker is running at (integer)
		"""

		# send the request
		response = self.connection.request('tracker', 'get', ['framerate'])
		# return value or error
		if response['statuscode'] == 200:
			return response['values']['framerate']
		else:
			raise Exception("Error in tracker.get_framerate: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def get_iscalibrated(self):

		"""Indicates whether there is a calibration (Boolean)
		"""

		# send the request
		response = self.connection.request('tracker', 'get', ['iscalibrated'])
		# return value or error
		if response['statuscode'] == 200:
			return response['values']['iscalibrated']
		else:
			raise Exception("Error in tracker.get_iscalibrated: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def get_iscalibrating(self):

		"""Indicates whether the tracker is in calibration mode (Boolean)
		"""

		# send the request
		response = self.connection.request('tracker', 'get', ['iscalibrating'])
		# return value or error
		if response['statuscode'] == 200:
			return response['values']['iscalibrating']
		else:
			raise Exception("Error in tracker.get_iscalibrating: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def get_calibresult(self):

		"""Gets the latest valid calibration result

		returns

		WITHOUT CALIBRATION:
		None

		WITH CALIBRATION:
		calibresults	--	a dict containing the calibration results:
						{	'result':	Boolean indicating whether the
									calibration was succesful
							'deg':	float indicating the average error
									in degrees of visual angle
							'Ldeg':	float indicating the left eye
									error in degrees of visual angle
							'Rdeg':	float indicating the right eye
									error in degrees of visual angle
							'calibpoints': list, containing a dict for
										each calibration point:
										{'state':	integer indicating
												the state of the
												calibration point
												(0 means no useful
												data has been
												obtained and the
												point should be
												resampled; 1 means
												the data is of
												questionable
												quality, consider
												resampling; 2 means
												the data is ok)
										'cpx':	x coordinate of the
												calibration point
										'cpy':	y coordinate of the
												calibration point
										'mecpx':	mean estimated x
												coordinate of the
												calibration point
										'mecpy':	mean estimated y
												coordinate of the
												calibration point
										'acd':	float indicating
												the accuracy in
												degrees of visual
												angle
										'Lacd':	float indicating
												the accuracy in
												degrees of visual
												angle (left eye)
										'Racd':	float indicating
												the accuracy in
												degrees of visual
												angle (right eye)
										'mepix':	mean error in
												pixels
										'Lmepix':	mean error in
												pixels (left eye)
										'Rmepix':	mean error in
												pixels (right eye)
										'asdp':	standard deviation
												in pixels
										'Lasdp':	standard deviation
												in pixels (left eye)
										'Rasdp':	standard deviation
												in pixels (right eye)
										}
						}

		"""

		# send the request
		response = self.connection.request('tracker', 'get', ['calibresult'])

		# return value or error
		if response['statuscode'] != 200:
			raise Exception("Error in tracker.get_calibresult: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

		# return True if this was not the final calibration point
		if not 'calibpoints' in response['values']:
			return None

		# if this was the final calibration point, return the results
		else:
			# return calibration dict
			returndict =  {	'result':response['values']['calibresult']['result'],
							'deg':response['values']['calibresult']['deg'],
							'Rdeg':response['values']['calibresult']['degl'],
							'Ldeg':response['values']['calibresult']['degr'],
							'calibpoints':[]
							}
			for pointdict in response['values']['calibresult']['calibpoints']:
				returndict['calibpoints'].append({	'state':pointdict['state'],
											'cpx':pointdict['cp']['x'],
											'cpy':pointdict['cp']['y'],
											'mecpx':pointdict['mecp']['x'],
											'mecpy':pointdict['mecp']['y'],
											'acd':pointdict['acd']['ad'],
											'Lacd':pointdict['acd']['adl'],
											'Racd':pointdict['acd']['adr'],
											'mepix':pointdict['mepix']['mep'],
											'Lmepix':pointdict['mepix']['mepl'],
											'Rmepix':pointdict['mepix']['mepr'],
											'asdp':pointdict['asdp']['asd'],
											'Lasdp':pointdict['asdp']['asdl'],
											'Rasdp':pointdict['asdp']['asdr']
											})
			return returndict

	def get_frame(self):

		"""Returns the latest frame data (dict)
			{	'timestamp': string time representation,
				'time': integer timestamp in milliseconds,
				'fix': Boolean indicating whether there is a fixation,
				'state': integer 32bit masked tracker state,
				'rawx': integer raw x gaze coordinate in pixels,
				'rawy': integer raw y gaze coordinate in pixels,
				'avgx': integer smoothed x gaze coordinate in pixels,
				'avgx': integer smoothed y gaze coordinate in pixels,
				'psize': float average pupil size,
				'Lrawx': integer raw x left eye gaze coordinate in pixels,
				'Lrawy': integer raw y left eye gaze coordinate in pixels,
				'Lavgx': integer smoothed x left eye gaze coordinate in pixels,
				'Lavgx': integer smoothed y left eye gaze coordinate in pixels,
				'Lpsize': float left eye pupil size,
				'Lpupilx': integer raw left eye pupil centre x coordinate,
				'Lpupily': integer raw left eye pupil centre y coordinate,
				'Rrawx': integer raw x right eye gaze coordinate in pixels,
				'Rrawy': integer raw y right eye gaze coordinate in pixels,
				'Ravgx': integer smoothed x right eye gaze coordinate in pixels,
				'Ravgx': integer smoothed y right eye gaze coordinate in pixels,
				'Rpsize': float right eye pupil size,
				'Rpupilx': integer raw right eye pupil centre x coordinate,
				'Rpupily': integer raw right eye pupil centre y coordinate
				}
		"""

		# send the request
		response = self.connection.request('tracker', 'get', ['frame'])
		# raise error if needed
		if response['statuscode'] != 200:
			raise Exception("Error in tracker.get_frame: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))
		# calculate pupil size
		# if both eyes are available, take the average
		if response['values']['frame']['lefteye']['psize'] > 0 and \
			response['values']['frame']['righteye']['psize'] > 0:
			psize = (response['values']['frame']['lefteye']['psize'] + \
				response['values']['frame']['righteye']['psize']) / 2.0
		# if only the right eye is available, then use the right eye
		elif response['values']['frame']['lefteye']['psize'] == 0 and \
			response['values']['frame']['righteye']['psize'] > 0:
			psize = response['values']['frame']['righteye']['psize']
		# if only the left eye is available, then use the left eye
		elif response['values']['frame']['lefteye']['psize'] > 0 and \
			response['values']['frame']['righteye']['psize'] == 0:
			psize = response['values']['frame']['lefteye']['psize']
		# if neither eye is available, then use the EyeTribe's standard
		# missing value (0.0)
		else:
			psize = 0.0
		# return the data in a dict
		return {	'timestamp':	response['values']['frame']['timestamp'],
				'time':		response['values']['frame']['time'],
				'fix':		response['values']['frame']['fix'],
				'state':		response['values']['frame']['state'],
				'rawx':		response['values']['frame']['raw']['x'],
				'rawy':		response['values']['frame']['raw']['y'],
				'avgx':		response['values']['frame']['avg']['x'],
				'avgy':		response['values']['frame']['avg']['y'],
				'psize':		psize,
				'Lrawx':		response['values']['frame']['lefteye']['raw']['x'],
				'Lrawy':		response['values']['frame']['lefteye']['raw']['y'],
				'Lavgx':		response['values']['frame']['lefteye']['avg']['x'],
				'Lavgy':		response['values']['frame']['lefteye']['avg']['y'],
				'Lpsize':		response['values']['frame']['lefteye']['psize'],
				'Lpupilx':		response['values']['frame']['lefteye']['pcenter']['x'],
				'Lpupily':		response['values']['frame']['lefteye']['pcenter']['y'],
				'Rrawx':		response['values']['frame']['righteye']['raw']['x'],
				'Rrawy':		response['values']['frame']['righteye']['raw']['y'],
				'Ravgx':		response['values']['frame']['righteye']['avg']['x'],
				'Ravgy':		response['values']['frame']['righteye']['avg']['y'],
				'Rpsize':		response['values']['frame']['righteye']['psize'],
				'Rpupilx':		response['values']['frame']['righteye']['pcenter']['x'],
				'Rpupily':		response['values']['frame']['righteye']['pcenter']['y']
				}

	def get_screenindex(self):

		"""Returns the screen index number in a multi screen setup (integer)
		"""

		# send the request
		response = self.connection.request('tracker', 'get', ['screenindex'])
		# return value or error
		if response['statuscode'] == 200:
			return response['values']['screenindex']
		else:
			raise Exception("Error in tracker.get_screenindex: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def get_screenresw(self):

		"""Returns the screen resolution width in pixels (integer)
		"""

		# send the request
		response = self.connection.request('tracker', 'get', ['screenresw'])
		# return value or error
		if response['statuscode'] == 200:
			return response['values']['screenresw']
		else:
			raise Exception("Error in tracker.get_screenresw: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def get_screenresh(self):

		"""Returns the screen resolution height in pixels (integer)
		"""

		# send the request
		response = self.connection.request('tracker', 'get', ['screenresh'])
		# return value or error
		if response['statuscode'] == 200:
			return response['values']['screenresh']
		else:
			raise Exception("Error in tracker.get_screenresh: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def get_screenpsyw(self):

		"""Returns the physical screen width in meters (float)
		"""

		# send the request
		response = self.connection.request('tracker', 'get', ['screenpsyw'])
		# return value or error
		if response['statuscode'] == 200:
			return response['values']['screenpsyw']
		else:
			raise Exception("Error in tracker.get_screenpsyw: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def get_screenpsyh(self):

		"""Returns the physical screen height in meters (float)
		"""

		# send the request
		response = self.connection.request('tracker', 'get', ['screenpsyh'])
		# return value or error
		if response['statuscode'] == 200:
			return response['values']['screenpsyh']
		else:
			raise Exception("Error in tracker.get_screenpsyh: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def set_push(self, push=None):

		"""Toggles the push state, or sets the state to the passed value

		keyword arguments

		push		--	Boolean indicating the state: True for push,
											False for pull
											None to toggle current
		returns

		state	--	Boolean indicating the push state
		"""

		# check passed value
		if push == None:
			# toggle state
			self.push = self.push != True
		elif type(push) == bool:
			# set state to passed value
			self.push = push
		else:
			# error on anything other than None, True or False
			raise Exception("tracker.set_push: push keyword argument should be a Boolean or None, not '%s'" % push)

		# send the request
		response = self.connection.request('tracker', 'set', {'push':str(self.push).lower()})
		# return value or error
		if response['statuscode'] == 200:
			return self.push
		else:
			raise Exception("Error in tracker.set_push: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))


	def set_version(self, version):

		"""Set the protocol version

		arguments

		version	--	integer version number
		"""

		# send the request
		response = self.connection.request('tracker', 'set', {'version':version})
		# return value or error
		if response['statuscode'] == 200:
			return version
		else:
			raise Exception("Error in tracker.set_version: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def set_screenindex(self, index):

		"""Set the screen index

		arguments

		index	--	integer value indicating the index number of the
					screen that is to be used with the tracker
		"""

		# send the request
		response = self.connection.request('tracker', 'set', {'screenindex':index})
		# return value or error
		if response['statuscode'] == 200:
			return index
		else:
			raise Exception("Error in tracker.set_screenindex: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def set_screenresw(self, width):

		"""Set the screen resolution width

		arguments

		width	--	integer value indicating the screen resolution width
					in pixels
		"""

		# send the request
		response = self.connection.request('tracker', 'set', {'screenresw':width})
		# return value or error
		if response['statuscode'] == 200:
			return width
		else:
			raise Exception("Error in tracker.set_screenresw: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def set_screenresh(self, height):

		"""Set the screen resolution height

		arguments

		height	--	integer value indicating the screen resolution height
					in pixels
		"""

		# send the request
		response = self.connection.request('tracker', 'set', {'screenresh':height})
		# return value or error
		if response['statuscode'] == 200:
			return height
		else:
			raise Exception("Error in tracker.set_screenresh: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def set_screenpsyw(self, width):

		"""Set the physical width of the screen

		arguments

		width	--	float value indicating the physical screen width in
					metres
		"""

		# send the request
		response = self.connection.request('tracker', 'set', {'screenpsyw':width})
		# return value or error
		if response['statuscode'] == 200:
			return width
		else:
			raise Exception("Error in tracker.set_screenpsyw: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def set_screenpsyh(self, height):

		"""Set the physical height of the screen

		arguments

		width	--	float value indicating the physical screen height in
					metres
		"""

		# send the request
		response = self.connection.request('tracker', 'set', {'screenpsyh':height})
		# return value or error
		if response['statuscode'] == 200:
			return height
		else:
			raise Exception("Error in tracker.set_screenpsyh: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))


class calibration:

	"""class for calibration related requests"""

	def __init__(self, connection):

		"""Initializes a calibration instance

		arguments

		connection	--	a pytribe.connection instance for the currently
						attached EyeTribe tracker
		"""

		self.connection = connection

	def set_connection(self, connection):

		"""Set a new connection

		arguments

		connection	--	a pytribe.connection instance for the currently
						attached EyeTribe tracker
		"""

		self.connection = connection

	def start(self, pointcount=9, max_attempts=5):

		"""Starts the calibration, using the passed number of calibration
		points

		keyword arguments

		pointcount	--	integer value indicating the amount of
						calibration points that should be used, which
						should be at least 7 (default = 9)
		max_attempts --	the number of times that calibration should be restarted
						if starting the calibration fails (default=5)
		"""
		
		for attempt in range(max_attempts):
		    # send the request
		    response = self.connection.request('calibration', 'start',
				{'pointcount':pointcount})
		    # return value or error
		    if response['statuscode'] == 200:
		        return
		    self.abort()
		raise Exception("Error in calibration.start: %s (code %d)" \
			% (response['values']['statusmessage'],response['statuscode']))		

	def pointstart(self, x, y):

		"""Mark the beginning of a new calibration point for the tracker to
		process

		arguments

		x			--	integer indicating the x coordinate of the
						calibration point
		y			--	integer indicating the y coordinate of the
						calibration point

		returns

		success		--	Boolean: True on success, False on a failure
		"""

		# send the request
		response = self.connection.request('calibration', 'pointstart', {'x':x,'y':y})
		# return value or error
		if response['statuscode'] == 200:
			return True
		else:
			raise Exception("Error in calibration.pointstart: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def pointend(self):

		"""Mark the end of processing a calibration point

		returns

		NORMALLY:
		success		--	Boolean: True on success, False on failure

		AFTER FINAL POINT:
		calibresults	--	a dict containing the calibration results:
						{	'result':	Boolean indicating whether the
									calibration was succesful
							'deg':	float indicating the average error
									in degrees of visual angle
							'Ldeg':	float indicating the left eye
									error in degrees of visual angle
							'Rdeg':	float indicating the right eye
									error in degrees of visual angle
							'calibpoints': list, containing a dict for
										each calibration point:
										{'state':	integer indicating
												the state of the
												calibration point
												(0 means no useful
												data has been
												obtained and the
												point should be
												resampled; 1 means
												the data is of
												questionable
												quality, consider
												resampling; 2 means
												the data is ok)
										'cpx':	x coordinate of the
												calibration point
										'cpy':	y coordinate of the
												calibration point
										'mecpx':	mean estimated x
												coordinate of the
												calibration point
										'mecpy':	mean estimated y
												coordinate of the
												calibration point
										'acd':	float indicating
												the accuracy in
												degrees of visual
												angle
										'Lacd':	float indicating
												the accuracy in
												degrees of visual
												angle (left eye)
										'Racd':	float indicating
												the accuracy in
												degrees of visual
												angle (right eye)
										'mepix':	mean error in
												pixels
										'Lmepix':	mean error in
												pixels (left eye)
										'Rmepix':	mean error in
												pixels (right eye)
										'asdp':	standard deviation
												in pixels
										'Lasdp':	standard deviation
												in pixels (left eye)
										'Rasdp':	standard deviation
												in pixels (right eye)
										}
						}
		"""

		# send the request
		response = self.connection.request('calibration', 'pointend', None)
		# return value or error
		if response['statuscode'] != 200:
			raise Exception("Error in calibration.pointend: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

		# return True if this was not the final calibration point
		if not 'calibresult' in response['values']:
			return True

		# if this was the final calibration point, return the results
		else:
			# return calibration dict
			returndict =  {	'result':response['values']['calibresult']['result'],
							'deg':response['values']['calibresult']['deg'],
							'Rdeg':response['values']['calibresult']['degl'],
							'Ldeg':response['values']['calibresult']['degr'],
							'calibpoints':[]
							}
			for pointdict in response['values']['calibresult']['calibpoints']:
				returndict['calibpoints'].append({	'state':pointdict['state'],
											'cpx':pointdict['cp']['x'],
											'cpy':pointdict['cp']['y'],
											'mecpx':pointdict['mecp']['x'],
											'mecpy':pointdict['mecp']['y'],
											'acd':pointdict['acd']['ad'],
											'Lacd':pointdict['acd']['adl'],
											'Racd':pointdict['acd']['adr'],
											'mepix':pointdict['mepix']['mep'],
											'Lmepix':pointdict['mepix']['mepl'],
											'Rmepix':pointdict['mepix']['mepr'],
											'asdp':pointdict['asdp']['asd'],
											'Lasdp':pointdict['asdp']['asdl'],
											'Rasdp':pointdict['asdp']['asdr']
											})
			return returndict

	def abort(self):

		"""Cancels the ongoing sequence and reinstates the previous
		calibration (only if there is one!)

		returns

		success		--	Boolean: True on success, False on failure
		"""

		# send the request
		response = self.connection.request('calibration', 'abort', None)
		# return value or error
		if response['statuscode'] == 200:
			return True
		else:
			raise Exception("Error in calibration.abort: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))

	def clear(self):

		"""Removes the current calibration from the tracker

		returns

		success		--	Boolean: True on success, False on failure
		"""

		# send the request
		response = self.connection.request('calibration', 'clear', None)
		# return value or error
		if response['statuscode'] == 200:
			return True
		else:
			raise Exception("Error in calibration.clear: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))


class heartbeat:

	"""class for signalling heartbeats to the server"""

	def __init__(self, connection):

		"""Initializes a heartbeat instance (not implemented in the SDK yet)

		arguments

		connection	--	a pytribe.connection instance for the currently
						attached EyeTribe tracker
		"""

		self.connection = connection

	def set_connection(self, connection):

		"""Set a new connection

		arguments

		connection	--	a pytribe.connection instance for the currently
						attached EyeTribe tracker
		"""

		self.connection = connection

	def beat(self):

		"""Sends a heartbeat to the device
		"""

		# send the request
		response = self.connection.request('heartbeat', None, None)
		# return value or error
		if response['statuscode'] == 200:
			return True
		else:
			raise Exception("Error in heartbeat.beat: %s (code %d)" % (response['values']['statusmessage'],response['statuscode']))


# # # # #
# DEBUG #
if __name__ == "__main__":
	test = EyeTribe()
	test.start_recording()
	time.sleep(10)
	test.stop_recording()
	test.close()
# # # # #