Oculomatic Pro Setup and User Guide 4/19/2018 - rev 1.8.5 Contact Support: Email : support@ryklinsoftware.com Phone : 1-646-688-3667 (M-F 9:00am-6:00pm EST) Software Download (Requires USB License Dongle): FULL INSTALLTION (includes DAQ and Camera drivers) http://www.ryklinsoftware.com/downloads/oculomatic_pro_installation_with_drivers.exe Oculomatic Program Updates http://www.ryklinsoftware.com/downloads/oculomatic_pro_installation.exe 3 rd Party Analytics and Stimulus Presentation Software Hairball http://www.ryklinsoftware.com/downloads/hairball_installation.exe What s in the box: 1
Hardware Item List: 1. Camera and Lens packaged together 2. IR Emitter for illuminating the scene. Camera cannot see the eye without this. 3. Tripods for mounting camera and IR Emitter These can be replaced by other mounting hardware that fits your environment. 4. POE Injector connects camera to computer (power over ethernet). 5. USB Device for outputting the X,Y gaze signal to external devices. 6. Cables these include a power for the POE Injector, USB for the DAQ device, two network cables for connecting the camera, and a power cable for the IR Emitter. 7. USB License key dongle. Installation: 1) The below software components should be first installed for Oculomatic to work properly a) Sapera camera driver. b) Microsoft.Net Framework 4.5 c) USB Smart Dongle license key d) Microsoft 2013 and 2015 x64 Redistributable e) Optional Data Acquisitions drivers: 2
i) NIDAQmx or Measurement Computing (MCCDAQ / Instacal) are both supported. You must install the drivers separately. f) Oculomatic Pro Software can then run smoothly with full functionality 2) Connecting hardware: a) Plug in the USB License Dongle (back of the computer into a USB2 port works best). b) Remove camera/lens and securely mount on a camera tripod or arm. i) Connect the supplied ethernet cable, with screw down end on the back of the camera and the other end into the POE Injector. Blue light solid Screw down the cable ii) Make sure you connect the ethernet cable into the port labeled output on the POE injector. To Computer To Camera To Power iii) Connect a regular ethernet network cable from your computer s ethernet port (Gigabit) to the POE Injector s input. iv) Connect power cable to the POE injector and plug it into the electrical outlet. v) You may need to restart your computer to get the network card to reset its TCP/IP c) You can start Oculomatic Pro now. d) Remove IR Emitter and mount to the other tripod and connect power. e) Position the camera and IR Emitter so that they are both in from of the subject, approximately 60 cm away (typical range is 30-70cm which is about arm s length or less). You should see a video stream in the Oculomatic Pro software s camera window, but you will likely need to adjust the focus, aperture, and direction the camera is pointing in order to achieve an image as shown below in section 4. 3
f) Optionally, connect the DAQ Device to the USB Port and run BNC cables from the analog output 0,1 and 2 channels, to your data acquisition device. 3) Using the software a) The software will start with default settings similar to those shown above. b) Position the camera and IR emitter, and adjust the focus, so that you have a clear image of the eye as shown. c) Adjust the Pupil Threshold so that it is clearly discriminated from the sclera, iris, and eye lashes. d) Adjust the Pupil s max and min area to optimize tracking performance and properly normalize the pupil s diameter analysis. e) You are now ready to start eye tracking. 4) Configuring the camera type a) No configuration is necessary, the default camera is set to Sapera.dll however users have some options to choose from. b) Users can configure the camera type by editing the bin/data/settings.xml file Look for the following tags: Option 1 <Camera>Sapera.dll</Camera> Option 2 <Camera>PTGrey.dll</Camera> Option 3 <Camera>Video.mp4</Camera> If using a video instead of a camera 1. Place the file in the data folder. 2. Install the K-Lite_Codec (included in the full driver distribution) 4
5) Thresholding the image a) Any changes to the settings shown in user interface require you press the S key. This will overwrite the previous data\settings.xml file. Starting Oculomatic Pro will automatically load the previous settings. b) Most settings should be kept constant between experiments and only play a role during initial setup. You should not have to change Circularity, Convexity or Inertia for any setup and believe these settings should just be kept at their default state (a future release will likely remove them and have those ranges hard coded). c) Pupil threshold as well as Min and Max Area of the Pupil are the most important parameters. Make sure that the threshold is set correctly by verifying the thresholded image of the pupil shown to the left. d) Once you have confirmed that set a range for acceptable Pupil dimensions (Min and Max Area P) that works for your subject. Be sure to keep in mind the pupil diameter will change due to luminance changes of your stimulus display! Don t make this range too small and initially try what works best for you. When the cyan circle encloses the pupil, tracking started and analog outputs are sent. e) Because the pupil midpoint pixel location is arbitrary in regard to the analog output range of the DAQ device, it is essential to perform an initial midpoint calibration. This requires the subject to fixate on a central fixation point while the experimenter presses the X key. Gain can be independently altered for the horizontal and vertical position if needed. If the gain settings are altered a NEW midpoint must be calibrated as to not introduce nonlinear shifts in transformation. The usual approach is to keep the gain constant between experimental sessions and rather perform a 5 or 9-point 2D affine calibration in your experimental control software. This is very simple to do after you try it a few times. f) By default, there is no 2D affine transformation applied; the raw signal is output. g) To perform a 2D affine transformation you must implement your own stimulus presentation sequence, capture the gaze raw data, and either save it to this file or send it to Oculomatic via the SDK. We include a sample Matlab script and C++ program that demonstrates this. i) The affine transformation matrix is stored in a file called bin\calibration.txt, see the appendix below for more info on the file format. 6) Spatial Calibration a) To calibrate the eye tracker and improve spatial accuracy and precision you must ask the participant to look at some reference points (sometimes called control points). Typically, five (5) or nine (9) spots are shown on the screen, then the participant is asked to look at each one individually. When their gaze is stable, record this average gaze coordinate (normalized) for each reference point. b) Oculomatic Pro uses these reference values to transform the raw data. c) Users should calibrate at least four (4) reference locations (oblique corners of the visual field). d) There are two ways to send these values to Oculomatic Pro i) Using the format indicated below, create a file called calibration.txt that contains all of these values and place it into the Oculomatic Pro bin directory. For more information on the file format see Section 10 below. ii) Use the SDK to transmit the data to Oculomatic 5
(1) Using The C Programming language, first startcalibration(), then addcalibrationpoint(), and finally finishcalibration(). An example is given in the CalibrationApp.cpp file which comes included with the Oculomatic Pro software. The CalibrationApp is a complete open source example demonstrating how to render control points on the screen while sampling gaze position, recording and then transmitting to Oculomatic. (2) Using Matlab, the script : testcalibrateoculomatic.m demonstrates how to display the control points on the screen, sample from the eye tracker and record the gaze value, construct a calibration matrix and send it to Oculomatic. 7) Analog data output Oculomatic currently supports both Measurement Computing and National Instruments DAQ devices. We typically supply USB models, but you can use PCIe cards as well. The driver will automatically communicate with most any model. a) Users can configure the DAQ device by editing the bin/data/settings.xml file, which contains all the startup parameters. Look for the following tags: Option 1 <DAQ>MCCDAQ.dll</DAQ> <DAQCHAN>USB-3101FS</DAQCHAN> Option 2 <DAQ>NIDAQMX.dll</DAQ> <DAQCHAN>Dev1/ao0:3</DAQCHAN> Option 3 <DAQ></DAQ> <DAQCHAN></DAQCHAN> // Use Measurement Computing driver // The name of the Measurement Computing device // Use National Instruments driver // The National Instruments Device Number and Channels // Do not load any DAQ device // Leave this field blank b) The DAQ Device will automatically stream the X,Y gaze signal through the device s first and second output channels. If you have a 4 channel output DAQ, then the pupil area will streamed on the 3 rd channel. The 4 th channel is currently reserved for future use. It does not output any signal at this time, and you should read 0V. c) The analog output dynamic range is -10 to +10 Volts d) The instantaneous analog output level is displayed on the Oculomatic user interface. e) Pupil area is normalized from 0-1 and streamed from -10 to +10 Volts, where no pupil detected corresponds to -10V and a fully open pupil is +10V. Pupil normalization is computed by using the min and max pupil area values specified in the GUI. f) Any 2D Affine transformation will be applied to the voltage as well as shared memory accessible via the SDK. g) The gain and invert signal controls can be adjusted by the user. h) All GUI settings can be saved by pressing the S key. i) Gaze, pupil area, and image data are currently not saved by Oculomatic. It is up to the user to implement their own save functionality. The supplied C++ program demonstrates how to do this. You may save data sample by sample, or buffer for the duration of a session, the design is up to you. 6
8) Digital data output a) Data is concomitantly output digitally to shared memory. Any other program running on the same computer can read the x,y gaze signal by implementing the Oculomatic pro SDK. Matlab and C++ examples are provided in the SDK subdirectory of the distribution. b) Unlike analog output, digital data is supplied as normalized values in the range of 0.0 to 1.0, where 0.5 is the center of the visual display. c) The current digital gaze signal is also displayed in the user interface. d) As with analog output, any 2D Affine transformation, including gain and invert, will be applied to the digital data output as well. e) Gaze x,y, pupil area, and time stamp are logged to file if the option is checked (by default it is) in the GUI. Each time Oculomatic starts up, the log file is over written. i) For sophisticated data saving, we leave it up to the user to implement their own functionality. The supplied C++ and Matlab sample programs demonstrate how to do get data sample by sample, allowing you to process and record this information however you wish. ii) Videos of the eye image are currently not saved by Oculomatic. Future releases may incorporate this feature, or allow users to grab images frame by frame via the sdk and implement save functionality themselves. 9) Troubleshooting a) Error message(s) stating that it cannot connect to a camera: Most likely because 1) the camera s power is off, 2) cable is not securely connected, or 3) you are not using a Gigabit ethernet port. Most likely because the camera s driver is not installed 7
This message is reported by the camera s driver and we can t suppress it. It usually means 1) the camera s power is off, 2) cable is not securely connected, or 3) you are not using a Gigabit ethernet port. This message always follow s the previous message. 8
Resulting in the following window showing noise instead of a video image All of these error messages are related to the system not detecting the camera. This can result from an incorrect physical connection, improper software driver installation, or incompatible network card. i) Check to make sure the cable is screwed down and the blue light is on as shown in the following figure. This indicates that the camera is getting powered and is most likely connected to your computer s ethernet card. ii) Check the ethernet status, make sure that it is enabled. The Speed must indicate 1.0 Gbps. 9
iii) Final confirmation that the cable is connected 10
iv) Run the Sapera Cam Expert utility to check if the camera is detected, as shown below. v) You must install All acquisition components when running the Sapera driver as shown below and restart your computer. 11
vi) Check in the MS Windows Control panel that the Sapera Driver is installed (as well as all other software as shown in the following screen shot). There are two components, the LT Runtime and Network Imaging Package. If they are missing, you will need to reinstall them. This might happen if you did not select All acquisition components as shown in the previous step. b) Analog output does not work. 12
i) If you get an error message such as: ii) Make sure the corresponding DAQ driver is installed. (1) NIDAQmx is for National Instruments. You do need Measurement and Automation Explorer to be installed as part of the driver. (2) MCCDAQ is for Measurement computing. You only need InstaCal iii) Do you have the correct configuration in the settings.xml file? See above for the various daq devices you can configure to use with Oculomatic. iv) Check that the correct BNC wires are connected and grounded. c) Noisy signal, or bad calibration: i) A video demonstration on focusing the camera and lighting is available on youtube.com: (1) https://www.youtube.com/watch?v=3e5if1tzwaw ii) Shown are 9 cardinal viewing angles. The pupil is clearly thresholded in every direction. 13
iii) Example of bad pupil threshold. Adjust the pupil threshold parameter. Otherwise, the lighting and focus are within tolerances. iv) Example of bad focus. Adjust focus on the camera lens. v) Example of bad lighting. Is your IR Emitter plugged in and facing the eye? Is the camera s aperture opened? 14
vi) Example of a Monkey s eye. Different species will have different size pupils. 10) Calibration.txt file format a) The first line is the number of calibration points b) The following lines each have 4 values: i) X,Y location of calibration point, followed by X,Y raw gaze value when looking at the calibration point. ii) This is repeated for each calibration location. /******************** 9 1.0 1.0 1.0 1.0 1.0 0.0 1.0 0.0 1.0-1.0 1.0-1.0 0.0 1.0 0.0 1.0 0.0 0.0 0.0 0.0 0.0-1.0 0.0-1.0-1.0 1.0-1.0 1.0-1.0 0.0-1.0 0.0-1.0-1.0-1.0-1.0 ********************/ 15