Transcription
iView X SDK 3.0iView X SDK1v3.1.0June 2012 2012 SensoMotoric Instruments GmbHJune 2012
iView X SDK 3.0Table of ContentsIntroduction. 6System Requirements . 7Supported Eye Tracking Devices . 7Supported Programming and Scripting Languages . 8Supported Operating Systems. 8Function and Device Overview . 8Getting Started . 11Downloading . 11Running the Installer . 11Next Steps. 12Getting started with the SDK Examples . 13Using C# . 14Using MATLAB . 17Using Python . 18Using E-Prime . 19Using NBS Presentation . 21iView X SDK Reference . 23Header File . 23Defines . 23Enumerations . 23Structs . 23Functions . 24Explanations for Defines. 25Explanations for Enumerations . 26Explanations for Data Structures. 27AccuracyStruct Reference . 27CalibrationPointStruct Reference. 27EventStruct Reference . 27EventStruct32 Reference. 28EyeDataStruct Reference. 28SampleStruct Reference . 29SampleStruct32 Reference . 29SystemInfoStruct Reference . 30CalibrationStruct Reference . 30 2012 SensoMotoric Instruments GmbHJune 20122
iView X SDK 3.0MonitorAttachedGeometryStruct Reference . 31StandAloneModeGeometryStruct Reference . 31ImageStruct Reference . 32AOIRectangleStruct Reference . 32AOIStruct Reference . 33Function Reference . 33int iV AbortCalibration () . 33int iV AcceptCalibrationPoint () . 34int iV Calibrate (). 34int iV ChangeCalibrationPoint (int number, int positionX, int positionY) . 34int iV ClearAOI () . 35int iV ClearRecordingBuffer (). 35int iV Connect (char sendIPAddress[16], int sendPort, char recvIPAddress[16], int receivePort)35int iV ContinueEyetracking () . 36int iV ContinueRecording (char etMessage[256]) . 36int iV DefineAOI(struct AOIStruct * aoiData) . 36int iV DefineAOIPort(int portNumber) . 37int iV DisableAOI (char aoiName[256]) . 37int iV DisableAOIGroup (char aoiGroup[256]) . 37int iV DisableGazeDataFilter() . 37int iV Disconnect () . 38int iV EnableAOI (char aoiName[256]) . 38int iV EnableAOIGroup (char aoiGroup[256]). 38int iV EnableGazeDataFilter() . 38int iV GetAccuracy (struct AccuracyStruct * accuracyData, int visualization). 39int iV GetAccuracyImage (struct ImageStruct * imageData). 39int iV GetCurrentCalibrationPoint (struct CalibrationPointStruct * currentCalibrationPoint). 39int iV GetCurrentTimestamp (int64* currentTimestamp) . 40int iV GetEvent (struct EventStruct * eventDataSample). 40int iV GetEvent32 (struct EventStruct32 * eventDataSample) . 40int iV GetEyeImage (struct ImageStruct* image) . 40int iV GetSample (struct SampleStruct * rawDataSample) . 41int iV GetSample32 (struct SampleStruct32 * rawDataSample) . 41int iV GetSceneVideo(struct ImageStruct* image). 41int iV GetSystemInfo (struct SystemInfoStruct * systemInfoData) . 42 2012 SensoMotoric Instruments GmbHJune 20123
iView X SDK 3.0int iV GetTrackingMonitor (struct ImageStruct* image) . 42int iV IsConnected () . 42int iV LoadCalibration (char name [256]) . 42int iV Log (char logMessage[256]) . 43int iV PauseEyetracking () . 43int iV PauseRecording () . 43int iV Quit() . 44int iV ReleaseAOIPort () . 44int iV RemoveAOI (char aoiName[256]) . 44int iV ResetCalibrationPoints() . 44int iV SaveCalibration (char name [256]) . 45int iV SaveData (char filename [256], char description [64], char user [64], int overwrite) . 45int iV SendCommand (char etMessage[256]) . 46int iV SendImageMessage (char etMessage[256]) . 46void iV SetCalibrationCallback ( pDLLSetCalibrationPoint pCalibrationPoint). 46void iV SetEventCallback ( pDLLSetEvent pEvent) . 47int iV SetEventDetectionParameter (int minDuration, int maxDispersion) . 47void iV SetEyeImageCallback ( pDLLSetEyeImage pEyeImage). 47int iV SetLicense (char key[16]) . 47int iV SetLogger (int logLevel, char filename[256]) . 48void iV SetResolution (int stimulusWidth, int stimulusHeight) . 48void iV SetSampleCallback ( pDLLSetSample pSample) . 48void iV SetSceneVideoCallback (pDLLSetSceneVideo pSceneVideo) . 49void iV SetTrackingMonitorCallback (pDLLSetTrackingMonitor pTrackingMonitor) . 49int iV SetTrackingParameter (int ET PARAM EYE, int ET PARAM, int value) . 49int iV SetupCalibration(struct CalibrationStruct *calibrationData). 49int iV SetupMonitorAttachedGeometry (struct ) . 50int iV SetupStandAloneMode (struct y) . 50int iV ShowEyeImageMonitor () . 50int iV ShowSceneVideoMonitor() . 51int iV ShowTrackingMonitor () . 51int iV Start(int etApplication) . 51int iV StartRecording () . 51 2012 SensoMotoric Instruments GmbHJune 20124
iView X SDK 3.0int iV StopRecording (). 52int iV Validate () . 52RED Stand Alone Mode . 53RED Monitor Attached Mode . 54Areas of Interest (AOI). 55Return Codes . 56Technical Support . 58License Agreement and Warranty for SDK Provided Free of Charge . 581.License . 582.Rights in Licensed Materials . 583.Confidentiality . 584.Limited Warranty and Liability . 595.Licensee Indemnity. 596.Export Restriction . 597.Non-Waiver; Severability; Non-Assignment. 598.Termination . 599.Entire Agreement; Written Form Requirement. . 5910.Notices . 6011.Applicable Law and Jurisdiction . 60About SMI . 61 2012 SensoMotoric Instruments GmbHJune 20125
iView X SDK 3.0IntroductionWelcome to the iViewX SDK Guide v.3.0.29!About iViewX SDKThe iView X Software Development Kit (“SDK”) provides an Application Interface (“API”) forcommunication between your software application and iView X , allowing you to create fullfeatured eye tracking applications that take advantage of the powerful features offered bySensoMotoric Instruments (“SMI”) eye tracking devices and the iView X platform. Specifically, theSDK was designed for SMI customers who wish to add eye tracking into their own customapplications. Using the functions provided in the SDK you can control SMI eye tracking devices andretrieve eye tracking data online. The SDK uses UDP over Ethernet communication to providemaximum speed and minimum latency for data transfer. Additionally, the SDK supports a growingnumber of programming languages and environments including, but not limited to, MATLAB , C/C ,C#, Visual Basic, E-Prime, NBS Presentation, and Python. Several example programs are provided forhelping you get started with your application development.About the GuideThe SDK Guide provides a practical introduction to developing applications using the SDK anddocumentation about major SDK features. It includes instructions for setting up your SDKenvironment and a function reference, which outlines each available function as well as thesupported devices. Additionally, the manual gives a brief overview on the included examples for eachmajor platform.6What’s New?In addition to this document, the SDK includes release notes, which may be found in the SMI\iView XSDK\docs directory. In the release notes you can find a complete list of the improvements and bugfixes we have made, helping you get the most from each release.Important Notes:PLEASE NOTE that in order to exchange data between iView X and your software application usingthe SDK, an Ethernet (IEEE 802.3) connection must be established. This applies even when runningiView X and your software application on the same PC. If unfamiliar with such process, pleaseconsult relevant documentation (e.g. the iView X user manual) on how to establish an Ethernetconnection between different computers. Please adjust the IP address and port settings in iView X and your application accordingly. 2012 SensoMotoric Instruments GmbHJune 2012
iView X SDK 3.0API layer overview:Shown below is a graphical overview of the iView X API.iView X SDK installer contains 32-bit DLLsNOTE: This SDK installer contains Windows 32bit DLLs. Although you can install and run the iView X SDK binaries on a Windows 64-bit OS given that 64-bit processors can run both 64-bit and 32-bitapplications natively, please note that it is not possible to implement the binaries in Windows 64-bitapplications. The SDK application files are installed into C:\Program Files (x86) for Windows 64-bitOS and C:\Program Files for Windows 32-bit OS.System RequirementsThe sections below describe the system requirements for developing applications using the iViewX SDK.Supported Eye Tracking DevicesThe following SMI Eye Tracking Devices are supported in this release:Supported Eye Tracking SystemsFrame rate [Hz]iView X RED 4 (Firewire)50 / 60RED (USB)60 / 120RED25060 / 120 / 250RED50060 / 120 / 250 / 500RED-m60 / 120iView X HED50 / 200iView X HED HT50 / 200iView X Hi-Speed240 (mono)iView X Hi-Speed350 (mono / bin)iView X Hi-Speed500 (mono / bin)iView X Hi-Speed1250 (mono)iView X Hi-Speed Primate500 / 1250 (mono / bin) 2012 SensoMotoric Instruments GmbHJune 20127
iView X SDK 3.0iView X MRI LR50iView X MEG50 / 250In general, it is always best to make sure that you are running the latest available version of iViewX and firmware for your eye tracker model with the SDK. The most recent iView X software isalways provided on the SMI Support Software Downloads king-systems/support/software-download.html.Please note that the SDK does not support iView X releases prior to v.2.0.Supported Programming and Scripting LanguagesThe iView X SDK can be used with most programming and scripting languages that are capableof importing C dynamic link libraries (DLLs). These include, but are not limited to, C , C#, Matlab,E-Prime, Python, and NBS Presentation. The SDK includes several programming examples to helpyou get started in your application development. They are as follows:LanguagesExampleC Remote Control ApplicationC#Remote Control ApplicationMATLAB E-PrimeSlide show and Gaze contingent ExperimentSlide show and Gaze contingent ExperimentPythonSlide show and Gaze contingent ExperimentNBS PresentationSlide show and Gaze contingent Experiment8These examples applications are included in the SDK folder in the /examples directory. Theyhighlight many of the features and capabilities of the iView X libraries and APIs.Supported Operating SystemsThe iView X SDK for is designed to run on the following operating systems:Supported Operating SystemsNotesWindows XP 32 bitSupportedWindows XP 64 bitSupportedWindows Vista 32 bitSupportedWindows Vista 64 bitSupportedWindows 7 32 bitSupportedWindows 7 64 bitSupportedLinuxPlannedMac OS XPlannedFunction and Device OverviewThe table below provides an overview of the various functions available in the iView X SDK alongwith their corresponding supported SMI eye tracking devices. More detailed informationpertaining to these functions follows in the iView X SDK Reference section. 2012 SensoMotoric Instruments GmbHJune 2012
iView X SDK 3.0REDRED-mHiSpeed/ PrimateHEDMRI /MEGXXX-X2iV AbortCalibrationiV AcceptCalibrationPointXXX-X3iV CalibrateXXX-X4iV ChangeCalibrationPointXXXXX5iV ClearAOIXXX-X6iV ClearRecordingBufferXXXXX7iV ConnectXXXXX8iV ContinueEyetrackingXX---9iV ContinueRecordingXXXXX10iV DefineAOIXXX-X11iV DefineAOIPortXXX-X12iV DeleteMonitorAttachedGeometry-X---13iV DeleteStandAloneGeometryX----14iV DisableAOIXXX-X15iV DisableAOIGroupXXX-X16iV DisableGazeDataFilterXXX-X17iV DisconnectXXXXX18iV EnableAOIXXX-X19iV EnableAOIGroupXXX-X20iV EnableGazeDataFilterXXX-X21iV GetAccuracyXXX-X22iV GetAccuracyImageXXX-X23iV GetCurrentCalibrationPointXXXXX24iV GetCurrentTimestampXXXXX25iV GetEventXXX-X26iV GetEvent32XXX-X27iV GetEyeImageXXXXX28iV GetSampleXXXXX29iV GetSample32XXXXX30iV GetSceneVideo---X-31iV GetSystemInfoXXXXX32iV GetTrackingMonitorXX---33iV IsConnectedXXXXX34iV LoadCalibrationXXX-X35iV LogXXXXX36iV PauseEyetrackingXX---37iV PauseRecordingXXXXX38iV QuitXXXXX39iV ReleaseAOIPortXXX-X40iV RemoveAOIXXX-X41iV ResetCalibrationPointsXXXXX42iV SaveCalibrationXXX-X43iV SaveDataXXXXX44iV SendCommandXXXXX45iV SendImageMessageXXX-XFunction1 2012 SensoMotoric Instruments GmbHJune 20129
iView X SDK 3.0FunctionREDRED-mHiSpeed/ PrimateHEDMRI /MEGXX-X46iV SetCalibrationCallbackX47iV SetConnectionTimeoutXXXXX48iV SetEventCallbackXXX-X49iV SetEventDetectionParameterXXX-X50iV SetEyeImageCallbackXXXXX51iV SetResolutionXXX-X52iV SetLicense-X---53iV SetLoggerXXXXX54iV SetResolutionXXX-X55iV SetSampleCallbackXXXXX56iV SetSceneVideoCallback---X-57iV SetTrackingMonitorCallbackXX---58iV SetTrackingParameter--XXX59iV SetupCalibrationXXX-X60iV SetupMonitorAttachedGeometry-X---61iV SetupStandAloneModeX----62iV ShowEyeImageMonitorXXXXX63iV ShowAccuracyMonitorXXXXX64iV ShowSceneVideoMonitor---X-65iV ShowTrackingMonitorXX---66iV StartXXXXX67iV StartRecordingXXXXX68iV StopRecordingXXXXX69iV ValidateXXX-X 2012 SensoMotoric Instruments GmbHJune 201210
iView X SDK 3.0Getting StartedQuickly get started with developing your SDK application by reading the sections below. In thefollowing sections you will learn how to set up your SDK environment, about the various functionavailable in the SDK, and how to create your first basic eye tracking application based on theprovided examples.Note: The SDK must be installed on the same computer as your software application. If running youreye tracking studies in a single-PC setup, this will be the same computer as your iView X software.DownloadingYou can download the latest recommended release of the SDK from the SMI Software Downloadspage: systems/support/softwaredownload.html.Running the InstallerAfter you have downloaded the SDK installer package, double-click the .msi file to begin theinstallation.When the files have been unpacked, the SDK License Agreement will appear — it contains importantinformation about the terms under which we supply the SDK. Agree to it if you would like to proceedwith the installation.If you had a previous installation it will first be removed before the new version of the SDK isinstalled on your computer. Please wait for the installation to complete. The installation process maytake a few minutes.When the SDK installation process is completed, the following folder structure will be available onyour computer: 2012 SensoMotoric Instruments GmbHJune 201211
iView X SDK 3.012As can be seen from the figure above, the SDK folder is divided into six sub-folders, “AutomaticUpdates”, “bin”, “docs”, “Examples”, “include”, and “lib”. The “bin” folder contains the Microsoftbinaries. The “docs” folder contains documentation, which describes the iView X API itself. The“Examples” folder contains several sample scripts and programs, which provide a quick and easystart into controlling iView X via the SDK. For detailed syntax information the user can take a lookinto the functional characteristics of the ready-to-use source code of all examples. The examplesillustrate the basic functionalities of the SDK and can be used as a baseline for developing your ownprojects and/or experiments. The “include” folder contains the header file of the iView X API. The“lib” folder contains the static library of the iView X API.Next StepsOnce you have completed installation of the SDK, you are ready to begin developing applications.Here are a few ways you can get started:Explore some code 2012 SensoMotoric Instruments GmbHJune 2012
iView X SDK 3.0The SDK includes sample code and applications for each major platform. You can browse theseexamples in the Examples folder.Learn about the iView X SDKTake a look at the “Getting Started with the SDK Examples” and “iView X SDK Reference” sectionsbelow to learn more about the included example programs and available functions.Getting started with the SDK ExamplesThe following sample experiments are provided with the SDK:-Remote Control Application: A simple application with the most common features forcontrolling an SMI eye tracker through iView X , including establishing a connection to iViewX , performing a calibration, and receiving data from the eye tracker.-Gaze Contingent Experiment: An example that demonstrates running a calibration sessionand subsequently recording eye tracking data. In this experiment gaze position data isretrieved from iView X in real time and displayed as on overlay on the presented bitmapimage. The example illustrates several example functions and commands and is a goodstarting point for writing your own eye tracking application.-Slide Show Experiment: An example that demonstrates running a calibration session andsubsequently recording eye tracking data. In this experiment a series of images arepresented to a user while eye tracking data is recorded in the background. The exampleillustrates several example functions and commands and is a good starting point for writingyour own eye tracking application. 2012 SensoMotoric Instruments GmbHJune 201213
iView X SDK 3.0The above examples demonstrate concepts that are fundamental to SDK application development.All example programs described in this SDK Guide are also provided in source code form in theexamples directory according to programming and scripting language type. (e.g., \Examples\VS C# forthe C# demo application) The source code will give a more detailed insight into the possibilities of theSDK and it functions.Using C#The SDK includes a C# example program, the Remote Control Application, to help you get startedwith developing your own application.LanguagesExampleC#Remote Control ApplicationThe C# example was created using Visual Studio 2008.You can run the C# demo application by double-clicking on the “csdemo.exe” file in the VS C#\DemoApplication folder. Doing so will bring up an application that looks like the image shown below. Thefull source code of this sample is included in the VS C#\Demo Project folder.To establish a connection to iView X you must first set the according IP addresses in the Connect toiView X sections of the User Interface. For single-PC setups, the “Received from” and “Send to” IPaddresses and ports will likely be (127.0.0.1; 5555) and (127.0.0.1; 4444), respectively. Please note 2012 SensoMotoric Instruments GmbHJune 201214
iView X SDK 3.0that the “Receive from” IP address and Port will be the same as the “Send to” IP address and Port setin-iView X (Setup - Hardware - Communication - Ethernet) or‘Network Settings ’ entry from tray menu.You should be sure to verify this, otherwise iView X and the example program will not be able tocommunicate. After configuring the IP addresses and ports, click the “Connect” button. If aconnection has been established, gaze data will be streamed automatically and will be shown in the“Sample” text box.The following code shows how to declare and use severa
SensoMotoric Instruments ("SMI") eye tracking devices and the iView X platform. Specifically, the SDK was designed for SMI customers who wish to add eye tracking into their own custom applications. Using the functions provided in the SDK you can control SMI eye tracking devices and retrieve eye tracking data online.
