(self, logfile=u'default', facedetect=True, eyedetect=True, \
		pupthreshold=50, glintthreshold=200, glintdetect=True, \
		pupsizemode=u'diameter', minfacesize=(30,30), Lexpect=(0.7,0.4), \
		Rexpect=(0.3,0.4), maxpupdist=0.2, maxpupsize=0.3, maxcpu=6, \
		**kwargs)
Initialises an EyeTracker class.
		
		Keyword Arguments
		
		logfile		-	A string that indicates the path to the log
						file. An extension will be added
						automatically. Default = 'default'.
		
		facedetect		-	A Boolean that indicates whether face
						detection should be attempted before further
						processing (eye detection, and pupil/glint
						detection). Set this to False if you will
						be using the EyeTracker from close to an
						eye, in which cases faces need and could not
						be detected. Default = True.
		
		pupthreshold	-	An integer that indicates what the highest
						luminance value is that is still considered
						to be part of the pupil. This value needs to
						be between 0 and 255. Default = 50.
		
		glintthreshold	-	An integer that indicates what the lowest
						luminance value is that is still considered
						to be part of the glint. This value needs to
						be between 0 and 255. Default = 200.
		
		glintdetect		-	A Boolean that indicates whether the glint
						(the corneal reflection) should also be
						detected. Default = True.
		
		pupsizemode		-	A string that indicates how the pupil size
						should be reported.
						'diameter' reports the width of the rect in
						which the thresholded pupil fits.
						'surface' reports the number of thresholded
						pixels that are assumed to be the pupil.
		
		minfacesize		-	A (w,h) tuple that indicates what size a
						face should minimally be. Default = (30,30)
		
		Lexpect		-	A (x,y) tuple that indicates where the left
						eye is expected to be. Note that the
						coordinates are in relative space, where
						(0,0) is the top-left of the image, (0,1)
						is the bottom-left, and (1,1) is the
						bottom-right. Also note that the left eye is
						likely to be on the right side of the image,
						and the right eye is likely to be in the
						left part of the image. Default = (0.7,0.4)
		
		Rexpect		-	A (x,y) tuple that indicates where the right
						eye is expected to be. Note that the
						coordinates are in relative space, where
						(0,0) is the top-left of the image, (0,1)
						is the bottom-left, and (1,1) is the
						bottom-right. Also note that the left eye is
						likely to be on the right side of the image,
						and the right eye is likely to be in the
						left part of the image. Default = (0.3,0.4)
		
		maxpupdist		-	A float that indicates what the maximal
						allowable distance is between the expected
						eye position, and the position of detected
						potential eye. The maximal distance is
						defined as a proportion of the image height.
						It can also be set to None. Default = (0.2)
		
		maxpupsize		-	A float that indicates what the maximal
						allowable width is of the detected eyes. The
						maximal size is defined as a proportion of
						the image width. It can also be set to None.
						Default = (0.3)

		maxcpu		-	Integer indicating the maximum amount of
						parallel processes that will be doing all
						of the image processing. This happens in
						parallel to speed things up; the processing
						time on one CPU can't keep up with the
						camera's sampling rate. Default = 6.
