From 347fac11de78ac51fef6bb10700b3ed88943ee92 Mon Sep 17 00:00:00 2001 From: Retype GitHub Action Date: Tue, 5 Mar 2024 16:12:42 +0000 Subject: [PATCH] Refreshes Retype-generated documentation. Process triggered by TTangNingzhi. --- 404.html | 8 ++++---- about/index.html | 8 ++++---- changelog/index.html | 8 ++++---- data-format/index.html | 10 +++++----- developer/index.html | 10 +++++----- faq/index.html | 8 ++++---- index.html | 30 +++++++++++++++++++++++++----- license/index.html | 8 ++++---- resources/js/config.js | 2 +- resources/js/search.json | 2 +- sitemap.xml.gz | Bin 700 -> 704 bytes usage-guide/index.html | 10 +++++----- 12 files changed, 62 insertions(+), 42 deletions(-) diff --git a/404.html b/404.html index d33a177..3aec5a6 100644 --- a/404.html +++ b/404.html @@ -4,7 +4,7 @@ - + @@ -29,11 +29,11 @@ - + - + - +
diff --git a/about/index.html b/about/index.html index 1fe85b2..442c6a4 100644 --- a/about/index.html +++ b/about/index.html @@ -4,7 +4,7 @@ - + @@ -32,11 +32,11 @@ - + - + - +
diff --git a/changelog/index.html b/changelog/index.html index 516450d..bea8cf7 100644 --- a/changelog/index.html +++ b/changelog/index.html @@ -4,7 +4,7 @@ - + @@ -32,11 +32,11 @@ - + - + - +
diff --git a/data-format/index.html b/data-format/index.html index d5e7ae4..667d5f6 100644 --- a/data-format/index.html +++ b/data-format/index.html @@ -4,7 +4,7 @@ - + @@ -32,12 +32,12 @@ - + - + - - + +
diff --git a/developer/index.html b/developer/index.html index 5205431..120ea6f 100644 --- a/developer/index.html +++ b/developer/index.html @@ -4,7 +4,7 @@ - + @@ -32,12 +32,12 @@ - + - + - - + +
diff --git a/faq/index.html b/faq/index.html index a95b15a..ce0312c 100644 --- a/faq/index.html +++ b/faq/index.html @@ -4,7 +4,7 @@ - + @@ -32,11 +32,11 @@ - + - + - +
diff --git a/index.html b/index.html index 88fbaaf..3bf0d45 100644 --- a/index.html +++ b/index.html @@ -4,7 +4,7 @@ - + @@ -32,11 +32,11 @@ - + - + - +
@@ -264,11 +264,31 @@

⚡ NEWS! ⚡

We would present CodeGRITS at -ICSE 2024 Demo Track. +ICSE 2024 Demo Track. Welcome to join us and discuss with us about it!

+
+
+ +

CodeGRITS stands for Gaze Recording & IDE Tracking System. It's a plugin developed by the SaNDwich Lab and is specially designed for empirical software engineering researchers. CodeGRITS is built on top diff --git a/license/index.html b/license/index.html index 973a15e..14999ba 100644 --- a/license/index.html +++ b/license/index.html @@ -4,7 +4,7 @@ - + @@ -32,11 +32,11 @@ - + - + - +

