View source for EyeSeeCam SCI

[[File:EyeSeeCam_SCI2.png|thumb|EyeSeeCam SCI]]
==Description==
The EyeSeeCam SCI is a combined eye tracker and head movement tracker. The head tracking is done with an IMU and the eye tracking is done with cameras and software that tracks the pupils of both eyes. The tracking data can be read out with directly in Matlab. In case a dedicated computer is used for readout the EyeSeeCam, the data it is converted to an LSL stream. The EyeSeeCam Sci can record at 250 and and 500 Hz. We are typically recording at 500 Hz.

==Construction of a gaze trace==
The data from EyeSeeCam is recorded in different coordinate systems than the double polar system that we use to present our targets. The head and eye tracking data each have their own coordinate system. To accurately analyze our data we have to transform these coordinate systems to double polar coordinates in the lab frame. In order to relate the EyeSeeCam coordinates to the lab coordinates, we first need to record a starting gaze position for each trial. This means that during the recording, the subject has to look at the center speaker (0,0) when the trial starts. 

From the EyeSeeCam data we can construct a head movement trace and an eye movement trace. These can be combined to create a gaze trace.

===Defining a temporary lab coordinate system===

We will define the starting direction as the direction the subject looks at at the beginning of each trial. The recording of the data should start when the subject is looking in this direction. <br>
For the purpose of the interpretation of the EyeSeeCam data we define the lab coordinates as identical to the EyeSeeCam coordinates when looking in the starting direction (starting gaze):

* X = forward
* Y = left
* Z = upwards

In the corresponding matlab functions we will use these temporary lab coordinates to calculate the rotation of the gaze direction but convert it in the end to double polar coordinates.

===Head movement===
EyeSeeCam_Sci provides us angle velocities for rotations around the  X,Y, and Z axes. For our analyses we want to have position data, so we have to calculate the position data from these angle velocities.
 
The head rotation axis X, Y and Z are defined with respect to the EyeSeeCam itself. 

*''The EyeSeeCam data is '''not''' in the lab frame!''

The EyeSeeCam gives angle velocities for rotations around X, Y and Z axis. In order to create a head movement trace we have to calculate rotation matrices (delta_Rx, delta_Ry and delta_Rz) in EyeSeeCam coordinate for every time step. 

Since the time steps are about 2 ms the rotations for each time step are small. Therefore the order in which delta_Rx, delta_Ry and delta_Rz are multiplied are not important and we calculate delta_R(t) in EyeSeeCam coordinates by 
<pre>
delta_R(t) = delta_Rx * delta_Ry * delta_Rz.
</pre>

To get the total rotation matrix in lab coordinates at time t we have 
<pre>
R(t) = R(t-delta_t) * delta_R(t). 
</pre>

===Eye movement===

The eye movements are given by rotations in the oculomotor coordinate system (ocs).

* X = anterior (torsion of the pupil in the gaze direction)
* Y = superior 
* Z = right

The torsion is not important for the gaze direction and is therefore excluded from the calculation.

Azimuth can be defined as a rotation about the Z axis and Elevation as a contra rotation about the Y axis.

Since the eye gaze is given as a rotation angle in OCS coordinates and the eye and head tracker coordinate are fixed relative to each other, we can easily transform OCS coordinates to the EyeSeeCam coordinates. We can then create rotation matrices in the EyeSeeCam coordinates for the azimuth and elevation of the gaze. Since the torsion is excluded the rotation matrices for azimuth and elevation can be multiplied in any order to get the eye rotation matrix in EyeSeeCam coordinates.
<pre>
eye_Rz(t) = Rz(eye_azimuth(t))
eye_Ry(t) = Ry(-eye_elevation(t))
eye_R(t)  = eye_Ry(t) * eye_Rz(t)
</pre>

===Gaze movement===

The gaze movement is the combined head and eye movement.
To create the total rotation matrix that represents the 'gaze' rotation in lab coordinates, you need to multiply the two rotation matrices you have for head and eye movement in the correct order. In your case, you have:

A rotation matrix for the head in lab coordinates.
A rotation matrix for the eyes in head coordinates.
The correct order of multiplication is as follows:

First, multiply the rotation matrix of the head in lab coordinates by the rotation matrix of the eyes in head coordinates.
<pre>
R_gaze(t) = head_R(t) * eye_R(t)
</pre>

Lastly you can multiply the R_gaze(t) with the starting gaze vector to get the gaze (in lab coordinates) at time t. We assume that the starting gaze is in the forward direction, which is in the X direction in the lab coordinates.

<pre>
startingGaze = [1; 0; 0]
gaze(t) = R_gaze(t) * startingGaze
</pre>

==Matlab programming==

===Functions for converting EyeSeeCam data to double polar data===
There is one function for head movement, one for eye movement and one for gaze movement. The gaze movement combines head and eye movement.

The functions take head rotation speeds and eye rotations (in degrees) as input and give objects containing the traces (head, eye and gaze respectivily) in double polar coordinates as output.

* headTrace_DP = EyeSeeCamSciHeadRotationData2Trace_DP(Vx_deg, Vy_deg, Vz_deg)
* eyeTrace_DP  = EyeSeeCamSciEyeRotationData2Trace_DP(Zocs_deg, Yocs_deg)
* gazeTrace_DP = EyeSeeCamSciHeadAndEyeRotationData2Trace_DP(Vx_deg, Vy_deg, Vz_deg, Zocs_deg, Yocs_deg)

The Vx, Vy and Vz are the head rotation speeds in the EyeSeeCam coordinates
The Zocs and Yocs are the eye rotations in OCS coordinates.

===EyeSeeCam data===
The recorded data is read from an LSL stream.
<pre>
% todo: LSL streaming parameters
</pre>
The lsldata is a struct and has the following fields:
*escdata
*escmetadata
*escstr
*evdata0
*evdata1
*evdata2
*evdata3
*evdata4


The lsldata.escdata contains the eye and head data. The data contains a matrix for with a row for every parameter. The total of parameters is 63. The field lsldata.escmetadata.channel lists all the names of the parameters.


<pre>
%Eye data

RightEyePosX = 46;
RightEyePosY = 47;
RightEyePosZ = 48;

xeye = lsldata.escdata.Data(46,:);       % right 46, left 32
yeye = lsldata.escdata.Data(47,:);       % right 47, left 33
zeye = lsldata.escdata.Data(48,:);       % right 48, left 34

% Head data
HeadInertialVelXCal = 27;
HeadInertialVelYCal = 29;
HeadInertialVelZCal = 31;

xh = lsldata.escdata.Data(27,:);       % calibrated torion velocity data HEAD
yh = lsldata.escdata.Data(29,:);       % calibrated vertical velocity data HEAD
zh = lsldata.escdata.Data(31,:);       % calibrated horizontal velocity data HEAD
</pre>