Initialises an EyeTracker class.
		
		Keyword Arguments
		
		logfile		-	A string that indicates the path to the log
						file. An extension will be added
						automatically. Default = 'default'.
		
		facedetect		-	A Boolean that indicates whether face
						detection should be attempted before further
						processing (eye detection, and pupil/glint
						detection). Set this to False if you will
						be using the EyeTracker from close to an
						eye, in which cases faces need and could not
						be detected. Default = True.
		
		pupthreshold	-	An integer that indicates what the highest
						luminance value is that is still considered
						to be part of the pupil. This value needs to
						be between 0 and 255. Default = 50.
		
		glintthreshold	-	An integer that indicates what the lowest
						luminance value is that is still considered
						to be part of the glint. This value needs to
						be between 0 and 255. Default = 200.
		
		glintdetect		-	A Boolean that indicates whether the glint
						(the corneal reflection) should also be
						detected. Default = True.
		
		pupsizemode		-	A string that indicates how the pupil size
						should be reported.
						'diameter' reports the width of the rect in
						which the thresholded pupil fits.
						'surface' reports the number of thresholded
						pixels that are assumed to be the pupil.
		
		minfacesize		-	A (w,h) tuple that indicates what size a
						face should minimally be. Default = (30,30)
		
		Lexpect		-	A (x,y) tuple that indicates where the left
						eye is expected to be. Note that the
						coordinates are in relative space, where
						(0,0) is the top-left of the image, (0,1)
						is the bottom-left, and (1,1) is the
						bottom-right. Also note that the left eye is
						likely to be on the right side of the image,
						and the right eye is likely to be in the
						left part of the image. Default = (0.7,0.4)
		
		Rexpect		-	A (x,y) tuple that indicates where the right
						eye is expected to be. Note that the
						coordinates are in relative space, where
						(0,0) is the top-left of the image, (0,1)
						is the bottom-left, and (1,1) is the
						bottom-right. Also note that the left eye is
						likely to be on the right side of the image,
						and the right eye is likely to be in the
						left part of the image. Default = (0.3,0.4)
		
		maxpupdist		-	A float that indicates what the maximal
						allowable distance is between the expected
						eye position, and the position of detected
						potential eye. The maximal distance is
						defined as a proportion of the image height.
						It can also be set to None. Default = (0.2)
		
		maxpupsize		-	A float that indicates what the maximal
						allowable width is of the detected eyes. The
						maximal size is defined as a proportion of
						the image width. It can also be set to None.
						Default = (0.3)
