# Usage Guide

CodeGRITS is built on top of Tobii Pro SDK, and is expected to be compatible with all Tobii eye-tracking devices (see Supported Eye Trackers for more details). However, we have only tested CodeGRITS with Tobii Pro Fusion since we do not have access to other eye-tracking devices. If you want to further develop CodeGRITS for your own eye-tracking device, please refer to the Developer Guide for more details, and also feel free to contact us if you need further assistance.

You could also use CodeGRITS without an eye-tracking device. Since CodeGRITS provides mouse simulation as a substitute for eye gaze. You could also uncheck the Eye Tracking option in the configuration window to disable eye tracking.

CodeGRITS is expected to be compatible with the entire family of JetBrains IDEs, including IntelliJ IDEA, PyCharm, Clion, etc. Due to the limited time, we did not specifically test CodeGRITS thoroughly on all of them. We provide a list of JetBrains IDEs that we have tested CodeGRITS on.

Since CodeGRITS is still in its early developmental stage, even though we believe it would work well, some minor issues may still exist. If you encounter any of them, please feel free to contact us or create a GitHub Issue.

Since Tobii Pro SDK did not provide a Java API, we have to use the Python API to collect eye gaze data. Thus, it is necessary to install the following packages in your Python environment to run this plugin (minor version differences should be fine).

python==3.8.8
tobii-research==1.10.1
pyautogui==0.9.53
screeninfo==0.8

Refer to Supported platforms and languages, Tobii Pro SDK only supports Python 3.8 and Python 3.10. Regarding operating systems, Tobii Pro SDK supports Windows 10 and 11 (64-bit), macOS 10.15 and 12, and Ubuntu 20.04 LTS. Note that unsupported operating systems may cause installation issues, especially the tobii-research package.

We provide the direct download link of the plugin zip file for the following JetBrains IDEs for convenience.

Note that the macOS version of the plugin is not fully tested as Windows and Linux versions, and some minor issues may exist.

We also encourage you to build the plugin from the source code, especially for the IDEs that are not listed above.

1. Clone the repository to your local machine. Note that the main branch is the stable version for Windows and Linux, and the mac branch is the unstable version for macOS.
2. Set the IDE type and version in build.gradle.kts file. For example, if you want to build the plugin for IntelliJ Community Edition between 2022.2 and 2023.3, you should set the following in build.gradle.kts file.

   intellij {
       type = "IC"
   }
   tasks {
       patchPluginXml {
           sinceBuild.set("222")
           untilBuild.set("233.*")
       }
   }

   Please refer to the Gradle IntelliJ Plugin - Configuration and Plugins Targeting IntelliJ Platform-Based IDEs for more details.
3. Open the command line and run ./gradlew build in the root folder to build the plugin.
4. Find the plugin zip file in the build/distributions folder.

1. Open the JetBrains IDE, click File - Settings - Plugins - Install Plugin from Disk... to install the plugin zip file.
2. Restart IntelliJ IDEA to enable the plugin, then all CodeGRITS features are available in the Tools dropdown menu, including Start/Stop Tracking, Pause/Resume Tracking, and Configuration.

Before starting tracking, you should first configure the plugin. Click Tools - Configuration to open the configuration window. The configuration settings are stored in the config.json file in the bin/ folder of your installed JetBrains IDE.

You can select the trackers which you want to use, including IDE Tracker, Eye Tracker, and Screen Recorder. If a compatible eye-tracking device is not available, CodeGRITS would use the mouse cursor as a substitute for eye gaze data.

You can configure the following settings:

• The Python interpreter path that is used for Eye Tracker;
• The output directory for the collected data, defaults to the root folder of your project;
• The sample frequency of Eye Tracker. The range depends on the eye-tracking device;
• The eye-tracking device to use. The mouse is also available as a substitute.

To enable eye tracking, you need to have the necessary Python packages installed in your Python environment. The plugin automatically checks if the required packages are installed.

You are able to pre-set some labels here which could be used to mark the developers' semantic activities that cannot be captured by explicit IDE interactions. You can add the labels by right-clicking during tracking. The label is also recorded in the output data via IDE Tracker.

IDE Tracker could track a wide range of IDE interactions including all but not limited to the following.

A real-time archive mechanism is also implemented to archive the whole code files when they are changed, and the console output during the development process. Below is one example of data collected by IDE Tracker. See Data Format for more details.

The workflow of Eye Tracker is divided into three steps:

(1) Connect to the eye-tracking device and receive raw data, which includes the coordinates of the eye gaze points, pupil diameters of both eyes and their validity; If a compatible eye-tracking device is not available, CodeGRITS will use the mouse cursor as a substitute.

(2) Map the coordinates of raw gazes within the text editor to specific locations in the code (i.e., file path, line and column number);

Below is one example of the data collected by Eye Tracker. See Data Format for more details.

Screen Recorder captures everything on the screen and saves the capture to a video. It also records the timestamp of each frame, which can be used to synchronize the screen recording with other tracking data to facilitate analysis. See Data Format for more details.