diff --git a/resources/js/config.js b/resources/js/config.js index 964a5d7..444b3f7 100644 --- a/resources/js/config.js +++ b/resources/js/config.js @@ -1 +1 @@ -var __DOCS_CONFIG__ = {"id":"eZrAvAItDi5SW+6E24841wA8N5q+s3zyxX1","key":"tcvt0/2E0iJwU89tcdl2OWLBYNW6FlgZXVho/RrU1T0.cjIyiuUcce5ESDKS+HVND3BygFgGqQBjM0a8OhcniBqUVNtyPwzqlr7si8jBeS3zREsZcS7NLUHXswhOaKOJow.42","base":"/CodeGRITS/","host":"codegrits.github.io","version":"1.0.0","useRelativePaths":true,"documentName":"index.html","appendDocumentName":false,"trailingSlash":true,"preloadSearch":false,"cacheBustingToken":"3.5.0.759257999436","cacheBustingStrategy":"query","sidebarFilterPlaceholder":"Filter","toolbarFilterPlaceholder":"Filter","showSidebarFilter":true,"filterNotFoundMsg":"No member names found containing the query \"{query}\"","maxHistoryItems":15,"homeIcon":"","access":[{"value":"public","label":"Public"},{"value":"protected","label":"Protected"}],"toolbarLinks":[{"id":"fields","label":"Fields"},{"id":"properties","label":"Properties"},{"id":"methods","label":"Methods"},{"id":"events","label":"Events"}],"sidebar":[{"n":"/","l":"Welcome","s":""},{"n":"about","l":"About","s":""},{"n":"usage-guide","l":"Usage Guide","s":""},{"n":"data-format","l":"Data Format","s":""},{"n":"developer","l":"Developer Guide","s":""},{"n":"changelog","l":"Changelog","s":""},{"n":"faq","l":"FAQ","s":""},{"n":"license","l":"License","v":false}],"search":{"mode":0,"minChars":2,"maxResults":20,"placeholder":"Search","hotkeys":["k"],"noResultsFoundMsg":"Sorry, no results found.","recognizeLanguages":true,"languages":[0],"preload":false},"resources":{"History_Title_Label":"History","History_ClearLink_Label":"Clear","History_NoHistory_Label":"No history items","API_AccessFilter_Label":"Access","API_ParameterSection_Label":"PARAMETERS","API_SignatureSection_Label":"SIGNATURE","API_CopyHint_Label":"Copy","API_CopyNameHint_Label":"Copy name","API_CopyLinkHint_Label":"Copy link","API_CopiedAckHint_Label":"Copied!","API_MoreOverloads_Label":"more","API_MoreDropdownItems_Label":"More","API_OptionalParameter_Label":"optional","API_DefaultParameterValue_Label":"Default value","API_InheritedFilter_Label":"Inherited","Search_Input_Placeholder":"Search","Toc_Contents_Label":"Contents","Toc_RelatedClasses_Label":"Related Classes","History_JustNowTime_Label":"just now","History_AgoTime_Label":"ago","History_YearTime_Label":"y","History_MonthTime_Label":"mo","History_DayTime_Label":"d","History_HourTime_Label":"h","History_MinuteTime_Label":"m","History_SecondTime_Label":"s"}}; +var __DOCS_CONFIG__ = {"id":"j482kLycA2rsOqKen248PH/zvavdXrNK1ZG","key":"eNEBPegV1Wxz+QP0VyfrNLbMgBGMDJcNlGhC1c7F5P8.mN1vhWEyTHqP1OVTAzfEHNmcvtUd5bD0V9JrNZMQL1brMC8YwX7Y6FVITF7MkK04knwj83uFLV9gUDd4pGakow.94","base":"/CodeGRITS/","host":"codegrits.github.io","version":"1.0.0","useRelativePaths":true,"documentName":"index.html","appendDocumentName":false,"trailingSlash":true,"preloadSearch":false,"cacheBustingToken":"3.5.0.762970357353","cacheBustingStrategy":"query","sidebarFilterPlaceholder":"Filter","toolbarFilterPlaceholder":"Filter","showSidebarFilter":true,"filterNotFoundMsg":"No member names found containing the query \"{query}\"","maxHistoryItems":15,"homeIcon":"","access":[{"value":"public","label":"Public"},{"value":"protected","label":"Protected"}],"toolbarLinks":[{"id":"fields","label":"Fields"},{"id":"properties","label":"Properties"},{"id":"methods","label":"Methods"},{"id":"events","label":"Events"}],"sidebar":[{"n":"/","l":"Welcome","s":""},{"n":"about","l":"About","s":""},{"n":"usage-guide","l":"Usage Guide","s":""},{"n":"data-format","l":"Data Format","s":""},{"n":"developer","l":"Developer Guide","s":""},{"n":"changelog","l":"Changelog","s":""},{"n":"faq","l":"FAQ","s":""},{"n":"license","l":"License","v":false}],"search":{"mode":0,"minChars":2,"maxResults":20,"placeholder":"Search","hotkeys":["k"],"noResultsFoundMsg":"Sorry, no results found.","recognizeLanguages":true,"languages":[0],"preload":false},"resources":{"History_Title_Label":"History","History_ClearLink_Label":"Clear","History_NoHistory_Label":"No history items","API_AccessFilter_Label":"Access","API_ParameterSection_Label":"PARAMETERS","API_SignatureSection_Label":"SIGNATURE","API_CopyHint_Label":"Copy","API_CopyNameHint_Label":"Copy name","API_CopyLinkHint_Label":"Copy link","API_CopiedAckHint_Label":"Copied!","API_MoreOverloads_Label":"more","API_MoreDropdownItems_Label":"More","API_OptionalParameter_Label":"optional","API_DefaultParameterValue_Label":"Default value","API_InheritedFilter_Label":"Inherited","Search_Input_Placeholder":"Search","Toc_Contents_Label":"Contents","Toc_RelatedClasses_Label":"Related Classes","History_JustNowTime_Label":"just now","History_AgoTime_Label":"ago","History_YearTime_Label":"y","History_MonthTime_Label":"mo","History_DayTime_Label":"d","History_HourTime_Label":"h","History_MinuteTime_Label":"m","History_SecondTime_Label":"s"}}; diff --git a/resources/js/search.json b/resources/js/search.json index 500319f..e2aae80 100644 --- a/resources/js/search.json +++ b/resources/js/search.json @@ -1 +1 @@ -[[{"l":"Welcome to CodeGRITS","p":["We would present CodeGRITS at ICSE 2024 Demo Track. Welcome to join us and discuss with us about it!","CodeGRITS stands for G aze R ecording & I DE T racking S ystem. It's a plugin developed by the SaNDwich Lab and is specially designed for empirical software engineering researchers. CodeGRITS is built on top of IntelliJ Platform SDK, with wide compatibility with the entire family of JetBrains IDEs and Tobii eye-tracking devices, to track developers’ IDE interactions and eye gaze data. The source code is available on GitHub with Javadoc documentation.","The data collected by CodeGRITS can be used by empirical SE researchers to understand the behaviors of developers, especially those related to eye gaze. CodeGRITS also provides a real-time data API for future plugin developers and researchers to design context-aware programming support tools.","CodeGRITS is still in its developmental stage as a research tool. Our goal is to make it mature enough and beneficial for the community, particularly for those involved in empirical software engineering and eye tracking research. We encourage the community to contribute through GitHub Issue for any suggestions or issues, aiding in its improvement.","For any inquiries, please email us at ntang@nd.edu or jan2@nd.edu. If you're interested in using CodeGRITS in your research, don't hesitate to email us for setup support. We are delighted to provide tailored assistance based on your specific OS and JetBrains IDE environment."]},{"l":"Cross-platform and Multilingual Support","p":["CodeGRITS provides cross-platform support for Windows, macOS, and Linux, and is expected to be compatible with the entire family of JetBrains IDEs, including IntelliJ IDEA, PyCharm, WebStorm, etc.","CodeGRITS could extract the abstract syntax tree (AST) structure of eye gazes on multiple programming languages, as long as the IDE supports them, including Java, Python, C/C++, JavaScript, etc."]},{"l":"Key Features","p":["\uD83D\uDD0D IDE Tracking: CodeGRITS tracks developers’ IDE interactions, including mouse clicks, keyboard inputs, etc.","\uD83D\uDC41️ Eye Tracking: CodeGRITS tracks developers’ eye gaze data from Tobii eye-tracking devices, and maps them to corresponding source code elements.","\uD83D\uDCBB Screen Recording: CodeGRITS simultaneously records developers’ screen for visualizing their behaviors.","\uD83D\uDD28 Research Toolkit: CodeGRITS provides a set of extra features for empirical SE researchers, including dynamic configuration, activity labeling, real-time data API, etc.","\uD83D\uDDC3️ Data Export: CodeGRITS exports data in XML format for further data analysis. See Data Format for more details."]},{"l":"Citation","p":["The paper of CodeGRITS has been accepted by ICSE 2024 Demonstrations Track. The PDF version is available here. Please cite the following if you use CodeGRITS in your research."]}],[{"l":"About","p":["CodeGRITS is professionally built and supported by a small dedicated team of HCI and SE researchers from SaNDwich Lab at the University of Notre Dame and Vanderbilt University. We are committed to keeping CodeGRITS open source and making it beneficial for the community.","The authors of CodeGRITS are Ningzhi Tang(equal contribution), Junwen An(equal contribution), Meng Chen, Aakash Bansal, Yu Huang, Collin McMillan, and Toby Jia-Jun Li. Technical support questions, bug reports, and feature requests are best started as a GitHub Issue.","We prepared a video demonstration of CodeGRITS for ICSE 2024."]},{"l":"Credits","p":["CodeGRITS would not be possible without the following commercial and open-source projects:","IntelliJ Platform SDK: CodeGRITS is built on top of the IntelliJ Platform.","Tobii Pro SDK: CodeGRITS uses the Tobii Pro SDK to collect eye gaze data from Tobii eye-tracking devices.","ReType: CodeGRITS documentation is built with Retype.","JavaCV: CodeGRITS uses JavaCV to implement the screen recorder.","Special thanks to the iTrace team. iTrace is a similar tool to CodeGRITS for collecting developers' eye gaze data in several IDEs, including Eclipse, Visual Studio, and Atom. We have learned a lot from their work and referred to part of their code. Different from iTrace, CodeGRITS is built for JetBrains IDEs and provides a set of extra functionalities (e.g., IDE tracking, screen recording, etc.) for empirical SE researchers."]},{"l":"License","p":["CodeGRITS is licensed under the MIT License. See the LICENSE for details."]},{"l":"Contact us","p":["Please feel free to contact us anytime if you have any questions or suggestions.","Email the developers Ningzhi Tang at ntang@nd.edu or Junwen An at jan2@nd.edu.","Start a GitHub Issue."]}],[{"l":"Usage Guide"},{"l":"Environment Requirements"},{"l":"Eye-tracking Device","p":["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."]},{"l":"IDE Compatibility","p":["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.","JetBrains IDEs","Version","IntelliJ IDEA","2022.2 - 2023.3","PyCharm","Clion","PhpStorm","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."]},{"l":"Python Environment","p":["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).","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."]},{"l":"Installation"},{"l":"Get the Plugin"},{"l":"Direct Download","p":["We provide the direct download link of the plugin zip file for the following JetBrains IDEs for convenience.","JetBrains IDEs","Version","Download Link","IntelliJ IDEA","2022.2 - 2023.3","Download","PyCharm"]},{"l":"Build from Source","p":["We also encourage you to build the plugin from the source code, especially for the IDEs that are not listed above.","Clone the repository to your local machine.","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.","Please refer to the Gradle IntelliJ Plugin - Configuration and Plugins Targeting IntelliJ Platform-Based IDEs for more details.","Open the command line and run ./gradlew build in the root folder to build the plugin.","Find the plugin zip file in the build/distributions folder."]},{"l":"Install the Plugin","p":["Open the JetBrains IDE, click File- Settings- Plugins- Install Plugin from Disk... to install the plugin zip file.","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."]},{"l":"Usage"},{"l":"Configuration","p":["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."]},{"l":"Functionalities","p":["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."]},{"l":"Settings","p":["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."]},{"l":"Preset Labels","p":["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.","After configuring the plugin, you can start tracking by clicking Tools- Start Tracking. You can also pause, or resume tracking by clicking Tools- Pause Tracking or Tools- Resume Tracking. CodeGRITS will not collect any data when it is paused. You can stop tracking by clicking Tools- Stop Tracking. The plugin will export data in XML format to the configured folder."]},{"l":"Trackers"},{"l":"IDE Tracker","p":["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."]},{"l":"Eye Tracker","p":["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.","CodeGRITS does not provide calibration for eye tracking. We highly recommend using Tobii Pro Eye Tracker Manager to conduct calibration before using eye tracking."]},{"l":"Screen Recorder","p":["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.","When using CodeGRITS's Screen Recorder, it is recommended to limit the setup to a single monitor. In cases where dual monitors are used, please position the IDE on the primary screen."]}],[{"l":"Data Format"},{"l":"Data Directory Structure","p":["Comment:","[OUTPUT_DIR] is the output directory specified in the configuration.","[START_TIMESTAMP] is the timestamp when the tracking starts.","[ARCHIVE_TIMESTAMP] is the timestamp when the archive is triggered.","video_clip_[k].mp4 is the video clip of the screen recording from the (k-1)-th pause (0-th pause is start) to the k-th pause.","frames.csv records the timestamp and clip number of each frame in the video clip.","All the timestamps used by CodeGRITS are Unix time in milliseconds, starting from 1970-01-01 00:00:00 UTC.","The editor coordinate system(e.g., line, column) of IntelliJ Platform starts from 0."]},{"l":"IDE Tracking","p":["action","actions","archive","archives","caret","carets","Comment:","Element: ide_tracking","environment","file","files","ide_tracking","mouse","mouses","selection","selections","Sub-element:","The root element of the ide_tracking.xml file.","typing","typings","visible_area","visible_areas"]},{"l":"Environment","p":["All path attributes in the data start with / are relative to project_path, otherwise they are absolute paths. Sometimes the path is empty, which means the data is irrelevant to any file or not successfully tracked.","Attribute:","Comment:","Element: environment","Example:","ide_name","ide_version","java_version","java_version will be replaced by python_version in PyCharm, etc.","os_name","project_name","project_path","scale_x","scale_x and scale_y are used to calculate the real screen resolution based on the screen_size. In the example above, the real screen resolution is (1536*1.25, 864*1.25) = (1920, 1080).","scale_y","screen_size"]},{"l":"Archives","p":["Element: archives","Sub-element: archive","Comment:","A real-time archive mechanism is implemented to track the state of the code file and console output at any timestamp during the development process. The file archive is triggered under two specific conditions: (1) When a file is opened or closed, or its selection changes; (2) When the content of the code in the main editor changes. The console archive is triggered when the console output changes (e.g., run class).","The archived data is stored in the archives directory, with the name [ARCHIVE_TIMESTAMP].archive, where[ARCHIVE_TIMESTAMP] is the timestamp when the archive is triggered. Relevant information is stored in the archive element, including the timestamp, the path of the file, and the remark.","Thus, if you want to know the state of the code file at a specific timestamp, you can find the archive file with the largest timestamp that is smaller than the target timestamp."]},{"l":"Archive","p":["Element: archive","Attribute:","id","timestamp","path: only used in fileArchive","remark: only used in fileArchive","Example:","Comment:","id could be fileArchive or consoleArchive.","remark could be fileOpened, fileClosed, fileSelectionChanged, contentChanged | OldFile, contentChanged | NewFile.","If the file is not a code file, i.e., the file extension is not in the \".java\", \".cpp\", \".c\", \".py\", \".rb\", \".js\", or \".md\", NotCodeFile | Fail would be added to the remark. This is to prevent archiving data files with large sizes.","If there are IO errors when archiving the file, IOException | Fail will be added to the remark."]},{"l":"Actions","p":["Element: actions","Sub-element: action","Comment:","The elements in actions are all the IDE-specific features, technically are all objects that implement the AnAction abstract class in IntelliJ IDEA. The range is diverse, from the basic editing features like EditorEnter, EditorBackSpace, clipboard features like EditorPaste, EditorCut, run features like RunClass, Stop, ToggleLineBreakpoint, Debug, navigating features like GotoDeclaration, Find, ShowIntentionActions, advanced IDE features like CompareTwoFiles, ReformatCode, to many others that cannot be fully listed here."]},{"l":"Action","p":["Element: action","Attribute:","id","timestamp","path","Example:","Comment:","CodeGRITS-related actions are also implemented as AnAction objects, and their id is prefixed with CodeGRITS, such as CodeGRITS.StartStopTracking, CodeGRITS.PauseResumeTracking, etc.","The \"add label\" action is also tracked here, with id as CodeGRITS.AddLabel.[LABEL_NAME], where the label name is pre-set in the configuration.","Other IntelliJ plugins may also implement their own AnAction objects, which will also be tracked here. For example, the copilot.applyInlays in the GitHub Copilot plugin."]},{"l":"Typings","p":["Element: typings","Sub-element: typing","Comment:","The typings element records the typing action of the user in the code editor. The data including the character, the timestamp, the path of the file, the line number, and the column number."]},{"l":"Typing","p":["Element: typing","Attribute:","character","timestamp","path","line","column","Example:"]},{"l":"Files","p":["Element: files","Sub-element: file","Comment:","The files element records the file-related actions including opening, closing, and selection change. The data including the timestamp and the path of the file."]},{"l":"File","p":["Element: file","Attribute:","id","timestamp","path: only used in fileOpened/ fileClosed","old_path: only used in selectionChanged","new_path: only used in selectionChanged","Example:","Comment:","id could be fileOpened, fileClosed, or selectionChanged."]},{"l":"Mouses","p":["Element: mouses","Sub-element: mouse","Comment:","The mouses element records the mouse-related actions including pressing, releasing, clicking, moving, and dragging. The data includes the timestamp, the path of the file, the x-coordinate, and the y-coordinate."]},{"l":"Mouse","p":["Element: mouse","Attribute:","id","timestamp","path","x","y","Example:","Comment:","id could be mousePressed, mouseReleased, mouseClicked, mouseMoved, or mouseDragged.","x and y are the coordinates relative to the screen_size in the environment, not the actual screen resolution."]},{"l":"Carets","p":["Element: carets","Sub-element: caret","Comment:","Caret is the cursor in the code editor. The carets element records the change of the caret position in the code editor. The data includes the timestamp, the path of the file, the line number, and the column number."]},{"l":"Caret","p":["Element: caret","Attribute:","id","timestamp","path","line","column","Example:","Comment:","id could only be caretPositionChanged."]},{"l":"Selections","p":["Element: selections","Sub-element: selection","Comment:","The selections element records data when the user selects a piece of code in the code editor. The data includes the timestamp, the path of the file, the start position, the end position, and the selected text."]},{"l":"Selection","p":["Element: selection","Attribute:","id","timestamp","path","start_position: line:column","end_position: line:column","selected_text","Example:","Comment:","id could only be selectionChanged."]},{"l":"Visible Areas","p":["Element: visible_areas","Sub-element: visible_area","Comment:","The visible_areas element records the visible area of the code editor."]},{"l":"Visible Area","p":["Element: visible_area Attribute:","id","timestamp","path","x","y","width","height","Comment:","id could only be visibleAreaChanged.","x and y are the coordinates of the left-top corner of the visible area in code editor, relative to the left-top corner of the code editor including the invisible part (i.e., the line 0 and column 0). The unit of x, y, width, and height is measured by screen_size in the environment, not the actual screen resolution.","The change of x and y is usually caused by scrolling code editor, which could be used to track the horizontal and vertical scrolling respectively. The change of width and height is usually caused by resizing code editor, which could be used to track the horizontal and vertical resizing respectively."]},{"l":"Eye Tracking","p":["eye_tracking","setting","gazes","gaze","left_eye","right_eye","location","ast_structure","level","Element: eye_tracking","Sub-element:","Comment:","The root element of the eye_tracking.xml file. CodeGRITS supports both Mouse simulation and Tobii Pro eye tracker devices.","Since Tobii Pro SDK does not support Java, we use the Python library tobii-research to collect eye tracking data and use Java ProcessBuilder to call the Python script to collect data. The Python interpreter is specified in the configuration."]},{"l":"Setting","p":["Element: setting","Attribute:","eye_tracker","sampling_rate","Example:","Comment:","eye_tracker could be Mouse for simulation, or a real Tobii Pro eye tracker device name (e.g., Tobii Pro Fusion), which is obtained from eyetracker.model in the tobii-research library.","sampling_rate is the sampling rate of the eye tracker in Hz, which is pre-set in the configuration and whose range could be in eyetracker.get_all_gaze_output_frequencies() called in the tobii-research library."]},{"l":"Gazes","p":["Element: gazes","Sub-element: gaze","Comment:","Collection of all gaze data."]},{"l":"Gaze","p":["Element: gaze","Sub-element:","left_eye","right_eye","location: only used when the gaze point can be mapped to its location in the code editor","ast_structure: only used when the gaze point cannot be mapped to its location in the code editor, and the code file is java.","Attribute:","timestamp","remark: only used when the gaze point cannot be mapped to location in the code editor","Example:","Comment:","When the gaze point cannot be mapped to its location in the code editor in the following 3 cases, the remark attribute is used:","The raw gaze point from the eye tracker is invalid. (i.e., nan). In this case, the remark is Fail | Invalid Gaze Point.","The code editor is not founded. In this case, the remark is Fail | No Editor.","The code editor is founded, but the gaze point is out of the code editor. In this case, the remark is Fail | Out of Text Editor."]},{"l":"Left Eye","p":["Element: left_eye","Attribute:","gaze_point_x","gaze_point_y","gaze_validity","pupil_diameter","pupil_validity","Example:","Comment:","gaze_point_x and gaze_point_y are the location on the screen, ranging from 0 to 1, where (0, 0) is the top-left corner of the screen, and (1, 1) is the bottom-right corner of the screen.","gaze_validity and pupil_validity are the validity of the gaze point and pupil diameter, which is binary, 0 for invalid, 1 for valid. When using a mouse to simulate eye tracker, gaze_validity is always 1.0, and pupil_validity is always 0.0.","pupil_diameter is the diameter of the pupil in mm, when using a mouse to simulate eye tracker, pupil_diameter is always 0."]},{"l":"Right Eye","p":["Element: right_eye","Attribute:","gaze_point_x","gaze_point_y","gaze_validity","pupil_diameter","pupil_validity","Example:","Comment:","gaze_point_x and gaze_point_y are the location on the screen, ranging from 0 to 1, where (0, 0) is the top-left corner of the screen, and (1, 1) is the bottom-right corner of the screen.","gaze_validity and pupil_validity are the validity of the gaze point and pupil diameter, which is binary, 0 for invalid, 1 for valid. When using a mouse to simulate eye tracker, gaze_validity is always 1.0, and pupil_validity is always 0.0.","pupil_diameter is the diameter of the pupil in mm, when using a mouse to simulate eye tracker, pupil_diameter is always 0."]},{"l":"Location","p":["Element: location","Attribute:","path","line","column","x","y","Example:","Comment:","x and y are the coordinates of the gaze relative to the top-left corner of the visible code editor, whose unit is same as the screen_size in environment, not the actual screen resolution.","line and column are the line number and column number of the gaze point in the code editor, which is calculated by xyToLogicalPosition(@NotNull Point p) method of Editor interface in the IntelliJ Platform SDK."]},{"l":"AST Structure","p":["Element: ast_structure","Sub-element: level: only used when the current token is different from the previous token","Attribute:","token","type","remark: only used when the current token is same as the previous token","Example:","Comment:","The abstract syntax tree (AST) of the code file is recorded in the ast_structure element. The AST is calculated by program structure interface (PSI) of IntelliJ Platform.","token is the text of the leaf node in the AST of the current gaze point, which is calculated by psiElement.getText().","type is the type of the leaf node, which is calculated by psiElement.getNode().getElementType().","remark is used when the current token is same as the previous token, which means the gaze point is still in the same leaf node. In this case, the remark is Same (Last Successful AST). We designed this mechanism to avoid eye_tracking.xml from being too large.","We calculate the parent nodes of the leaf node by psiElement.getParent() until the file level (i.e. PsiFile), and save them in the level element. In the previous example, the leaf node is PsiIdentifier:println, and its parent nodes are PsiReferenceExpression:System.out.println=> PsiMethodCallExpression:System.out.println(Hello world!)=> PsiExpressionStatement=> PsiCodeBlock=> PsiMethod:main=> PsiClass:Main. The original code text is"]},{"l":"Level","p":["Element: level","Attribute:","start: line:column","end: line:column","tag","Example:","Comment:","start and end are the start and end position of the AST node level in the code file, which is calculated by psiElement.getTextRange().","tag is the type of the AST node level, which is calculated by psiElement.toString()."]},{"l":"Screen Recording","p":["clip_[k].mp4","frames.csv"]},{"l":"Video Clips","p":["clip_[k].mp4","Comment:","The video clip of the screen recording from the (k-1)-th pause (0-th pause is start) to the k-th pause. We designed this mechanism to avoid the video file in the memory being too large especially when pausing the tracking for a long time."]},{"l":"Frames","p":["frames.csv","Column:","timestamp","frame_number","clip_number","Example:","Comment:","The frame rate is 12 fps.","frame_number is the frame number of the frame in its video clip.","clip_number is the number of the video clip to which the frame belongs.","We also record the timestamp of Start, Pause, Resume, and Stop actions in the frames.csv file, which could be used to separate each stage of the development process."]}],[{"l":"Developer Guide"},{"l":"Further Development","p":["Please refer to IntelliJ Platform SDK for more details. We also provide the JavaDoc of the source code. Feel free to contact us if you need any help."]},{"l":"Accommodating New IDEs","p":["See Build from Source."]},{"l":"Accommodating New Eye Trackers","p":["If you want to integrate other eye-tracking devices except for Tobii eye-tracking devices, you need to reimplement all Python scripts in the source code to get the right eye-tracking device information and eye gaze data using your eye tracker API.","Location","Method","/trackers/EyeTracker.java","setPythonScriptTobii()","/utils/AvailabilityChecker.java","checkPythonEnvironment(String pythonInterpreter)","checkEyeTracker(String pythonInterpreter)","getEyeTrackerName(String pythonInterpreter)","getFrequencies(String pythonInterpreter)"]},{"l":"Real-time Data API"},{"l":"Overview","p":["We provide a real-time data API for future JetBrains plugin developers and researchers to get real-time data from IDE tracker and eye tracker separately. The API is based on the IDE Tracker and Eye Tracker.","We provide an example project DataStreamReceiver that builds on top of the real-time data API. It is designed to receive the IDE and eye tracking data and directly visualize them in two separate windows. You could refer to its source code to learn how to use the API."]},{"l":"Configuration","p":["Before using the API, you first need to build CodeGRITS from source(See Build from Source). Then, find the folder ./build/idea-sandbox/plugins/CodeGRITS in the CodeGRITS project, which is the dependency of the API. You need to add it to the intellij section in build.gradle.kts file of your plugin project.","You also need to add the following to ./src/main/resources/META-INF/plugin.xml."]},{"l":"Quick Start","p":["To use the API, simply call the getInstance() method to get the instance of the IDE Tracker or Eye Tracker. Then, set the isRealTimeDataTransmitting to true to enable real-time data transmitting. After that, set the ideTrackerDataHandler or eyeTrackerDataHandler to handle the real-time data. Finally, call the startTracking() method to start tracking.","Element object is an XML element that is imported from org.w3c.dom.Element package."]},{"l":"IDE Tracker","p":["IDETracker.getInstance()","setIsRealTimeDataTransmitting(boolean isRealTimeDataTransmitting)","setIdeTrackerDataHandler(ConsumerElement ideTrackerDataHandler)","startTracking(Project project)"]},{"l":"Eye Tracker","p":["EyeTracker.getInstance()","setIsRealTimeDataTransmitting(boolean isRealTimeDataTransmitting)","setEyeTrackerDataHandler(ConsumerElement eyeTrackerDataHandler)","startTracking(Project project)"]}],[{"l":"Changelog","p":["Encountered a bug or have a suggestion? Please create a GitHub Issue."]},{"l":"v0.2.0","p":["Released on 2023-12-28.","Improve the implementation of Screen Recorder from JCodec to JavaCV.","Initial pre-mature release for CodeGRITS.","Fix the color distortion and the missing cursor issues of the screen recorder.","Fix several issues about the naming.","Add the logo of CodeGRITS."]},{"i":"v010","l":"v0.1.0","p":["Released on 2023-11-30.","Release for ICSE 2024 Demo review."]}],[{"i":"frequently-asked-questions-faq","l":"Frequently Asked Questions (FAQ)"},{"i":"q1-what-is-the-difference-between-codegrits-and-itrace","l":"Q1. What is the difference between CodeGRITS and iTrace?","p":["iTrace is a similar tool to CodeGRITS for collecting developers' eye gaze data in several IDEs, including Eclipse, Visual Studio, and Atom. However, CodeGRITS is built for JetBrains IDEs, which have increased popularity in the industry and academia.","CodeGRITS also provides a set of extra functionalities, notably IDE tracking and screen recording, for empirical SE researchers. See Trackers for more details."]},{"i":"q2-can-i-use-codegrits-without-an-eye-tracking-device","l":"Q2. Can I use CodeGRITS without an eye-tracking device?","p":["Yes. CodeGRITS provides mouse simulation as a substitute for eye gaze. You could also uncheck the Eye Tracking option in the configuration window to disable the eye tracker to only use the IDE tracker and screen recorder."]},{"i":"q3-how-to-integrate-other-eye-tracking-devices-with-codegrits","l":"Q3. How to integrate other eye-tracking devices with CodeGRITS?","p":["See Accommodating New Eye Trackers."]},{"i":"q4-how-to-use-codegrits-in-other-jetbrains-ides","l":"Q4. How to use CodeGRITS in other JetBrains IDEs?","p":["See Accommodating New IDEs."]},{"i":"q5-how-efficient-is-the-processing-of-raw-eye-gaze-data","l":"Q5. How efficient is the processing of raw eye gaze data?","p":["In CodeGRITS, the efficiency of the processing of gaze data is negligible. For each gaze, we calculate the average time from the timestamp in the raw data to the timestamp after all processing is complete. This processing primarily involves location mapping and upward traversal of the AST. The average delay is 4.32 ms, equating to delays of approximately 12.98% for 30Hz, 25.96% for 60Hz, and 51.92% for 120Hz eye gaze data. With such a high sampling frequency, meaningful changes in the content of the code editor's page are extremely rare within this short time frame, which ensures the accuracy of gaze processing. Moreover, compared to iTrace, our method of receiving data from the eye-tracking device is more efficient, ensuring that all sampled gazes are mapped without any loss."]},{"i":"q6-how-much-storage-space-does-codegrits-require","l":"Q6. How much storage space does CodeGRITS require?","p":["Generally speaking, a high sample frequency generates a large amount of gaze data. To conserve storage space, we only perform upward traversal of the AST of the first gaze and record the hierarchy structure, and mark the rest as same. This approach significantly reduces storage space. In a previous debugging study, we set the eye-tracking device's sample frequency to 60Hz, and during the 20-minute experiment, the eye-tracking data amounted to only about 40MB."]}],[{"l":"License","p":["MIT License","Copyright (c) 2023 SaNDwich Lab","Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:","The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.","THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE."]}]] \ No newline at end of file +[[{"l":"Welcome to CodeGRITS","p":["We would present CodeGRITS at ICSE 2024 Demo Track. Welcome to join us and discuss with us about it!","CodeGRITS has been primarily developed and tested on Windows and Linux, with only partial testing on macOS. There may be some unnoticed bugs on macOS. We have created a mac branch for this and have fixed some known issues. If you encounter additional issues on macOS, please feel free to report them to us.","CodeGRITS stands for G aze R ecording & I DE T racking S ystem. It's a plugin developed by the SaNDwich Lab and is specially designed for empirical software engineering researchers. CodeGRITS is built on top of IntelliJ Platform SDK, with wide compatibility with the entire family of JetBrains IDEs and Tobii eye-tracking devices, to track developers’ IDE interactions and eye gaze data. The source code is available on GitHub with Javadoc documentation.","The data collected by CodeGRITS can be used by empirical SE researchers to understand the behaviors of developers, especially those related to eye gaze. CodeGRITS also provides a real-time data API for future plugin developers and researchers to design context-aware programming support tools.","CodeGRITS is still in its developmental stage as a research tool. Our goal is to make it mature enough and beneficial for the community, particularly for those involved in empirical software engineering and eye tracking research. We encourage the community to contribute through GitHub Issue for any suggestions or issues, aiding in its improvement.","For any inquiries, please email us at ntang@nd.edu or jan2@nd.edu. If you're interested in using CodeGRITS in your research, don't hesitate to email us for setup support. We are delighted to provide tailored assistance based on your specific OS and JetBrains IDE environment."]},{"l":"Cross-platform and Multilingual Support","p":["CodeGRITS provides cross-platform support for Windows, macOS, and Linux, and is expected to be compatible with the entire family of JetBrains IDEs, including IntelliJ IDEA, PyCharm, WebStorm, etc.","CodeGRITS could extract the abstract syntax tree (AST) structure of eye gazes on multiple programming languages, as long as the IDE supports them, including Java, Python, C/C++, JavaScript, etc."]},{"l":"Key Features","p":["\uD83D\uDD0D IDE Tracking: CodeGRITS tracks developers’ IDE interactions, including mouse clicks, keyboard inputs, etc.","\uD83D\uDC41️ Eye Tracking: CodeGRITS tracks developers’ eye gaze data from Tobii eye-tracking devices, and maps them to corresponding source code elements.","\uD83D\uDCBB Screen Recording: CodeGRITS simultaneously records developers’ screen for visualizing their behaviors.","\uD83D\uDD28 Research Toolkit: CodeGRITS provides a set of extra features for empirical SE researchers, including dynamic configuration, activity labeling, real-time data API, etc.","\uD83D\uDDC3️ Data Export: CodeGRITS exports data in XML format for further data analysis. See Data Format for more details."]},{"l":"Citation","p":["The paper of CodeGRITS has been accepted by ICSE 2024 Demonstrations Track. The PDF version is available here. Please cite the following if you use CodeGRITS in your research."]}],[{"l":"About","p":["CodeGRITS is professionally built and supported by a small dedicated team of HCI and SE researchers from SaNDwich Lab at the University of Notre Dame and Vanderbilt University. We are committed to keeping CodeGRITS open source and making it beneficial for the community.","The authors of CodeGRITS are Ningzhi Tang(equal contribution), Junwen An(equal contribution), Meng Chen, Aakash Bansal, Yu Huang, Collin McMillan, and Toby Jia-Jun Li. Technical support questions, bug reports, and feature requests are best started as a GitHub Issue.","We prepared a video demonstration of CodeGRITS for ICSE 2024."]},{"l":"Credits","p":["CodeGRITS would not be possible without the following commercial and open-source projects:","IntelliJ Platform SDK: CodeGRITS is built on top of the IntelliJ Platform.","Tobii Pro SDK: CodeGRITS uses the Tobii Pro SDK to collect eye gaze data from Tobii eye-tracking devices.","ReType: CodeGRITS documentation is built with Retype.","JavaCV: CodeGRITS uses JavaCV to implement the screen recorder.","Special thanks to the iTrace team. iTrace is a similar tool to CodeGRITS for collecting developers' eye gaze data in several IDEs, including Eclipse, Visual Studio, and Atom. We have learned a lot from their work and referred to part of their code. Different from iTrace, CodeGRITS is built for JetBrains IDEs and provides a set of extra functionalities (e.g., IDE tracking, screen recording, etc.) for empirical SE researchers."]},{"l":"License","p":["CodeGRITS is licensed under the MIT License. See the LICENSE for details."]},{"l":"Contact us","p":["Please feel free to contact us anytime if you have any questions or suggestions.","Email the developers Ningzhi Tang at ntang@nd.edu or Junwen An at jan2@nd.edu.","Start a GitHub Issue."]}],[{"l":"Usage Guide"},{"l":"Environment Requirements"},{"l":"Eye-tracking Device","p":["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."]},{"l":"IDE Compatibility","p":["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.","JetBrains IDEs","Version","IntelliJ IDEA","2022.2 - 2023.3","PyCharm","Clion","PhpStorm","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."]},{"l":"Python Environment","p":["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).","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."]},{"l":"Installation"},{"l":"Get the Plugin"},{"l":"Direct Download","p":["We provide the direct download link of the plugin zip file for the following JetBrains IDEs for convenience.","JetBrains IDEs","Version","Download Link","IntelliJ IDEA","2022.2 - 2023.3","Download","PyCharm"]},{"l":"Build from Source","p":["We also encourage you to build the plugin from the source code, especially for the IDEs that are not listed above.","Clone the repository to your local machine.","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.","Please refer to the Gradle IntelliJ Plugin - Configuration and Plugins Targeting IntelliJ Platform-Based IDEs for more details.","Open the command line and run ./gradlew build in the root folder to build the plugin.","Find the plugin zip file in the build/distributions folder."]},{"l":"Install the Plugin","p":["Open the JetBrains IDE, click File- Settings- Plugins- Install Plugin from Disk... to install the plugin zip file.","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."]},{"l":"Usage"},{"l":"Configuration","p":["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."]},{"l":"Functionalities","p":["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."]},{"l":"Settings","p":["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."]},{"l":"Preset Labels","p":["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.","After configuring the plugin, you can start tracking by clicking Tools- Start Tracking. You can also pause, or resume tracking by clicking Tools- Pause Tracking or Tools- Resume Tracking. CodeGRITS will not collect any data when it is paused. You can stop tracking by clicking Tools- Stop Tracking. The plugin will export data in XML format to the configured folder."]},{"l":"Trackers"},{"l":"IDE Tracker","p":["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."]},{"l":"Eye Tracker","p":["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.","CodeGRITS does not provide calibration for eye tracking. We highly recommend using Tobii Pro Eye Tracker Manager to conduct calibration before using eye tracking."]},{"l":"Screen Recorder","p":["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.","When using CodeGRITS's Screen Recorder, it is recommended to limit the setup to a single monitor. In cases where dual monitors are used, please position the IDE on the primary screen."]}],[{"l":"Data Format"},{"l":"Data Directory Structure","p":["Comment:","[OUTPUT_DIR] is the output directory specified in the configuration.","[START_TIMESTAMP] is the timestamp when the tracking starts.","[ARCHIVE_TIMESTAMP] is the timestamp when the archive is triggered.","video_clip_[k].mp4 is the video clip of the screen recording from the (k-1)-th pause (0-th pause is start) to the k-th pause.","frames.csv records the timestamp and clip number of each frame in the video clip.","All the timestamps used by CodeGRITS are Unix time in milliseconds, starting from 1970-01-01 00:00:00 UTC.","The editor coordinate system(e.g., line, column) of IntelliJ Platform starts from 0."]},{"l":"IDE Tracking","p":["action","actions","archive","archives","caret","carets","Comment:","Element: ide_tracking","environment","file","files","ide_tracking","mouse","mouses","selection","selections","Sub-element:","The root element of the ide_tracking.xml file.","typing","typings","visible_area","visible_areas"]},{"l":"Environment","p":["All path attributes in the data start with / are relative to project_path, otherwise they are absolute paths. Sometimes the path is empty, which means the data is irrelevant to any file or not successfully tracked.","Attribute:","Comment:","Element: environment","Example:","ide_name","ide_version","java_version","java_version will be replaced by python_version in PyCharm, etc.","os_name","project_name","project_path","scale_x","scale_x and scale_y are used to calculate the real screen resolution based on the screen_size. In the example above, the real screen resolution is (1536*1.25, 864*1.25) = (1920, 1080).","scale_y","screen_size"]},{"l":"Archives","p":["Element: archives","Sub-element: archive","Comment:","A real-time archive mechanism is implemented to track the state of the code file and console output at any timestamp during the development process. The file archive is triggered under two specific conditions: (1) When a file is opened or closed, or its selection changes; (2) When the content of the code in the main editor changes. The console archive is triggered when the console output changes (e.g., run class).","The archived data is stored in the archives directory, with the name [ARCHIVE_TIMESTAMP].archive, where[ARCHIVE_TIMESTAMP] is the timestamp when the archive is triggered. Relevant information is stored in the archive element, including the timestamp, the path of the file, and the remark.","Thus, if you want to know the state of the code file at a specific timestamp, you can find the archive file with the largest timestamp that is smaller than the target timestamp."]},{"l":"Archive","p":["Element: archive","Attribute:","id","timestamp","path: only used in fileArchive","remark: only used in fileArchive","Example:","Comment:","id could be fileArchive or consoleArchive.","remark could be fileOpened, fileClosed, fileSelectionChanged, contentChanged | OldFile, contentChanged | NewFile.","If the file is not a code file, i.e., the file extension is not in the \".java\", \".cpp\", \".c\", \".py\", \".rb\", \".js\", or \".md\", NotCodeFile | Fail would be added to the remark. This is to prevent archiving data files with large sizes.","If there are IO errors when archiving the file, IOException | Fail will be added to the remark."]},{"l":"Actions","p":["Element: actions","Sub-element: action","Comment:","The elements in actions are all the IDE-specific features, technically are all objects that implement the AnAction abstract class in IntelliJ IDEA. The range is diverse, from the basic editing features like EditorEnter, EditorBackSpace, clipboard features like EditorPaste, EditorCut, run features like RunClass, Stop, ToggleLineBreakpoint, Debug, navigating features like GotoDeclaration, Find, ShowIntentionActions, advanced IDE features like CompareTwoFiles, ReformatCode, to many others that cannot be fully listed here."]},{"l":"Action","p":["Element: action","Attribute:","id","timestamp","path","Example:","Comment:","CodeGRITS-related actions are also implemented as AnAction objects, and their id is prefixed with CodeGRITS, such as CodeGRITS.StartStopTracking, CodeGRITS.PauseResumeTracking, etc.","The \"add label\" action is also tracked here, with id as CodeGRITS.AddLabel.[LABEL_NAME], where the label name is pre-set in the configuration.","Other IntelliJ plugins may also implement their own AnAction objects, which will also be tracked here. For example, the copilot.applyInlays in the GitHub Copilot plugin."]},{"l":"Typings","p":["Element: typings","Sub-element: typing","Comment:","The typings element records the typing action of the user in the code editor. The data including the character, the timestamp, the path of the file, the line number, and the column number."]},{"l":"Typing","p":["Element: typing","Attribute:","character","timestamp","path","line","column","Example:"]},{"l":"Files","p":["Element: files","Sub-element: file","Comment:","The files element records the file-related actions including opening, closing, and selection change. The data including the timestamp and the path of the file."]},{"l":"File","p":["Element: file","Attribute:","id","timestamp","path: only used in fileOpened/ fileClosed","old_path: only used in selectionChanged","new_path: only used in selectionChanged","Example:","Comment:","id could be fileOpened, fileClosed, or selectionChanged."]},{"l":"Mouses","p":["Element: mouses","Sub-element: mouse","Comment:","The mouses element records the mouse-related actions including pressing, releasing, clicking, moving, and dragging. The data includes the timestamp, the path of the file, the x-coordinate, and the y-coordinate."]},{"l":"Mouse","p":["Element: mouse","Attribute:","id","timestamp","path","x","y","Example:","Comment:","id could be mousePressed, mouseReleased, mouseClicked, mouseMoved, or mouseDragged.","x and y are the coordinates relative to the screen_size in the environment, not the actual screen resolution."]},{"l":"Carets","p":["Element: carets","Sub-element: caret","Comment:","Caret is the cursor in the code editor. The carets element records the change of the caret position in the code editor. The data includes the timestamp, the path of the file, the line number, and the column number."]},{"l":"Caret","p":["Element: caret","Attribute:","id","timestamp","path","line","column","Example:","Comment:","id could only be caretPositionChanged."]},{"l":"Selections","p":["Element: selections","Sub-element: selection","Comment:","The selections element records data when the user selects a piece of code in the code editor. The data includes the timestamp, the path of the file, the start position, the end position, and the selected text."]},{"l":"Selection","p":["Element: selection","Attribute:","id","timestamp","path","start_position: line:column","end_position: line:column","selected_text","Example:","Comment:","id could only be selectionChanged."]},{"l":"Visible Areas","p":["Element: visible_areas","Sub-element: visible_area","Comment:","The visible_areas element records the visible area of the code editor."]},{"l":"Visible Area","p":["Element: visible_area Attribute:","id","timestamp","path","x","y","width","height","Comment:","id could only be visibleAreaChanged.","x and y are the coordinates of the left-top corner of the visible area in code editor, relative to the left-top corner of the code editor including the invisible part (i.e., the line 0 and column 0). The unit of x, y, width, and height is measured by screen_size in the environment, not the actual screen resolution.","The change of x and y is usually caused by scrolling code editor, which could be used to track the horizontal and vertical scrolling respectively. The change of width and height is usually caused by resizing code editor, which could be used to track the horizontal and vertical resizing respectively."]},{"l":"Eye Tracking","p":["eye_tracking","setting","gazes","gaze","left_eye","right_eye","location","ast_structure","level","Element: eye_tracking","Sub-element:","Comment:","The root element of the eye_tracking.xml file. CodeGRITS supports both Mouse simulation and Tobii Pro eye tracker devices.","Since Tobii Pro SDK does not support Java, we use the Python library tobii-research to collect eye tracking data and use Java ProcessBuilder to call the Python script to collect data. The Python interpreter is specified in the configuration."]},{"l":"Setting","p":["Element: setting","Attribute:","eye_tracker","sampling_rate","Example:","Comment:","eye_tracker could be Mouse for simulation, or a real Tobii Pro eye tracker device name (e.g., Tobii Pro Fusion), which is obtained from eyetracker.model in the tobii-research library.","sampling_rate is the sampling rate of the eye tracker in Hz, which is pre-set in the configuration and whose range could be in eyetracker.get_all_gaze_output_frequencies() called in the tobii-research library."]},{"l":"Gazes","p":["Element: gazes","Sub-element: gaze","Comment:","Collection of all gaze data."]},{"l":"Gaze","p":["Element: gaze","Sub-element:","left_eye","right_eye","location: only used when the gaze point can be mapped to its location in the code editor","ast_structure: only used when the gaze point cannot be mapped to its location in the code editor, and the code file is java.","Attribute:","timestamp","remark: only used when the gaze point cannot be mapped to location in the code editor","Example:","Comment:","When the gaze point cannot be mapped to its location in the code editor in the following 3 cases, the remark attribute is used:","The raw gaze point from the eye tracker is invalid. (i.e., nan). In this case, the remark is Fail | Invalid Gaze Point.","The code editor is not founded. In this case, the remark is Fail | No Editor.","The code editor is founded, but the gaze point is out of the code editor. In this case, the remark is Fail | Out of Text Editor."]},{"l":"Left Eye","p":["Element: left_eye","Attribute:","gaze_point_x","gaze_point_y","gaze_validity","pupil_diameter","pupil_validity","Example:","Comment:","gaze_point_x and gaze_point_y are the location on the screen, ranging from 0 to 1, where (0, 0) is the top-left corner of the screen, and (1, 1) is the bottom-right corner of the screen.","gaze_validity and pupil_validity are the validity of the gaze point and pupil diameter, which is binary, 0 for invalid, 1 for valid. When using a mouse to simulate eye tracker, gaze_validity is always 1.0, and pupil_validity is always 0.0.","pupil_diameter is the diameter of the pupil in mm, when using a mouse to simulate eye tracker, pupil_diameter is always 0."]},{"l":"Right Eye","p":["Element: right_eye","Attribute:","gaze_point_x","gaze_point_y","gaze_validity","pupil_diameter","pupil_validity","Example:","Comment:","gaze_point_x and gaze_point_y are the location on the screen, ranging from 0 to 1, where (0, 0) is the top-left corner of the screen, and (1, 1) is the bottom-right corner of the screen.","gaze_validity and pupil_validity are the validity of the gaze point and pupil diameter, which is binary, 0 for invalid, 1 for valid. When using a mouse to simulate eye tracker, gaze_validity is always 1.0, and pupil_validity is always 0.0.","pupil_diameter is the diameter of the pupil in mm, when using a mouse to simulate eye tracker, pupil_diameter is always 0."]},{"l":"Location","p":["Element: location","Attribute:","path","line","column","x","y","Example:","Comment:","x and y are the coordinates of the gaze relative to the top-left corner of the visible code editor, whose unit is same as the screen_size in environment, not the actual screen resolution.","line and column are the line number and column number of the gaze point in the code editor, which is calculated by xyToLogicalPosition(@NotNull Point p) method of Editor interface in the IntelliJ Platform SDK."]},{"l":"AST Structure","p":["Element: ast_structure","Sub-element: level: only used when the current token is different from the previous token","Attribute:","token","type","remark: only used when the current token is same as the previous token","Example:","Comment:","The abstract syntax tree (AST) of the code file is recorded in the ast_structure element. The AST is calculated by program structure interface (PSI) of IntelliJ Platform.","token is the text of the leaf node in the AST of the current gaze point, which is calculated by psiElement.getText().","type is the type of the leaf node, which is calculated by psiElement.getNode().getElementType().","remark is used when the current token is same as the previous token, which means the gaze point is still in the same leaf node. In this case, the remark is Same (Last Successful AST). We designed this mechanism to avoid eye_tracking.xml from being too large.","We calculate the parent nodes of the leaf node by psiElement.getParent() until the file level (i.e. PsiFile), and save them in the level element. In the previous example, the leaf node is PsiIdentifier:println, and its parent nodes are PsiReferenceExpression:System.out.println=> PsiMethodCallExpression:System.out.println(Hello world!)=> PsiExpressionStatement=> PsiCodeBlock=> PsiMethod:main=> PsiClass:Main. The original code text is"]},{"l":"Level","p":["Element: level","Attribute:","start: line:column","end: line:column","tag","Example:","Comment:","start and end are the start and end position of the AST node level in the code file, which is calculated by psiElement.getTextRange().","tag is the type of the AST node level, which is calculated by psiElement.toString()."]},{"l":"Screen Recording","p":["clip_[k].mp4","frames.csv"]},{"l":"Video Clips","p":["clip_[k].mp4","Comment:","The video clip of the screen recording from the (k-1)-th pause (0-th pause is start) to the k-th pause. We designed this mechanism to avoid the video file in the memory being too large especially when pausing the tracking for a long time."]},{"l":"Frames","p":["frames.csv","Column:","timestamp","frame_number","clip_number","Example:","Comment:","The frame rate is 12 fps.","frame_number is the frame number of the frame in its video clip.","clip_number is the number of the video clip to which the frame belongs.","We also record the timestamp of Start, Pause, Resume, and Stop actions in the frames.csv file, which could be used to separate each stage of the development process."]}],[{"l":"Developer Guide"},{"l":"Further Development","p":["Please refer to IntelliJ Platform SDK for more details. We also provide the JavaDoc of the source code. Feel free to contact us if you need any help."]},{"l":"Accommodating New IDEs","p":["See Build from Source."]},{"l":"Accommodating New Eye Trackers","p":["If you want to integrate other eye-tracking devices except for Tobii eye-tracking devices, you need to reimplement all Python scripts in the source code to get the right eye-tracking device information and eye gaze data using your eye tracker API.","Location","Method","/trackers/EyeTracker.java","setPythonScriptTobii()","/utils/AvailabilityChecker.java","checkPythonEnvironment(String pythonInterpreter)","checkEyeTracker(String pythonInterpreter)","getEyeTrackerName(String pythonInterpreter)","getFrequencies(String pythonInterpreter)"]},{"l":"Real-time Data API"},{"l":"Overview","p":["We provide a real-time data API for future JetBrains plugin developers and researchers to get real-time data from IDE tracker and eye tracker separately. The API is based on the IDE Tracker and Eye Tracker.","We provide an example project DataStreamReceiver that builds on top of the real-time data API. It is designed to receive the IDE and eye tracking data and directly visualize them in two separate windows. You could refer to its source code to learn how to use the API."]},{"l":"Configuration","p":["Before using the API, you first need to build CodeGRITS from source(See Build from Source). Then, find the folder ./build/idea-sandbox/plugins/CodeGRITS in the CodeGRITS project, which is the dependency of the API. You need to add it to the intellij section in build.gradle.kts file of your plugin project.","You also need to add the following to ./src/main/resources/META-INF/plugin.xml."]},{"l":"Quick Start","p":["To use the API, simply call the getInstance() method to get the instance of the IDE Tracker or Eye Tracker. Then, set the isRealTimeDataTransmitting to true to enable real-time data transmitting. After that, set the ideTrackerDataHandler or eyeTrackerDataHandler to handle the real-time data. Finally, call the startTracking() method to start tracking.","Element object is an XML element that is imported from org.w3c.dom.Element package."]},{"l":"IDE Tracker","p":["IDETracker.getInstance()","setIsRealTimeDataTransmitting(boolean isRealTimeDataTransmitting)","setIdeTrackerDataHandler(ConsumerElement ideTrackerDataHandler)","startTracking(Project project)"]},{"l":"Eye Tracker","p":["EyeTracker.getInstance()","setIsRealTimeDataTransmitting(boolean isRealTimeDataTransmitting)","setEyeTrackerDataHandler(ConsumerElement eyeTrackerDataHandler)","startTracking(Project project)"]}],[{"l":"Changelog","p":["Encountered a bug or have a suggestion? Please create a GitHub Issue."]},{"l":"v0.2.0","p":["Released on 2023-12-28.","Improve the implementation of Screen Recorder from JCodec to JavaCV.","Initial pre-mature release for CodeGRITS.","Fix the color distortion and the missing cursor issues of the screen recorder.","Fix several issues about the naming.","Add the logo of CodeGRITS."]},{"i":"v010","l":"v0.1.0","p":["Released on 2023-11-30.","Release for ICSE 2024 Demo review."]}],[{"i":"frequently-asked-questions-faq","l":"Frequently Asked Questions (FAQ)"},{"i":"q1-what-is-the-difference-between-codegrits-and-itrace","l":"Q1. What is the difference between CodeGRITS and iTrace?","p":["iTrace is a similar tool to CodeGRITS for collecting developers' eye gaze data in several IDEs, including Eclipse, Visual Studio, and Atom. However, CodeGRITS is built for JetBrains IDEs, which have increased popularity in the industry and academia.","CodeGRITS also provides a set of extra functionalities, notably IDE tracking and screen recording, for empirical SE researchers. See Trackers for more details."]},{"i":"q2-can-i-use-codegrits-without-an-eye-tracking-device","l":"Q2. Can I use CodeGRITS without an eye-tracking device?","p":["Yes. CodeGRITS provides mouse simulation as a substitute for eye gaze. You could also uncheck the Eye Tracking option in the configuration window to disable the eye tracker to only use the IDE tracker and screen recorder."]},{"i":"q3-how-to-integrate-other-eye-tracking-devices-with-codegrits","l":"Q3. How to integrate other eye-tracking devices with CodeGRITS?","p":["See Accommodating New Eye Trackers."]},{"i":"q4-how-to-use-codegrits-in-other-jetbrains-ides","l":"Q4. How to use CodeGRITS in other JetBrains IDEs?","p":["See Accommodating New IDEs."]},{"i":"q5-how-efficient-is-the-processing-of-raw-eye-gaze-data","l":"Q5. How efficient is the processing of raw eye gaze data?","p":["In CodeGRITS, the efficiency of the processing of gaze data is negligible. For each gaze, we calculate the average time from the timestamp in the raw data to the timestamp after all processing is complete. This processing primarily involves location mapping and upward traversal of the AST. The average delay is 4.32 ms, equating to delays of approximately 12.98% for 30Hz, 25.96% for 60Hz, and 51.92% for 120Hz eye gaze data. With such a high sampling frequency, meaningful changes in the content of the code editor's page are extremely rare within this short time frame, which ensures the accuracy of gaze processing. Moreover, compared to iTrace, our method of receiving data from the eye-tracking device is more efficient, ensuring that all sampled gazes are mapped without any loss."]},{"i":"q6-how-much-storage-space-does-codegrits-require","l":"Q6. How much storage space does CodeGRITS require?","p":["Generally speaking, a high sample frequency generates a large amount of gaze data. To conserve storage space, we only perform upward traversal of the AST of the first gaze and record the hierarchy structure, and mark the rest as same. This approach significantly reduces storage space. In a previous debugging study, we set the eye-tracking device's sample frequency to 60Hz, and during the 20-minute experiment, the eye-tracking data amounted to only about 40MB."]}],[{"l":"License","p":["MIT License","Copyright (c) 2023 SaNDwich Lab","Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:","The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.","THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE."]}]] \ No newline at end of file diff --git a/sitemap.xml.gz b/sitemap.xml.gz index 56ad974053acd24426861cd1478b420b70e5b7ca..c14c6df334794f32d76e4cf20e09c4330ee92f65 100644 GIT binary patch literal 704 zcmV;x0zds9iwFP!000001Jv3}bDJ;_0N{Img@-#2gN+~KIET)((`%bvdQ+se&_p0A z3ESzf??Py&Npot|8SM#yCHO3@7KDAcyS9392J4jRZj)tJBn#-c5vr57$(Q^0={C7L z-W&$29ry)S?%ZwCc;D~y{BpTuPI+iq?=oX$?s$VcE}swPMYcAMZcshkUF%w_?t> zMjXqcT%|>o7VGC+Lv_aXnaH!||s@mC%JXV9hx`|q+M z+iXJ82FE0%a!>+-;OdY#_Fx7dgjEF{PUcy9GPY$waP>AMPAd+b3o@8>84|`D)=8WO zG6ZcMbP}A{w-BgR(18?&yAY}>=qO5Kq=t%@HDh91tu`lK*UN0o*8!|SsZ$3stvO!K zflFic^^8Aa5{?wufbLT)#XH0XA6L!_E~y*Zmf0r)Qf~p`Wje5mY4sh%beD@4I(VgV z3Z0qK>_KTfF+OneN3gMzjT7L3dlS9Xf@WTwp=Z94;C=jki|dOE){7rH=l%H8)=O^O zxr=d+D_7hKfjI$#ciN}smDUV>{Ag~vlaf@rxMu_2*#M^-c#FZTIx=+Unf1<_o*JA? zj(ZJ`JIhUB0M_O31ap}HRtZ8_$1wsr3*1;i0!(JA{UMHfuBlGIH9aW}Kg$un?sx-R zkkZoX+me*FBBfoC(ymEqYf{<`Deab&c1KA|D&3OGwxp6Rsa#7c)so7zq!Mk!d6t{D zHyw0-{52A+7m8^kNqC=MKoSCzS){*Vj(eGoR6N-n5z#Zr#K9|X+%dp^DiwFP!000001Ju~da+@#|2H<_3!owc0v5ha|IE&7-(`}n>x>Lll&{RmO zBz)=9_h8dbl4jMaGde475`0EFKj7WNxl@xPI4_O9&t}Cmn}Ft~ky_kmUmoA*>+E5F zx9gqq5GL4I`}?d7!EVd)bUGDY2I!deg>jP64f{Mu)> z*=)+|(QJP=nG9DNmbj)2-w*9Qc0dsbCxb793~m2ZNK?MUeIGu3eEeMQ%AxJpi}}!* zW?xOKMLwP7RrNTlx693TvHptf#-q2k)=7gWz3lOK@51EU-rf8}Z52+CM+|1O&r zt5r-|@0oyH^s<2{xH=||J()g4Va=lsCkre;7}v2VxOyEErz8jMqYP$U#f0&eX@O-R zV$haRi{QY%$3QKj4rF7vkD;1J9YtY`P%!6J%~-RZFIER$*Rx{C>j>7U)awmoN^!iL z2cM_vvy6Yk5Ka`>g0eZTr8~q1UssM2PPy;9j=2i~X>b7PGCerSl>7nB^(mJwl$*{P z4LS^U1THklHiCqg8-0+15O_?f^o#5bbK2z=95V5XtAq=T>jbd)!9WM=InDs>fE(A4 z0F$YgZ*KKNE;Y@GSN8c)q$}P66_uv5Q?e@_lH5s}O%mp8er3NPxa<9Q@r<~Lc zob!WJ@M}HcfA8PGPDyEL-P?+kc1}vWAf;WB($=K3D^l7uDeZ=mmQ>u5N?TH4ODbzg iMJ=hMB^9*)IcKj64`F}z6954J{{sNP3^{U - + @@ -32,12 +32,12 @@ - + - + - - + +