Initialises an EyeTracker class . Keyword Arguments logfile - A string that indicates the path to the log file . An extension will be added automatically . Default = default . facedetect - A Boolean that indicates whether face detection should be attempted before further processing ( eye detection and pupil / glint detection ) . Set this to False if you will be using the EyeTracker from close to an eye in which cases faces need and could not be detected . Default = True . pupthreshold - An integer that indicates what the highest luminance value is that is still considered to be part of the pupil . This value needs to be between 0 and 255 . Default = 50 . glintthreshold - An integer that indicates what the lowest luminance value is that is still considered to be part of the glint . This value needs to be between 0 and 255 . Default = 200 . glintdetect - A Boolean that indicates whether the glint ( the corneal reflection ) should also be detected . Default = True . pupsizemode - A string that indicates how the pupil size should be reported . diameter reports the width of the rect in which the thresholded pupil fits . surface reports the number of thresholded pixels that are assumed to be the pupil . minfacesize - A ( w h ) tuple that indicates what size a face should minimally be . Default = ( 30 30 ) Lexpect - A ( x y ) tuple that indicates where the left eye is expected to be . Note that the coordinates are in relative space where ( 0 0 ) is the top - left of the image ( 0 1 ) is the bottom - left and ( 1 1 ) is the bottom - right . Also note that the left eye is likely to be on the right side of the image and the right eye is likely to be in the left part of the image . Default = ( 0 . 7 0 . 4 ) Rexpect - A ( x y ) tuple that indicates where the right eye is expected to be . Note that the coordinates are in relative space where ( 0 0 ) is the top - left of the image ( 0 1 ) is the bottom - left and ( 1 1 ) is the bottom - right . Also note that the left eye is likely to be on the right side of the image and the right eye is likely to be in the left part of the image . Default = ( 0 . 3 0 . 4 ) maxpupdist - A float that indicates what the maximal allowable distance is between the expected eye position and the position of detected potential eye . The maximal distance is defined as a proportion of the image height . It can also be set to None . Default = ( 0 . 2 ) maxpupsize - A float that indicates what the maximal allowable width is of the detected eyes . The maximal size is defined as a proportion of the image width . It can also be set to None . Default = ( 0 . 3 )
def __init__(self, logfile=u'default', facedetect=True, eyedetect=True, \
		pupthreshold=50, glintthreshold=200, glintdetect=True, \
		pupsizemode=u'diameter', minfacesize=(30,30), Lexpect=(0.7,0.4), \
		Rexpect=(0.3,0.4), maxpupdist=0.2, maxpupsize=0.3, maxcpu=6, \
		**kwargs):
		
		"""Initialises an EyeTracker class.
		
		Keyword Arguments
		
		logfile		-	A string that indicates the path to the log
						file. An extension will be added
						automatically. Default = 'default'.
		
		facedetect		-	A Boolean that indicates whether face
						detection should be attempted before further
						processing (eye detection, and pupil/glint
						detection). Set this to False if you will
						be using the EyeTracker from close to an
						eye, in which cases faces need and could not
						be detected. Default = True.
		
		pupthreshold	-	An integer that indicates what the highest
						luminance value is that is still considered
						to be part of the pupil. This value needs to
						be between 0 and 255. Default = 50.
		
		glintthreshold	-	An integer that indicates what the lowest
						luminance value is that is still considered
						to be part of the glint. This value needs to
						be between 0 and 255. Default = 200.
		
		glintdetect		-	A Boolean that indicates whether the glint
						(the corneal reflection) should also be
						detected. Default = True.
		
		pupsizemode		-	A string that indicates how the pupil size
						should be reported.
						'diameter' reports the width of the rect in
						which the thresholded pupil fits.
						'surface' reports the number of thresholded
						pixels that are assumed to be the pupil.
		
		minfacesize		-	A (w,h) tuple that indicates what size a
						face should minimally be. Default = (30,30)
		
		Lexpect		-	A (x,y) tuple that indicates where the left
						eye is expected to be. Note that the
						coordinates are in relative space, where
						(0,0) is the top-left of the image, (0,1)
						is the bottom-left, and (1,1) is the
						bottom-right. Also note that the left eye is
						likely to be on the right side of the image,
						and the right eye is likely to be in the
						left part of the image. Default = (0.7,0.4)
		
		Rexpect		-	A (x,y) tuple that indicates where the right
						eye is expected to be. Note that the
						coordinates are in relative space, where
						(0,0) is the top-left of the image, (0,1)
						is the bottom-left, and (1,1) is the
						bottom-right. Also note that the left eye is
						likely to be on the right side of the image,
						and the right eye is likely to be in the
						left part of the image. Default = (0.3,0.4)
		
		maxpupdist		-	A float that indicates what the maximal
						allowable distance is between the expected
						eye position, and the position of detected
						potential eye. The maximal distance is
						defined as a proportion of the image height.
						It can also be set to None. Default = (0.2)
		
		maxpupsize		-	A float that indicates what the maximal
						allowable width is of the detected eyes. The
						maximal size is defined as a proportion of
						the image width. It can also be set to None.
						Default = (0.3)

		maxcpu		-	Integer indicating the maximum amount of
						parallel processes that will be doing all
						of the image processing. This happens in
						parallel to speed things up; the processing
						time on one CPU can't keep up with the
						camera's sampling rate. Default = 6.
		"""

		# DEBUG message.
		_message(u'debug', u'generic.EyeTracker.__init__', \
			u"Initialising a new EyeTracker.")
		
		# GENERAL SETTINGS
		# Face detection yes/no, and from what size.
		self._facedetect = facedetect
		self._minfacesize = minfacesize
		# Face eye yes/no.
		self._eyedetect = eyedetect
		# Eye detection settings. These are relative positions of where
		# each eye is expected to be in a frame, how far away detected eyes
		# are allowed to be from the expected locations, and how large the
		# detected eyes are allowed to be. (All defined as proportions of
		# the frame's width and height.)
		self._Lexpect = Lexpect
		self._Rexpect = Rexpect
		self._maxpupdist = maxpupdist
		self._maxpupsize = maxpupsize
		# Pupil detection thresholds (dark for pupil, bright for glint),
		# and additional options that determine whether glints should be
		# detected, and how the pupil size should be reported.
		self._pupt = pupthreshold
		self._glit = glintthreshold
		self._glintdetect = glintdetect
		self._pupsizemode = pupsizemode
		
		# ALIVE EVENT
		# This event signals whether the tracker is still alive. It should
		# only be cleared when closing the connection to the tracker!
		self._alive = Event()
		self._alive.set()
		
		# FRAME OBTAINING THREAD
		# Boolean that turns to True when a connection with the source of
		# frames has been established.
		self._connected = False
		# We need a Queue for frames that are generated in the obtainer
		# Thread. The Queue is read out by the parallel processes.
		self._framequeue = Queue()
		# We need a lock to prevent potential simultaneous attempts to
		# access the image source at the same time. This shouldn't actually
		# be possible in the current implementation, but may be added in
		# the future.
		self._sourcelock = Lock()
		# Start the frame obtaining Thread
		_message(u'debug', u'generic.EyeTracker.__init__', \
			u"Starting a Thread to obtain frames.")
		self._frame_obtainer_thread = Thread(target=self._frame_obtainer, \
			args=[self._alive, self._framequeue])
		self._frame_obtainer_thread.name = u'frame_obtainer'
		self._frame_obtainer_thread.daemon = True
		self._frame_obtainer_thread.start()

		# PARALLEL PROCESSING
		# We need a Queue for samples that are generated in the parallel
		# processes that are simultaneously processing new frames.
		self._samplequeue = Queue()
		# Check how many CPUs we can use.
		cpus = cpu_count()
		if cpus > maxcpu:
			cpus = maxcpu
		# Start parallel processes to do image processing.
		_message(u'debug', u'generic.EyeTracker.__init__', \
			u"Starting %d parallel processes to process frames into samples." \
			% (cpus-1))
		self._frame_processes = []
		for i in range(1, cpus):
			p = Process(target=_frame_processer, \
				args=[self._alive, self._framequeue, self._samplequeue, \
				self._pupt, self._glit, self._facedetect, self._eyedetect, \
				self._minfacesize, self._Lexpect, self._Rexpect, \
				self._maxpupdist, self._maxpupsize, self._glintdetect, \
				self._pupsizemode])
			p.name = u'frame_processor_%d' % (i)
			p.daemon = True
			p.start()
			self._frame_processes.append(p)
		
		# SAMPLE WRITING
		# Variable that keeps track of the latest sample.
		self._latest_sample = [0, numpy.zeros((2,5))*numpy.NaN]
		# Boolean that signals whether the recording Thread should be
		# active or not.
		self._recording = False
		# Lock to prevent simultaneous access to the log file.
		self._loglock = Lock()
		# The log file is an open text file. It will be opened when
		# self._start_recording is called, and it will be closed when
		# self._stop_recording is called. Between calling those two
		# functions, samples will be appended to the log. To prevent
		# samples from being appended to an existing log file, here we
		# open a new logfile with in 'w' mode, thereby erasing any existing
		# content of a previous log file. This means users need to be
		# careful when naming their files, to prevent overwriting.
		self._logfilename = u'%s.tsv' % (logfile)
		_message(u'debug', u'generic.EyeTracker.__init__', \
			u"Creating new logfile '%s'." \
			% (self._logfilename))
		# Create a header for the log file.
		l = [u'time']
		l.extend([u'Lpx', u'Lpy', u'Lps', u'Lgx', u'Lgy'])
		l.extend([u'Rpx', u'Rpy', u'Rps', u'Rgx', u'Rgy'])
		line = u'\t'.join(map(unicode, l)) + u'\n'
		# Create a new log file.
		self._loglock.acquire(True)
		self._logfile = open(self._logfilename, u'w')
		self._logfile.write(line)
		self._logfile.close()
		self._loglock.release()

		# Start the sample logging Thread
		_message(u'debug', u'generic.EyeTracker.__init__', \
			u"Starting a Thread to log samples to file '%s'." \
			% (self._logfilename))
		self._sample_logging_thread = Thread(target=self._sample_logger, \
			args=[self._alive, self._samplequeue])
		self._sample_logging_thread.name = u'sample_logger'
		self._sample_logging_thread.daemon = True
		self._sample_logging_thread.start()
		
		# CUSTOM INITIALISATION
		# Run the custom initialisation procedure.
		self.connect(**kwargs)
def __init__ ( self , logfile = u'default' , facedetect = True , eyedetect = True , pupthreshold = 50 , glintthreshold = 200 , glintdetect = True , pupsizemode = u'diameter' , minfacesize = ( 30 , 30 ) , Lexpect = ( 0.7 , 0.4 ) , Rexpect = ( 0.3 , 0.4 ) , maxpupdist = 0.2 , maxpupsize = 0.3 , maxcpu = 6 , * * kwargs ) : # DEBUG message. _message ( u'debug' , u'generic.EyeTracker.__init__' , u"Initialising a new EyeTracker." ) # GENERAL SETTINGS # Face detection yes/no, and from what size. self . _facedetect = facedetect self . _minfacesize = minfacesize # Face eye yes/no. self . _eyedetect = eyedetect # Eye detection settings. These are relative positions of where # each eye is expected to be in a frame, how far away detected eyes # are allowed to be from the expected locations, and how large the # detected eyes are allowed to be. (All defined as proportions of # the frame's width and height.) self . _Lexpect = Lexpect self . _Rexpect = Rexpect self . _maxpupdist = maxpupdist self . _maxpupsize = maxpupsize # Pupil detection thresholds (dark for pupil, bright for glint), # and additional options that determine whether glints should be # detected, and how the pupil size should be reported. self . _pupt = pupthreshold self . _glit = glintthreshold self . _glintdetect = glintdetect self . _pupsizemode = pupsizemode # ALIVE EVENT # This event signals whether the tracker is still alive. It should # only be cleared when closing the connection to the tracker! self . _alive = Event ( ) self . _alive . set ( ) # FRAME OBTAINING THREAD # Boolean that turns to True when a connection with the source of # frames has been established. self . _connected = False # We need a Queue for frames that are generated in the obtainer # Thread. The Queue is read out by the parallel processes. self . _framequeue = Queue ( ) # We need a lock to prevent potential simultaneous attempts to # access the image source at the same time. This shouldn't actually # be possible in the current implementation, but may be added in # the future. self . _sourcelock = Lock ( ) # Start the frame obtaining Thread _message ( u'debug' , u'generic.EyeTracker.__init__' , u"Starting a Thread to obtain frames." ) self . _frame_obtainer_thread = Thread ( target = self . _frame_obtainer , args = [ self . _alive , self . _framequeue ] ) self . _frame_obtainer_thread . name = u'frame_obtainer' self . _frame_obtainer_thread . daemon = True self . _frame_obtainer_thread . start ( ) # PARALLEL PROCESSING # We need a Queue for samples that are generated in the parallel # processes that are simultaneously processing new frames. self . _samplequeue = Queue ( ) # Check how many CPUs we can use. cpus = cpu_count ( ) if cpus > maxcpu : cpus = maxcpu # Start parallel processes to do image processing. _message ( u'debug' , u'generic.EyeTracker.__init__' , u"Starting %d parallel processes to process frames into samples." % ( cpus - 1 ) ) self . _frame_processes = [ ] for i in range ( 1 , cpus ) : p = Process ( target = _frame_processer , args = [ self . _alive , self . _framequeue , self . _samplequeue , self . _pupt , self . _glit , self . _facedetect , self . _eyedetect , self . _minfacesize , self . _Lexpect , self . _Rexpect , self . _maxpupdist , self . _maxpupsize , self . _glintdetect , self . _pupsizemode ] ) p . name = u'frame_processor_%d' % ( i ) p . daemon = True p . start ( ) self . _frame_processes . append ( p ) # SAMPLE WRITING # Variable that keeps track of the latest sample. self . _latest_sample = [ 0 , numpy . zeros ( ( 2 , 5 ) ) * numpy . NaN ] # Boolean that signals whether the recording Thread should be # active or not. self . _recording = False # Lock to prevent simultaneous access to the log file. self . _loglock = Lock ( ) # The log file is an open text file. It will be opened when # self._start_recording is called, and it will be closed when # self._stop_recording is called. Between calling those two # functions, samples will be appended to the log. To prevent # samples from being appended to an existing log file, here we # open a new logfile with in 'w' mode, thereby erasing any existing # content of a previous log file. This means users need to be # careful when naming their files, to prevent overwriting. self . _logfilename = u'%s.tsv' % ( logfile ) _message ( u'debug' , u'generic.EyeTracker.__init__' , u"Creating new logfile '%s'." % ( self . _logfilename ) ) # Create a header for the log file. l = [ u'time' ] l . extend ( [ u'Lpx' , u'Lpy' , u'Lps' , u'Lgx' , u'Lgy' ] ) l . extend ( [ u'Rpx' , u'Rpy' , u'Rps' , u'Rgx' , u'Rgy' ] ) line = u'\t' . join ( map ( unicode , l ) ) + u'\n' # Create a new log file. self . _loglock . acquire ( True ) self . _logfile = open ( self . _logfilename , u'w' ) self . _logfile . write ( line ) self . _logfile . close ( ) self . _loglock . release ( ) # Start the sample logging Thread _message ( u'debug' , u'generic.EyeTracker.__init__' , u"Starting a Thread to log samples to file '%s'." % ( self . _logfilename ) ) self . _sample_logging_thread = Thread ( target = self . _sample_logger , args = [ self . _alive , self . _samplequeue ] ) self . _sample_logging_thread . name = u'sample_logger' self . _sample_logging_thread . daemon = True self . _sample_logging_thread . start ( ) # CUSTOM INITIALISATION # Run the custom initialisation procedure. self . connect ( * * kwargs )