From 0e30009c92e31d26dd915e09d52b851ee42705ef Mon Sep 17 00:00:00 2001 From: Tommaso Ghilardi Date: Wed, 5 Nov 2025 14:38:29 +0000 Subject: [PATCH 01/19] initial documentation restiling --- {Stimuli => CalibrationStimuli}/cute_cat.svg | 0 {Stimuli => CalibrationStimuli}/cute_cow.svg | 0 {Stimuli => CalibrationStimuli}/cute_dog.svg | 0 .../cute_elephant.svg | 0 {Stimuli => CalibrationStimuli}/cute_elk.svg | 0 .../cute_hippo.svg | 0 .../cute_ladybug.svg | 0 .../cute_panda.svg | 0 .../cute_penguin.svg | 0 {Stimuli => CalibrationStimuli}/cute_pig.svg | 0 .../cute_sheep.svg | 0 DeToX.egg-info/PKG-INFO | 30 - DeToX.egg-info/SOURCES.txt | 14 - DeToX.egg-info/requires.txt | 2 - Documentation/.gitignore | 1 + .../Draft}/Settings.qmd | 0 Documentation/Vignettes/GettingStarted.qmd | 187 ++ Documentation/Vignettes/Installation.qmd | 125 + {docs => Documentation}/_quarto.yml | 60 +- .../api/BaseCalibrationSession.qmd | 0 .../api/ETSettings.AnimationSettings.qmd | 0 .../api/ETSettings.CalibrationColors.qmd | 0 .../api/ETSettings.FontSizeMultipliers.qmd | 0 .../api/ETSettings.UIElementSizes.qmd | 0 .../api/ETracker.calibrate.qmd | 0 .../api/ETracker.gaze_contingent.qmd | 0 .../api/ETracker.get_gaze_position.qmd | 0 .../api/ETracker.load_calibration.qmd | 0 {docs => Documentation}/api/ETracker.qmd | 0 .../api/ETracker.record_event.qmd | 0 .../api/ETracker.save_calibration.qmd | 0 .../api/ETracker.save_data.qmd | 0 .../api/ETracker.show_status.qmd | 0 .../api/ETracker.start_recording.qmd | 0 .../api/ETracker.stop_recording.qmd | 0 {docs => Documentation}/api/InfantStimuli.qmd | 0 .../api/MouseCalibrationSession.qmd | 0 {docs => Documentation}/api/NicePrint.qmd | 0 .../api/TobiiCalibrationSession.qmd | 0 {docs => Documentation}/api/_sidebar.yml | 0 .../api/convert_height_to_units.qmd | 0 .../api/get_psychopy_pos.qmd | 0 .../api/get_psychopy_pos_from_trackbox.qmd | 0 {docs => Documentation}/api/get_tobii_pos.qmd | 0 {docs => Documentation}/api/index.qmd | 2 +- {docs => Documentation}/api/pix2tobii.qmd | 0 .../api/psychopy_to_pixels.qmd | 0 {docs => Documentation}/api/tobii2pix.qmd | 0 {docs => Documentation}/index.qmd | 11 +- Documentation/objects.json | 1 + .../resources}/full_logo.png | Bin {docs => Documentation}/styles.scss | 0 _site/Vignettes/GettingStarted.html | 1126 +++++++++ _site/Vignettes/Installation.html | 1010 ++++++++ .../api/BaseCalibrationSession.html | 1061 ++++----- _site/api/ETSettings.AnimationSettings.html | 1137 +++++++++ _site/api/ETSettings.CalibrationColors.html | 1114 +++++++++ _site/api/ETSettings.FontSizeMultipliers.html | 1094 +++++++++ _site/api/ETSettings.UIElementSizes.html | 1141 +++++++++ .../api/ETracker.calibrate.html | 396 +++- .../api/ETracker.gaze_contingent.html | 418 +++- _site/api/ETracker.get_gaze_position.html | 1167 +++++++++ _site/api/ETracker.html | 2094 +++++++++++++++++ .../api/ETracker.load_calibration.html | 386 ++- .../api/ETracker.record_event.html | 382 ++- .../api/ETracker.save_calibration.html | 382 ++- .../api/ETracker.save_data.html | 364 ++- .../api/ETracker.show_status.html | 375 ++- .../api/ETracker.start_recording.html | 425 +++- .../api/ETracker.stop_recording.html | 375 ++- _site/api/InfantStimuli.html | 1306 ++++++++++ _site/api/MouseCalibrationSession.html | 1159 +++++++++ .../index.html => _site/api/NicePrint.html | 479 +++- _site/api/TobiiCalibrationSession.html | 1152 +++++++++ _site/api/convert_height_to_units.html | 1119 +++++++++ _site/api/get_psychopy_pos.html | 1160 +++++++++ _site/api/get_psychopy_pos_from_trackbox.html | 1150 +++++++++ _site/api/get_tobii_pos.html | 1145 +++++++++ _site/api/index.html | 1279 ++++++++++ _site/api/pix2tobii.html | 1112 +++++++++ _site/api/psychopy_to_pixels.html | 1115 +++++++++ .../api/tobii2pix.html | 461 +++- {docs/_site => _site}/index.html | 301 ++- _site/resources/full_logo.png | Bin 0 -> 8765 bytes _site/search.json | 1309 +++++++++++ _site/site_libs/bootstrap/bootstrap-icons.css | 2078 ++++++++++++++++ .../site_libs/bootstrap/bootstrap-icons.woff | Bin 0 -> 176200 bytes _site/site_libs/bootstrap/bootstrap.min.css | 12 + _site/site_libs/bootstrap/bootstrap.min.js | 7 + _site/site_libs/clipboard/clipboard.min.js | 7 + .../cookie-consent/cookie-consent.css | 4 + .../cookie-consent/cookie-consent.js | 1 + _site/site_libs/quarto-html/anchor.min.js | 9 + _site/site_libs/quarto-html/popper.min.js | 6 + .../quarto-syntax-highlighting.css | 189 ++ .../site_libs/quarto-html/quarto.js | 0 _site/site_libs/quarto-html/tippy.css | 1 + _site/site_libs/quarto-html/tippy.umd.min.js | 2 + _site/site_libs/quarto-nav/headroom.min.js | 7 + _site/site_libs/quarto-nav/quarto-nav.js | 325 +++ .../quarto-search/autocomplete.umd.js | 3 + _site/site_libs/quarto-search/fuse.min.js | 9 + .../site_libs/quarto-search/quarto-search.js | 1290 ++++++++++ build/lib/DeToX/Base.py | 1575 ------------- build/lib/DeToX/Calibration.py | 1218 ---------- build/lib/DeToX/Coords.py | 507 ---- build/lib/DeToX/ETSettings.py | 574 ----- build/lib/DeToX/Utils.py | 247 -- build/lib/DeToX/__init__.py | 36 - build/lib/DeToX/calibration_config.py | 104 - docs/GettingStarted.qmd | 141 -- docs/Tutorial/Tutorial1.qmd | 22 - docs/Tutorial/Tutorial2.qmd | 17 - docs/Tutorial/Tutorial3.qmd | 17 - docs/Tutorial/Tutorial4.qmd | 17 - docs/Vignettes/Calibration.qmd | 17 - docs/Vignettes/DataFormats.qmd | 17 - docs/Vignettes/GazeContingent.qmd | 17 - docs/Vignettes/Installation.qmd | 91 - docs/_site/Calibration.html | 627 ----- docs/_site/DataFormats.html | 626 ----- docs/_site/GazeContingent.html | 626 ----- docs/_site/GettingStarted.html | 626 ----- docs/_site/api/Base.ETracker.html | 1408 ----------- docs/_site/api/ETracker.close.html | 735 ------ docs/_site/search.json | 608 ----- .../site_libs/bootstrap/bootstrap.min.css | 12 - .../quarto-syntax-highlighting.css | 205 -- docs/_site/styles.css | 98 - docs/api/ETracker.get_average_gaze.qmd | 35 - docs/objects.json | 1 - 131 files changed, 31668 insertions(+), 11633 deletions(-) rename {Stimuli => CalibrationStimuli}/cute_cat.svg (100%) rename {Stimuli => CalibrationStimuli}/cute_cow.svg (100%) rename {Stimuli => CalibrationStimuli}/cute_dog.svg (100%) rename {Stimuli => CalibrationStimuli}/cute_elephant.svg (100%) rename {Stimuli => CalibrationStimuli}/cute_elk.svg (100%) rename {Stimuli => CalibrationStimuli}/cute_hippo.svg (100%) rename {Stimuli => CalibrationStimuli}/cute_ladybug.svg (100%) rename {Stimuli => CalibrationStimuli}/cute_panda.svg (100%) rename {Stimuli => CalibrationStimuli}/cute_penguin.svg (100%) rename {Stimuli => CalibrationStimuli}/cute_pig.svg (100%) rename {Stimuli => CalibrationStimuli}/cute_sheep.svg (100%) delete mode 100644 DeToX.egg-info/PKG-INFO delete mode 100644 DeToX.egg-info/SOURCES.txt delete mode 100644 DeToX.egg-info/requires.txt create mode 100644 Documentation/.gitignore rename {docs/Vignettes => Documentation/Draft}/Settings.qmd (100%) create mode 100644 Documentation/Vignettes/GettingStarted.qmd create mode 100644 Documentation/Vignettes/Installation.qmd rename {docs => Documentation}/_quarto.yml (82%) rename {docs => Documentation}/api/BaseCalibrationSession.qmd (100%) rename {docs => Documentation}/api/ETSettings.AnimationSettings.qmd (100%) rename {docs => Documentation}/api/ETSettings.CalibrationColors.qmd (100%) rename {docs => Documentation}/api/ETSettings.FontSizeMultipliers.qmd (100%) rename {docs => Documentation}/api/ETSettings.UIElementSizes.qmd (100%) rename {docs => Documentation}/api/ETracker.calibrate.qmd (100%) rename {docs => Documentation}/api/ETracker.gaze_contingent.qmd (100%) rename {docs => Documentation}/api/ETracker.get_gaze_position.qmd (100%) rename {docs => Documentation}/api/ETracker.load_calibration.qmd (100%) rename {docs => Documentation}/api/ETracker.qmd (100%) rename {docs => Documentation}/api/ETracker.record_event.qmd (100%) rename {docs => Documentation}/api/ETracker.save_calibration.qmd (100%) rename {docs => Documentation}/api/ETracker.save_data.qmd (100%) rename {docs => Documentation}/api/ETracker.show_status.qmd (100%) rename {docs => Documentation}/api/ETracker.start_recording.qmd (100%) rename {docs => Documentation}/api/ETracker.stop_recording.qmd (100%) rename {docs => Documentation}/api/InfantStimuli.qmd (100%) rename {docs => Documentation}/api/MouseCalibrationSession.qmd (100%) rename {docs => Documentation}/api/NicePrint.qmd (100%) rename {docs => Documentation}/api/TobiiCalibrationSession.qmd (100%) rename {docs => Documentation}/api/_sidebar.yml (100%) rename {docs => Documentation}/api/convert_height_to_units.qmd (100%) rename {docs => Documentation}/api/get_psychopy_pos.qmd (100%) rename {docs => Documentation}/api/get_psychopy_pos_from_trackbox.qmd (100%) rename {docs => Documentation}/api/get_tobii_pos.qmd (100%) rename {docs => Documentation}/api/index.qmd (96%) rename {docs => Documentation}/api/pix2tobii.qmd (100%) rename {docs => Documentation}/api/psychopy_to_pixels.qmd (100%) rename {docs => Documentation}/api/tobii2pix.qmd (100%) rename {docs => Documentation}/index.qmd (84%) create mode 100644 Documentation/objects.json rename {docs/_site/resources/logo => Documentation/resources}/full_logo.png (100%) rename {docs => Documentation}/styles.scss (100%) create mode 100644 _site/Vignettes/GettingStarted.html create mode 100644 _site/Vignettes/Installation.html rename docs/_site/api/ETracker.html => _site/api/BaseCalibrationSession.html (50%) create mode 100644 _site/api/ETSettings.AnimationSettings.html create mode 100644 _site/api/ETSettings.CalibrationColors.html create mode 100644 _site/api/ETSettings.FontSizeMultipliers.html create mode 100644 _site/api/ETSettings.UIElementSizes.html rename {docs/_site => _site}/api/ETracker.calibrate.html (57%) rename {docs/_site => _site}/api/ETracker.gaze_contingent.html (62%) create mode 100644 _site/api/ETracker.get_gaze_position.html create mode 100644 _site/api/ETracker.html rename {docs/_site => _site}/api/ETracker.load_calibration.html (59%) rename {docs/_site => _site}/api/ETracker.record_event.html (60%) rename {docs/_site => _site}/api/ETracker.save_calibration.html (59%) rename {docs/_site => _site}/api/ETracker.save_data.html (62%) rename {docs/_site => _site}/api/ETracker.show_status.html (61%) rename {docs/_site => _site}/api/ETracker.start_recording.html (57%) rename {docs/_site => _site}/api/ETracker.stop_recording.html (61%) create mode 100644 _site/api/InfantStimuli.html create mode 100644 _site/api/MouseCalibrationSession.html rename docs/_site/api/index.html => _site/api/NicePrint.html (56%) create mode 100644 _site/api/TobiiCalibrationSession.html create mode 100644 _site/api/convert_height_to_units.html create mode 100644 _site/api/get_psychopy_pos.html create mode 100644 _site/api/get_psychopy_pos_from_trackbox.html create mode 100644 _site/api/get_tobii_pos.html create mode 100644 _site/api/index.html create mode 100644 _site/api/pix2tobii.html create mode 100644 _site/api/psychopy_to_pixels.html rename docs/_site/api/ETracker.get_average_gaze.html => _site/api/tobii2pix.html (55%) rename {docs/_site => _site}/index.html (52%) create mode 100644 _site/resources/full_logo.png create mode 100644 _site/search.json create mode 100644 _site/site_libs/bootstrap/bootstrap-icons.css create mode 100644 _site/site_libs/bootstrap/bootstrap-icons.woff create mode 100644 _site/site_libs/bootstrap/bootstrap.min.css create mode 100644 _site/site_libs/bootstrap/bootstrap.min.js create mode 100644 _site/site_libs/clipboard/clipboard.min.js create mode 100644 _site/site_libs/cookie-consent/cookie-consent.css create mode 100644 _site/site_libs/cookie-consent/cookie-consent.js create mode 100644 _site/site_libs/quarto-html/anchor.min.js create mode 100644 _site/site_libs/quarto-html/popper.min.js create mode 100644 _site/site_libs/quarto-html/quarto-syntax-highlighting.css rename {docs/_site => _site}/site_libs/quarto-html/quarto.js (100%) create mode 100644 _site/site_libs/quarto-html/tippy.css create mode 100644 _site/site_libs/quarto-html/tippy.umd.min.js create mode 100644 _site/site_libs/quarto-nav/headroom.min.js create mode 100644 _site/site_libs/quarto-nav/quarto-nav.js create mode 100644 _site/site_libs/quarto-search/autocomplete.umd.js create mode 100644 _site/site_libs/quarto-search/fuse.min.js create mode 100644 _site/site_libs/quarto-search/quarto-search.js delete mode 100644 build/lib/DeToX/Base.py delete mode 100644 build/lib/DeToX/Calibration.py delete mode 100644 build/lib/DeToX/Coords.py delete mode 100644 build/lib/DeToX/ETSettings.py delete mode 100644 build/lib/DeToX/Utils.py delete mode 100644 build/lib/DeToX/__init__.py delete mode 100644 build/lib/DeToX/calibration_config.py delete mode 100644 docs/GettingStarted.qmd delete mode 100644 docs/Tutorial/Tutorial1.qmd delete mode 100644 docs/Tutorial/Tutorial2.qmd delete mode 100644 docs/Tutorial/Tutorial3.qmd delete mode 100644 docs/Tutorial/Tutorial4.qmd delete mode 100644 docs/Vignettes/Calibration.qmd delete mode 100644 docs/Vignettes/DataFormats.qmd delete mode 100644 docs/Vignettes/GazeContingent.qmd delete mode 100644 docs/Vignettes/Installation.qmd delete mode 100644 docs/_site/Calibration.html delete mode 100644 docs/_site/DataFormats.html delete mode 100644 docs/_site/GazeContingent.html delete mode 100644 docs/_site/GettingStarted.html delete mode 100644 docs/_site/api/Base.ETracker.html delete mode 100644 docs/_site/api/ETracker.close.html delete mode 100644 docs/_site/search.json delete mode 100644 docs/_site/site_libs/bootstrap/bootstrap.min.css delete mode 100644 docs/_site/site_libs/quarto-html/quarto-syntax-highlighting.css delete mode 100644 docs/_site/styles.css delete mode 100644 docs/api/ETracker.get_average_gaze.qmd delete mode 100644 docs/objects.json diff --git a/Stimuli/cute_cat.svg b/CalibrationStimuli/cute_cat.svg similarity index 100% rename from Stimuli/cute_cat.svg rename to CalibrationStimuli/cute_cat.svg diff --git a/Stimuli/cute_cow.svg b/CalibrationStimuli/cute_cow.svg similarity index 100% rename from Stimuli/cute_cow.svg rename to CalibrationStimuli/cute_cow.svg diff --git a/Stimuli/cute_dog.svg b/CalibrationStimuli/cute_dog.svg similarity index 100% rename from Stimuli/cute_dog.svg rename to CalibrationStimuli/cute_dog.svg diff --git a/Stimuli/cute_elephant.svg b/CalibrationStimuli/cute_elephant.svg similarity index 100% rename from Stimuli/cute_elephant.svg rename to CalibrationStimuli/cute_elephant.svg diff --git a/Stimuli/cute_elk.svg b/CalibrationStimuli/cute_elk.svg similarity index 100% rename from Stimuli/cute_elk.svg rename to CalibrationStimuli/cute_elk.svg diff --git a/Stimuli/cute_hippo.svg b/CalibrationStimuli/cute_hippo.svg similarity index 100% rename from Stimuli/cute_hippo.svg rename to CalibrationStimuli/cute_hippo.svg diff --git a/Stimuli/cute_ladybug.svg b/CalibrationStimuli/cute_ladybug.svg similarity index 100% rename from Stimuli/cute_ladybug.svg rename to CalibrationStimuli/cute_ladybug.svg diff --git a/Stimuli/cute_panda.svg b/CalibrationStimuli/cute_panda.svg similarity index 100% rename from Stimuli/cute_panda.svg rename to CalibrationStimuli/cute_panda.svg diff --git a/Stimuli/cute_penguin.svg b/CalibrationStimuli/cute_penguin.svg similarity index 100% rename from Stimuli/cute_penguin.svg rename to CalibrationStimuli/cute_penguin.svg diff --git a/Stimuli/cute_pig.svg b/CalibrationStimuli/cute_pig.svg similarity index 100% rename from Stimuli/cute_pig.svg rename to CalibrationStimuli/cute_pig.svg diff --git a/Stimuli/cute_sheep.svg b/CalibrationStimuli/cute_sheep.svg similarity index 100% rename from Stimuli/cute_sheep.svg rename to CalibrationStimuli/cute_sheep.svg diff --git a/DeToX.egg-info/PKG-INFO b/DeToX.egg-info/PKG-INFO deleted file mode 100644 index db4bb3a..0000000 --- a/DeToX.egg-info/PKG-INFO +++ /dev/null @@ -1,30 +0,0 @@ -Metadata-Version: 2.4 -Name: DeToX -Version: 0.1.0 -Summary: Lightweight Python wrapper around tobii-researcher -Author-email: Tommaso Ghilardi -Requires-Python: >=3.10 -Description-Content-Type: text/markdown -Requires-Dist: tobii-research -Requires-Dist: psychopy - -# DeToX - -DeToX (Developmental Tobii Experiment) is a user-friendly Python wrapper for the tobii-researcher library. It is designed to simplify the integration of Tobii eye-tracking hardware with PsychoPy, particularly for conducting developmental studies involving infants. By streamlining the process of data collection, DeToX aims to enhance the efficiency of developmental eye-tracking experiments. - -## Key Features - -- **Data Recording**: Seamlessly record eye-tracking data during experiments. -- **CSV Export**: Save the collected data buffer conveniently as a CSV file for further analysis. -- **Customizable Calibration**: Run eye-tracker calibration using a variety of animations tailored to engage infants. -- **Status Monitoring**: Keep track of the eye-tracker's status in real-time. - -### Operational Features - -- **Simulated Data Streams**: Facilitate experimental setups by simulating eye-tracker data streams, allowing for research continuity without the need for physical eye-tracking hardware. - - **Next Steps**: Implement enhancements to the calibration process and improve status display functionalities. - -### Future Enhancements - -- **Gaze-Contingent Experimentation**: Develop helper functions to support gaze-contingent experimental designs, enabling more dynamic and interactive studies. - diff --git a/DeToX.egg-info/SOURCES.txt b/DeToX.egg-info/SOURCES.txt deleted file mode 100644 index f7d2dc2..0000000 --- a/DeToX.egg-info/SOURCES.txt +++ /dev/null @@ -1,14 +0,0 @@ -README.md -pyproject.toml -DeToX/Base.py -DeToX/Calibration.py -DeToX/Coords.py -DeToX/ETSettings.py -DeToX/Utils.py -DeToX/__init__.py -DeToX.egg-info/PKG-INFO -DeToX.egg-info/SOURCES.txt -DeToX.egg-info/dependency_links.txt -DeToX.egg-info/requires.txt -DeToX.egg-info/top_level.txt -tests/testCalibration.py \ No newline at end of file diff --git a/DeToX.egg-info/requires.txt b/DeToX.egg-info/requires.txt deleted file mode 100644 index 6a5b7d9..0000000 --- a/DeToX.egg-info/requires.txt +++ /dev/null @@ -1,2 +0,0 @@ -tobii-research -psychopy diff --git a/Documentation/.gitignore b/Documentation/.gitignore new file mode 100644 index 0000000..075b254 --- /dev/null +++ b/Documentation/.gitignore @@ -0,0 +1 @@ +/.quarto/ diff --git a/docs/Vignettes/Settings.qmd b/Documentation/Draft/Settings.qmd similarity index 100% rename from docs/Vignettes/Settings.qmd rename to Documentation/Draft/Settings.qmd diff --git a/Documentation/Vignettes/GettingStarted.qmd b/Documentation/Vignettes/GettingStarted.qmd new file mode 100644 index 0000000..edd88a6 --- /dev/null +++ b/Documentation/Vignettes/GettingStarted.qmd @@ -0,0 +1,187 @@ +--- +title: "Getting Started with DeToX" +description: "Starting using DeToX" +author: Tommaso Ghilardi + +execute: + enabled: false +--- + +Great! You've got DeToX installed—now let's jump into the exciting part! + +This tutorial will walk you through an **EXTREMELY** basic example showing what DeToX can do and what you'll need to get started. Think of it as your quick-start guide to running your first eye-tracking experiment. + +::: callout-note +## Before we begin + +This tutorial walks you through the essential steps for running an eye-tracking experiment with DeToX. We've designed it to be as straightforward as possible, though you'll need some basic familiarity with PsychoPy - specifically how to create windows and display stimuli. If you're new to PsychoPy or need a refresher, their [official tutorial](https://www.psychopy.org/coder/tutorial1.html) is an excellent starting point. + +Don't worry if you're not a PsychoPy expert! The concepts we'll use are fundamental and easy to pick up. +::: + +DeToX bridges two powerful Python libraries: **PsychoPy** and **tobii_research**. + +- **PsychoPy** is your experiment-building toolkit. It gives you the flexibility and control to design studies exactly how you want them—from simple reaction time tasks to complex visual paradigms. + +- **tobii_research** is your direct line to Tobii eye trackers. It's incredibly powerful, but let's be honest—some of its low-level details can be... *complex*. + +**That's where DeToX comes in**: we've wrapped the tricky bits so you can focus on your research, not wrestling with SDK documentation. + +## Preparation + +let's begin importing the libraries that we will need for this example + +```{python} +#| label: Libraries +#| eval: false +from psychopy import visual, core +from DeToX import ETracker +``` + +**`visual`** and `core` are some of PsychoPy's main modules—it's what you'll use to create the window where your stimuli appear and your experiment runs. + +**`ETracker`** is DeToX's main class and your central hub for all eye-tracking operations. This is the object you'll interact with throughout your experiment to control calibration, recording, and data collection. + +## Window + +Every experiment needs a stage—in PsychoPy, that's your **Window**. This is where all your stimuli will appear and where participants will interact with your study. + +```{python} +#| label: Window creation +#| eval: false +# Create the experiment window +win = visual.Window( + size=[1920, 1080], # Window dimensions in pixels + fullscr=True, # Expand to fill the entire screen + units='pix' # Use pixels as the measurement unit +) +``` + +Breaking it down: + +- **`size`**: Sets your window dimensions. Here we're using 1920×1080, but adjust this to match your monitor. + +- **`fullscr=True`**: Makes the window take over the whole screen—crucial for experiments where you want to eliminate distractions. + +- **`units='pix'`**: Defines how you'll specify positions and sizes throughout your experiment. DeToX supports multiple PsychoPy unit systems—`'height'`, `'norm'`, `'pix'`—so choose whichever you're most comfortable with or best fits your experimental design. + +::: callout-important +## Window size + +If you're following along with this tutorial and experimenting on your own, we **strongly recommend** using a smaller window with `fullscr=False` instead of fullscreen mode. When `fullscr=True`, the window takes over your entire screen, making it tricky (or impossible!) to interact with your computer—like stopping the script or checking documentation. Save fullscreen for your actual experiments. +::: + +Perfect now we have our window where we can draw images, videos and interact with them!! + +## ETracker + +So far we've focused on creating the canvas for our stimuli—but how do we actually interact with the eye tracker? Simple! We use the **`ETracker`** class we imported earlier. + +The `ETracker` needs access to the window we just created, so initializing it is straightforward: + +```{python} +#| label: Et controller +#| eval: false +ET_controller = ETracker(win) +``` + +::: callout-important +## Don't Have an Eye Tracker? No Problem! + +If you're following along without a Tobii eye tracker connected, you can still test everything using **simulation mode**. Just pass `simulate=True` when creating your `ETracker`: + +```{python} +#| label: Et controller simulation +#| eval: false +ET_controller = ETracker(win, simulate=True) +``` + +This tells DeToX to collect data from your **mouse position** instead of an actual eye tracker—perfect for development, testing, or learning the workflow before you have hardware access 😉 +::: + +Once you run this code, DeToX will connect to your eye tracker and set everything up for you. It will also gather information about the connected device and display it in a nice, readable format: + +``` markdown +┌────────────────── Eyetracker Info ──────────────────┐ +│Connected to the eyetracker: │ +│ - Model: Tobii Pro Fusion │ +│ - Current frequency: 250.0 Hz │ +│ - Current illumination mode: Default │ +│Other options: │ +│ - Possible frequencies: (30.0, 60.0, 120.0, 250.0) │ +│ - Possible illumination modes: ('Default',) │ +└─────────────────────────────────────────────────────┘ +``` + +This tells us we're connected to the eye tracker and ready to start recording data! + +## Recod data + +Great! You're now connected to the eye-tracker (or simulating it). However, we're not actually collecting any data yet - let's fix that. + +To begin data collection, call the `start_recording` method on your ETracker instance: + +```{python} +#| label: Recording +#| eval: false +# Start recording data +ET_controller.start_recording(filename="testing.h5") +``` + +The `start_recording` method accepts a `filename` parameter for naming your data file. If you don't specify one, DeToX automatically generates a timestamp-based filename. + +Your eye-tracking data is now being collected continuously and will be later saved in a HDF5 format, which is ideal for storing large datasets efficiently. For details on the data structure and how to analyze your files, see our [DataFormats](DataFormats.qmd) guide. + +## Events + +OK, now that we're recording data, we can show images, videos, or whatever we want! It's entirely up to you and your experimental design! + +Since this is a **SUPER BASIC** example to get you started, we won't overcomplicate things with elaborate stimuli or complex tasks. Let's keep it stupidly simple. As we show images, videos or whatnot we need to keep track at which point thesee stimuli happen in our eyetracking data. And how to do so?? well we can use the `record_event` function!! + +```{python} +#| label: Events +#| eval: false +# Send event 1 +ET_controller.record_event('wait 1') +core.wait(2) # wait 2s + +# Send event 2 +ET_controller.record_event('wait 2') +core.wait(2) # wait 2s +``` + +Here's what's happening: + +- **`controller.record_event('wait 1')`**: Drops a timestamped marker labeled `'wait 1'` into your data stream. This is like planting a flag that says "something important happened HERE." + +- **`core.wait(2)`**: Pauses execution for 2 seconds. During this time, the eye tracker keeps collecting gaze data in the background. + +- **`controller.record_event('wait 2')`**: Plants another marker at the 2-second point, labeled `'wait 2'`. + +- Another **`core.wait(2)`**: Waits another 2 seconds. + +Here we're just using `core.wait()` as a **placeholder**. In your actual experiment, this is where you'd display your stimuli—show images, play videos, present text, or run whatever task your study requires. The `record_event()` calls mark when those stimuli begin in this case! + +## Stop recording + +After the experiment is done, we need to stop the recording and save the data!!! + +```{python} +#| label: Stop recording +#| eval: false +# Stop recording data +ET_controller.stop_recording() +``` + +**Voilà!** DeToX will stop the recording and automatically save all your data to a file. You'll get another nice confirmation message showing you what happened: + +``` markdown +┌────────────── Recording Complete ───────────────┐ +│Data collection lasted approximately 4.02 seconds│ +│Data has been saved to testing.h5 │ +└─────────────────────────────────────────────────┘ +``` + +This tells you how long the recording session lasted and where your data file was saved. By default, DeToX creates a timestamped filename (like `testing.h5`) so you never accidentally overwrite previous recordings. + +**And that's it!** Your eye-tracking data—complete with all those event markers you recorded—is now safely stored and ready for analysis. \ No newline at end of file diff --git a/Documentation/Vignettes/Installation.qmd b/Documentation/Vignettes/Installation.qmd new file mode 100644 index 0000000..b32a8d2 --- /dev/null +++ b/Documentation/Vignettes/Installation.qmd @@ -0,0 +1,125 @@ +--- +title: "Installation" +author: Tommaso Ghilardi +--- + +So you're interested in using DeToX? Awesome! Let's get you set up quickly. + +DeToX is designed as a lightweight wrapper around **PsychoPy** and **tobii_research**. Here's the good news: `tobii_research` usually comes bundled with PsychoPy, which means the only real hurdle is installing PsychoPy itself. And yes, PsychoPy *can* be a bit tricky to install due to its many dependencies—but don't worry, we'll walk you through it. Once PsychoPy is up and running, adding DeToX is a breeze. + +## Installing PsychoPy + +Since PsychoPy is the main challenge, let's tackle that first. You have **two main options**: + +- **Package Installation** + + Install PsychoPy like any other Python package using `pip`. This approach is flexible and ideal if you prefer working in an IDE (like **Positron**, **VS Code**, **PyCharm**, or **Spyder**) where you have full control over your Python environment. + +- **Standalone Installation** + + Use the PsychoPy standalone installer, which bundles PsychoPy and all its dependencies into a single, ready-to-use application. This is often the **easiest way to get started**, especially if you're not familiar with managing Python environments or just want to hit the ground running. + +We like installing psychopy as a package but you do you! + +::: panel-tabset +### Package + +This method is ideal if you prefer working in an IDE (like Positron, VS Code, PyCharm, or Spyder) and want full control over your Python environment. + +#### Step 1: Create a Virtual Environment + +We like to use miniforge to handle our environments and Python installations. Any other method would work as well, but for simplicity we'll show you how we prefer to do it. + +*We recommend using Python 3.10 for the best compatibility:* + +``` bash +mamba create -n detox_env python=3.10 +``` + +This will create an environment called detox_env with python 3.10. Exactly what we need! + +You will probably need to confirm by pressing `y`, and after a few seconds you'll have your environment with Python 3.10! Great! + +#### Step 2: Activate Environment and Install PsychoPy + +Now let's activate this environment (making sure we're using it) and then install PsychoPy: + +``` bash +mamba activate detox_env +pip install psychopy +``` + +this will take some time but if you are lucky you will have psychopy in your enviroment + +Again, confirm if needed and you're done! Amazing! + +### Standalone + +PsychoPy is a large package with many dependencies, and sometimes (depending on your operating system) installing it can be quite tricky! For this reason, the PsychoPy website suggests using the standalone installation method. This is like installing regular software on your computer - it will install PsychoPy and all its dependencies in one go. + +#### Step 1: Install PsychoPy Standalone + +1. Go to the [PsychoPy download page](https://www.psychopy.org/download.html) + +2. Download the standalone installer for your operating system + +3. Run the installer and follow the setup instructions + +You are done!!! Great! +::: + +## Installing DeToX + +Once PsychoPy is installed, we can look at DeToX. Let's gets our hand dirty! The installation is the same for both the Package and Standalone PsychoPy installations but some steps differ. + +::: callout-warning +## DeToX is Still in Development + +DeToX isn't yet available on PyPI, so you'll need to install it directly from our **GitHub repository**. Don't worry—it's straightforward, and we'll guide you through it! + +**One requirement:** You need **Git** installed on your system. + +📥 **Don't have Git?** Download it from [git-scm.com](https://git-scm.com/)—installation takes just a minute. +::: + +::: panel-tabset +### Package + +Again make sure to be in the correct environment if you installed PsychoPy as a package. with the following command: + +``` bash +mamba activate detox_env +``` + +Then simply run: + +``` bash +pip install git+https://github.com/DevStart-Hub/DeToX.git +``` + +Wait a few seconds, confirm if needed, and you are done! + +### Standalone + +1. **Open PsychoPy** + +2. **Go to Coder View** (the interface with the code editor) + +3. **Open the Tools menu** + +4. **Select "Plugins/package manager..."** + +5. **Click on "Packages"** in the top tabs + +6. **Click the "Open PIP terminal" button** + +7. **Type the following command:** `pip install git+https://github.com/DevStart-Hub/DeToX.git` + +That's it! You now have both PsychoPy and DeToX installed and ready to use. +::: + +::: callout-warning +## Important: DeToX requires coding + +DeToX is a code-based library that works with PsychoPy's Coder interface. If you typically use PsychoPy's Builder (the drag-and-drop visual interface), you'll need to switch to the Coder interface to use DeToX. Don't worry - we provide plenty of code examples to get you started! +::: \ No newline at end of file diff --git a/docs/_quarto.yml b/Documentation/_quarto.yml similarity index 82% rename from docs/_quarto.yml rename to Documentation/_quarto.yml index 022ab3f..ba2450c 100644 --- a/docs/_quarto.yml +++ b/Documentation/_quarto.yml @@ -1,11 +1,20 @@ project: type: website + output-dir: ../_site + resources: + - resources/** + + render: + - "*.qmd" + - "!Draft/*" + execute: kernel: tester metadata-files: - api/_sidebar.yml + website: title: "DeToX" @@ -16,35 +25,16 @@ website: navbar: - logo: resources/logo/full_logo.png + logo: resources/full_logo.png - # background: primary right: - - href: GettingStarted.qmd - text: Getting Started - text: "Vignettes" menu: - text: "Installation" href: Vignettes/Installation.qmd - - text: "Calibration Guide" - href: Vignettes/Calibration.qmd - - text: "Gaze Contingent Experiments" - href: Vignettes/GazeContingent.qmd - - text: Undertanding data formats - href: Vignettes/DataFormats.qmd - - text: Accessing DeToX settings - href: Vignettes/Settings.qmd - - - text: "Tutorial" - menu: - - text: "1) Experiment" - href: Tutorial/Tutorial1.qmd - - text: "2) Use the Eye Tracker" - href: Tutorial/Tutorial2.qmd - - text: "3) Calibration" - href: Tutorial/Tutorial3.qmd - - text: "4) Gaze Contingent" - href: Tutorial/Tutorial4.qmd + - text: Getting Started + href: Vignettes/GettingStarted.qmd + - href: api/index.qmd text: Reference @@ -59,6 +49,16 @@ website: - text: Report a Bug href: https://bugs.com + sidebar: + - title: "Vignettes" + style: "floating" + contents: + - text: "Installation" + href: Vignettes/Installation.qmd + - text: Getting Started + href: Vignettes/GettingStarted.qmd + + # Utilities back-to-top-navigation: true page-navigation: true @@ -99,12 +99,12 @@ format: code-block-background: true code-block-border-left: "#00B3B3" - # Pagination - grid: - sidebar-width: 300px - body-width: 1100px - margin-width: 300px - gutter-width: 1.5rem + # # Pagination + # grid: + # sidebar-width: 300px + # body-width: 1100px + # margin-width: 300px + # gutter-width: 1.5rem quartodoc: style: pkgdown @@ -149,7 +149,7 @@ quartodoc: - subtitle: Gaze Contingent desc: > Tools for running gaze-contingent experiments, where visual presentation - adapts dynamically to a participant’s gaze position. Includes functionality + adapts dynamically to a participants gaze position. Includes functionality for live gaze-contingent control and methods to compute average gaze positions for experimental logic. contents: diff --git a/docs/api/BaseCalibrationSession.qmd b/Documentation/api/BaseCalibrationSession.qmd similarity index 100% rename from docs/api/BaseCalibrationSession.qmd rename to Documentation/api/BaseCalibrationSession.qmd diff --git a/docs/api/ETSettings.AnimationSettings.qmd b/Documentation/api/ETSettings.AnimationSettings.qmd similarity index 100% rename from docs/api/ETSettings.AnimationSettings.qmd rename to Documentation/api/ETSettings.AnimationSettings.qmd diff --git a/docs/api/ETSettings.CalibrationColors.qmd b/Documentation/api/ETSettings.CalibrationColors.qmd similarity index 100% rename from docs/api/ETSettings.CalibrationColors.qmd rename to Documentation/api/ETSettings.CalibrationColors.qmd diff --git a/docs/api/ETSettings.FontSizeMultipliers.qmd b/Documentation/api/ETSettings.FontSizeMultipliers.qmd similarity index 100% rename from docs/api/ETSettings.FontSizeMultipliers.qmd rename to Documentation/api/ETSettings.FontSizeMultipliers.qmd diff --git a/docs/api/ETSettings.UIElementSizes.qmd b/Documentation/api/ETSettings.UIElementSizes.qmd similarity index 100% rename from docs/api/ETSettings.UIElementSizes.qmd rename to Documentation/api/ETSettings.UIElementSizes.qmd diff --git a/docs/api/ETracker.calibrate.qmd b/Documentation/api/ETracker.calibrate.qmd similarity index 100% rename from docs/api/ETracker.calibrate.qmd rename to Documentation/api/ETracker.calibrate.qmd diff --git a/docs/api/ETracker.gaze_contingent.qmd b/Documentation/api/ETracker.gaze_contingent.qmd similarity index 100% rename from docs/api/ETracker.gaze_contingent.qmd rename to Documentation/api/ETracker.gaze_contingent.qmd diff --git a/docs/api/ETracker.get_gaze_position.qmd b/Documentation/api/ETracker.get_gaze_position.qmd similarity index 100% rename from docs/api/ETracker.get_gaze_position.qmd rename to Documentation/api/ETracker.get_gaze_position.qmd diff --git a/docs/api/ETracker.load_calibration.qmd b/Documentation/api/ETracker.load_calibration.qmd similarity index 100% rename from docs/api/ETracker.load_calibration.qmd rename to Documentation/api/ETracker.load_calibration.qmd diff --git a/docs/api/ETracker.qmd b/Documentation/api/ETracker.qmd similarity index 100% rename from docs/api/ETracker.qmd rename to Documentation/api/ETracker.qmd diff --git a/docs/api/ETracker.record_event.qmd b/Documentation/api/ETracker.record_event.qmd similarity index 100% rename from docs/api/ETracker.record_event.qmd rename to Documentation/api/ETracker.record_event.qmd diff --git a/docs/api/ETracker.save_calibration.qmd b/Documentation/api/ETracker.save_calibration.qmd similarity index 100% rename from docs/api/ETracker.save_calibration.qmd rename to Documentation/api/ETracker.save_calibration.qmd diff --git a/docs/api/ETracker.save_data.qmd b/Documentation/api/ETracker.save_data.qmd similarity index 100% rename from docs/api/ETracker.save_data.qmd rename to Documentation/api/ETracker.save_data.qmd diff --git a/docs/api/ETracker.show_status.qmd b/Documentation/api/ETracker.show_status.qmd similarity index 100% rename from docs/api/ETracker.show_status.qmd rename to Documentation/api/ETracker.show_status.qmd diff --git a/docs/api/ETracker.start_recording.qmd b/Documentation/api/ETracker.start_recording.qmd similarity index 100% rename from docs/api/ETracker.start_recording.qmd rename to Documentation/api/ETracker.start_recording.qmd diff --git a/docs/api/ETracker.stop_recording.qmd b/Documentation/api/ETracker.stop_recording.qmd similarity index 100% rename from docs/api/ETracker.stop_recording.qmd rename to Documentation/api/ETracker.stop_recording.qmd diff --git a/docs/api/InfantStimuli.qmd b/Documentation/api/InfantStimuli.qmd similarity index 100% rename from docs/api/InfantStimuli.qmd rename to Documentation/api/InfantStimuli.qmd diff --git a/docs/api/MouseCalibrationSession.qmd b/Documentation/api/MouseCalibrationSession.qmd similarity index 100% rename from docs/api/MouseCalibrationSession.qmd rename to Documentation/api/MouseCalibrationSession.qmd diff --git a/docs/api/NicePrint.qmd b/Documentation/api/NicePrint.qmd similarity index 100% rename from docs/api/NicePrint.qmd rename to Documentation/api/NicePrint.qmd diff --git a/docs/api/TobiiCalibrationSession.qmd b/Documentation/api/TobiiCalibrationSession.qmd similarity index 100% rename from docs/api/TobiiCalibrationSession.qmd rename to Documentation/api/TobiiCalibrationSession.qmd diff --git a/docs/api/_sidebar.yml b/Documentation/api/_sidebar.yml similarity index 100% rename from docs/api/_sidebar.yml rename to Documentation/api/_sidebar.yml diff --git a/docs/api/convert_height_to_units.qmd b/Documentation/api/convert_height_to_units.qmd similarity index 100% rename from docs/api/convert_height_to_units.qmd rename to Documentation/api/convert_height_to_units.qmd diff --git a/docs/api/get_psychopy_pos.qmd b/Documentation/api/get_psychopy_pos.qmd similarity index 100% rename from docs/api/get_psychopy_pos.qmd rename to Documentation/api/get_psychopy_pos.qmd diff --git a/docs/api/get_psychopy_pos_from_trackbox.qmd b/Documentation/api/get_psychopy_pos_from_trackbox.qmd similarity index 100% rename from docs/api/get_psychopy_pos_from_trackbox.qmd rename to Documentation/api/get_psychopy_pos_from_trackbox.qmd diff --git a/docs/api/get_tobii_pos.qmd b/Documentation/api/get_tobii_pos.qmd similarity index 100% rename from docs/api/get_tobii_pos.qmd rename to Documentation/api/get_tobii_pos.qmd diff --git a/docs/api/index.qmd b/Documentation/api/index.qmd similarity index 96% rename from docs/api/index.qmd rename to Documentation/api/index.qmd index 55ce5ca..0e8a773 100644 --- a/docs/api/index.qmd +++ b/Documentation/api/index.qmd @@ -35,7 +35,7 @@ Methods for running and managing eye tracker calibration. These include display ### Gaze Contingent -Tools for running gaze-contingent experiments, where visual presentation adapts dynamically to a participant’s gaze position. Includes functionality for live gaze-contingent control and methods to compute average gaze positions for experimental logic. +Tools for running gaze-contingent experiments, where visual presentation adapts dynamically to a participants gaze position. Includes functionality for live gaze-contingent control and methods to compute average gaze positions for experimental logic. | | | diff --git a/docs/api/pix2tobii.qmd b/Documentation/api/pix2tobii.qmd similarity index 100% rename from docs/api/pix2tobii.qmd rename to Documentation/api/pix2tobii.qmd diff --git a/docs/api/psychopy_to_pixels.qmd b/Documentation/api/psychopy_to_pixels.qmd similarity index 100% rename from docs/api/psychopy_to_pixels.qmd rename to Documentation/api/psychopy_to_pixels.qmd diff --git a/docs/api/tobii2pix.qmd b/Documentation/api/tobii2pix.qmd similarity index 100% rename from docs/api/tobii2pix.qmd rename to Documentation/api/tobii2pix.qmd diff --git a/docs/index.qmd b/Documentation/index.qmd similarity index 84% rename from docs/index.qmd rename to Documentation/index.qmd index fce2748..21f60d4 100644 --- a/docs/index.qmd +++ b/Documentation/index.qmd @@ -1,13 +1,18 @@ --- title: "DeToX" keywords: [DeToX, eye-tracking, Tobii, PsychoPy, infant studies, calibration, gaze data, eye tracker, research, Python] + +format: + html: + page-layout: full + toc: false --- ```{=html} Logo ``` @@ -56,5 +61,5 @@ While we tried to have a thotoug documentation with lots of examples you may hav ::: callout-caution ## Disclaimer -While we have done our best to create a reliable and user-friendly package, this is our first attempt at developing a comprehensive eye-tracking wrapper. We encourage you to thoroughly test DeToX with your specific experimental setup and requirements before relying on it for critical research. This package is provided without warranties of any kind, and users should verify that all functionality works as expected in their particular research context. We welcome feedback and bug reports to help improve the package, but please use appropriate caution and validation procedures when implementing DeToX in your studies. +While we are tring to do our best to create a reliable and user-friendly package, this is our first attempt at developing a comprehensive eye-tracking wrapper. We encourage you to thoroughly test DeToX with your specific experimental setup and requirements before relying on it for critical research. This package is provided without warranties of any kind, and users should verify that all functionality works as expected in their particular research context. We welcome feedback and bug reports to help improve the package, but please use appropriate caution and validation procedures when implementing DeToX in your studies. ::: \ No newline at end of file diff --git a/Documentation/objects.json b/Documentation/objects.json new file mode 100644 index 0000000..bf8de95 --- /dev/null +++ b/Documentation/objects.json @@ -0,0 +1 @@ +{"project": "DeToX", "version": "0.0.9999", "count": 84, "items": [{"name": "DeToX.ETracker.calibrate", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.calibrate", "dispname": "-"}, {"name": "DeToX.Base.ETracker.calibrate", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.calibrate", "dispname": "DeToX.ETracker.calibrate"}, {"name": "DeToX.ETracker.gaze_contingent", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.gaze_contingent", "dispname": "-"}, {"name": "DeToX.Base.ETracker.gaze_contingent", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.gaze_contingent", "dispname": "DeToX.ETracker.gaze_contingent"}, {"name": "DeToX.ETracker.get_gaze_position", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.get_gaze_position", "dispname": "-"}, {"name": "DeToX.Base.ETracker.get_gaze_position", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.get_gaze_position", "dispname": "DeToX.ETracker.get_gaze_position"}, {"name": "DeToX.ETracker.load_calibration", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.load_calibration", "dispname": "-"}, {"name": "DeToX.Base.ETracker.load_calibration", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.load_calibration", "dispname": "DeToX.ETracker.load_calibration"}, {"name": "DeToX.ETracker.record_event", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.record_event", "dispname": "-"}, {"name": "DeToX.Base.ETracker.record_event", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.record_event", "dispname": "DeToX.ETracker.record_event"}, {"name": "DeToX.ETracker.save_calibration", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.save_calibration", "dispname": "-"}, {"name": "DeToX.Base.ETracker.save_calibration", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.save_calibration", "dispname": "DeToX.ETracker.save_calibration"}, {"name": "DeToX.ETracker.save_data", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.save_data", "dispname": "-"}, {"name": "DeToX.Base.ETracker.save_data", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.save_data", "dispname": "DeToX.ETracker.save_data"}, {"name": "DeToX.ETracker.set_eyetracking_settings", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.set_eyetracking_settings", "dispname": "-"}, {"name": "DeToX.Base.ETracker.set_eyetracking_settings", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.set_eyetracking_settings", "dispname": "DeToX.ETracker.set_eyetracking_settings"}, {"name": "DeToX.ETracker.show_status", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.show_status", "dispname": "-"}, {"name": "DeToX.Base.ETracker.show_status", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.show_status", "dispname": "DeToX.ETracker.show_status"}, {"name": "DeToX.ETracker.start_recording", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.start_recording", "dispname": "-"}, {"name": "DeToX.Base.ETracker.start_recording", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.start_recording", "dispname": "DeToX.ETracker.start_recording"}, {"name": "DeToX.ETracker.stop_recording", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.stop_recording", "dispname": "-"}, {"name": "DeToX.Base.ETracker.stop_recording", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker.stop_recording", "dispname": "DeToX.ETracker.stop_recording"}, {"name": "DeToX.ETracker", "domain": "py", "role": "class", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker", "dispname": "-"}, {"name": "DeToX.Base.ETracker", "domain": "py", "role": "class", "priority": "1", "uri": "api/ETracker.html#DeToX.ETracker", "dispname": "DeToX.ETracker"}, {"name": "DeToX.ETracker.start_recording", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.start_recording.html#DeToX.ETracker.start_recording", "dispname": "-"}, {"name": "DeToX.Base.ETracker.start_recording", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.start_recording.html#DeToX.ETracker.start_recording", "dispname": "DeToX.ETracker.start_recording"}, {"name": "DeToX.ETracker.stop_recording", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.stop_recording.html#DeToX.ETracker.stop_recording", "dispname": "-"}, {"name": "DeToX.Base.ETracker.stop_recording", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.stop_recording.html#DeToX.ETracker.stop_recording", "dispname": "DeToX.ETracker.stop_recording"}, {"name": "DeToX.ETracker.record_event", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.record_event.html#DeToX.ETracker.record_event", "dispname": "-"}, {"name": "DeToX.Base.ETracker.record_event", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.record_event.html#DeToX.ETracker.record_event", "dispname": "DeToX.ETracker.record_event"}, {"name": "DeToX.ETracker.save_data", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.save_data.html#DeToX.ETracker.save_data", "dispname": "-"}, {"name": "DeToX.Base.ETracker.save_data", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.save_data.html#DeToX.ETracker.save_data", "dispname": "DeToX.ETracker.save_data"}, {"name": "DeToX.ETracker.show_status", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.show_status.html#DeToX.ETracker.show_status", "dispname": "-"}, {"name": "DeToX.Base.ETracker.show_status", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.show_status.html#DeToX.ETracker.show_status", "dispname": "DeToX.ETracker.show_status"}, {"name": "DeToX.ETracker.calibrate", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.calibrate.html#DeToX.ETracker.calibrate", "dispname": "-"}, {"name": "DeToX.Base.ETracker.calibrate", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.calibrate.html#DeToX.ETracker.calibrate", "dispname": "DeToX.ETracker.calibrate"}, {"name": "DeToX.ETracker.save_calibration", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.save_calibration.html#DeToX.ETracker.save_calibration", "dispname": "-"}, {"name": "DeToX.Base.ETracker.save_calibration", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.save_calibration.html#DeToX.ETracker.save_calibration", "dispname": "DeToX.ETracker.save_calibration"}, {"name": "DeToX.ETracker.load_calibration", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.load_calibration.html#DeToX.ETracker.load_calibration", "dispname": "-"}, {"name": "DeToX.Base.ETracker.load_calibration", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.load_calibration.html#DeToX.ETracker.load_calibration", "dispname": "DeToX.ETracker.load_calibration"}, {"name": "DeToX.ETracker.gaze_contingent", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.gaze_contingent.html#DeToX.ETracker.gaze_contingent", "dispname": "-"}, {"name": "DeToX.Base.ETracker.gaze_contingent", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.gaze_contingent.html#DeToX.ETracker.gaze_contingent", "dispname": "DeToX.ETracker.gaze_contingent"}, {"name": "DeToX.ETracker.get_gaze_position", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.get_gaze_position.html#DeToX.ETracker.get_gaze_position", "dispname": "-"}, {"name": "DeToX.Base.ETracker.get_gaze_position", "domain": "py", "role": "function", "priority": "1", "uri": "api/ETracker.get_gaze_position.html#DeToX.ETracker.get_gaze_position", "dispname": "DeToX.ETracker.get_gaze_position"}, {"name": "DeToX.BaseCalibrationSession.check_points", "domain": "py", "role": "function", "priority": "1", "uri": "api/BaseCalibrationSession.html#DeToX.BaseCalibrationSession.check_points", "dispname": "-"}, {"name": "DeToX.Calibration.BaseCalibrationSession.check_points", "domain": "py", "role": "function", "priority": "1", "uri": "api/BaseCalibrationSession.html#DeToX.BaseCalibrationSession.check_points", "dispname": "DeToX.BaseCalibrationSession.check_points"}, {"name": "DeToX.BaseCalibrationSession.show_message_and_wait", "domain": "py", "role": "function", "priority": "1", "uri": "api/BaseCalibrationSession.html#DeToX.BaseCalibrationSession.show_message_and_wait", "dispname": "-"}, {"name": "DeToX.Calibration.BaseCalibrationSession.show_message_and_wait", "domain": "py", "role": "function", "priority": "1", "uri": "api/BaseCalibrationSession.html#DeToX.BaseCalibrationSession.show_message_and_wait", "dispname": "DeToX.BaseCalibrationSession.show_message_and_wait"}, {"name": "DeToX.BaseCalibrationSession", "domain": "py", "role": "class", "priority": "1", "uri": "api/BaseCalibrationSession.html#DeToX.BaseCalibrationSession", "dispname": "-"}, {"name": "DeToX.Calibration.BaseCalibrationSession", "domain": "py", "role": "class", "priority": "1", "uri": "api/BaseCalibrationSession.html#DeToX.BaseCalibrationSession", "dispname": "DeToX.BaseCalibrationSession"}, {"name": "DeToX.TobiiCalibrationSession.run", "domain": "py", "role": "function", "priority": "1", "uri": "api/TobiiCalibrationSession.html#DeToX.TobiiCalibrationSession.run", "dispname": "-"}, {"name": "DeToX.Calibration.TobiiCalibrationSession.run", "domain": "py", "role": "function", "priority": "1", "uri": "api/TobiiCalibrationSession.html#DeToX.TobiiCalibrationSession.run", "dispname": "DeToX.TobiiCalibrationSession.run"}, {"name": "DeToX.TobiiCalibrationSession", "domain": "py", "role": "class", "priority": "1", "uri": "api/TobiiCalibrationSession.html#DeToX.TobiiCalibrationSession", "dispname": "-"}, {"name": "DeToX.Calibration.TobiiCalibrationSession", "domain": "py", "role": "class", "priority": "1", "uri": "api/TobiiCalibrationSession.html#DeToX.TobiiCalibrationSession", "dispname": "DeToX.TobiiCalibrationSession"}, {"name": "DeToX.MouseCalibrationSession.run", "domain": "py", "role": "function", "priority": "1", "uri": "api/MouseCalibrationSession.html#DeToX.MouseCalibrationSession.run", "dispname": "-"}, {"name": "DeToX.Calibration.MouseCalibrationSession.run", "domain": "py", "role": "function", "priority": "1", "uri": "api/MouseCalibrationSession.html#DeToX.MouseCalibrationSession.run", "dispname": "DeToX.MouseCalibrationSession.run"}, {"name": "DeToX.MouseCalibrationSession", "domain": "py", "role": "class", "priority": "1", "uri": "api/MouseCalibrationSession.html#DeToX.MouseCalibrationSession", "dispname": "-"}, {"name": "DeToX.Calibration.MouseCalibrationSession", "domain": "py", "role": "class", "priority": "1", "uri": "api/MouseCalibrationSession.html#DeToX.MouseCalibrationSession", "dispname": "DeToX.MouseCalibrationSession"}, {"name": "DeToX.convert_height_to_units", "domain": "py", "role": "function", "priority": "1", "uri": "api/convert_height_to_units.html#DeToX.convert_height_to_units", "dispname": "-"}, {"name": "DeToX.Coords.convert_height_to_units", "domain": "py", "role": "function", "priority": "1", "uri": "api/convert_height_to_units.html#DeToX.convert_height_to_units", "dispname": "DeToX.convert_height_to_units"}, {"name": "DeToX.get_psychopy_pos", "domain": "py", "role": "function", "priority": "1", "uri": "api/get_psychopy_pos.html#DeToX.get_psychopy_pos", "dispname": "-"}, {"name": "DeToX.Coords.get_psychopy_pos", "domain": "py", "role": "function", "priority": "1", "uri": "api/get_psychopy_pos.html#DeToX.get_psychopy_pos", "dispname": "DeToX.get_psychopy_pos"}, {"name": "DeToX.psychopy_to_pixels", "domain": "py", "role": "function", "priority": "1", "uri": "api/psychopy_to_pixels.html#DeToX.psychopy_to_pixels", "dispname": "-"}, {"name": "DeToX.Coords.psychopy_to_pixels", "domain": "py", "role": "function", "priority": "1", "uri": "api/psychopy_to_pixels.html#DeToX.psychopy_to_pixels", "dispname": "DeToX.psychopy_to_pixels"}, {"name": "DeToX.get_tobii_pos", "domain": "py", "role": "function", "priority": "1", "uri": "api/get_tobii_pos.html#DeToX.get_tobii_pos", "dispname": "-"}, {"name": "DeToX.Coords.get_tobii_pos", "domain": "py", "role": "function", "priority": "1", "uri": "api/get_tobii_pos.html#DeToX.get_tobii_pos", "dispname": "DeToX.get_tobii_pos"}, {"name": "DeToX.pix2tobii", "domain": "py", "role": "function", "priority": "1", "uri": "api/pix2tobii.html#DeToX.pix2tobii", "dispname": "-"}, {"name": "DeToX.Coords.pix2tobii", "domain": "py", "role": "function", "priority": "1", "uri": "api/pix2tobii.html#DeToX.pix2tobii", "dispname": "DeToX.pix2tobii"}, {"name": "DeToX.tobii2pix", "domain": "py", "role": "function", "priority": "1", "uri": "api/tobii2pix.html#DeToX.tobii2pix", "dispname": "-"}, {"name": "DeToX.Coords.tobii2pix", "domain": "py", "role": "function", "priority": "1", "uri": "api/tobii2pix.html#DeToX.tobii2pix", "dispname": "DeToX.tobii2pix"}, {"name": "DeToX.get_psychopy_pos_from_trackbox", "domain": "py", "role": "function", "priority": "1", "uri": "api/get_psychopy_pos_from_trackbox.html#DeToX.get_psychopy_pos_from_trackbox", "dispname": "-"}, {"name": "DeToX.Coords.get_psychopy_pos_from_trackbox", "domain": "py", "role": "function", "priority": "1", "uri": "api/get_psychopy_pos_from_trackbox.html#DeToX.get_psychopy_pos_from_trackbox", "dispname": "DeToX.get_psychopy_pos_from_trackbox"}, {"name": "DeToX.NicePrint", "domain": "py", "role": "function", "priority": "1", "uri": "api/NicePrint.html#DeToX.NicePrint", "dispname": "-"}, {"name": "DeToX.Utils.NicePrint", "domain": "py", "role": "function", "priority": "1", "uri": "api/NicePrint.html#DeToX.NicePrint", "dispname": "DeToX.NicePrint"}, {"name": "DeToX.InfantStimuli.get_stim", "domain": "py", "role": "function", "priority": "1", "uri": "api/InfantStimuli.html#DeToX.InfantStimuli.get_stim", "dispname": "-"}, {"name": "DeToX.Utils.InfantStimuli.get_stim", "domain": "py", "role": "function", "priority": "1", "uri": "api/InfantStimuli.html#DeToX.InfantStimuli.get_stim", "dispname": "DeToX.InfantStimuli.get_stim"}, {"name": "DeToX.InfantStimuli.get_stim_original_size", "domain": "py", "role": "function", "priority": "1", "uri": "api/InfantStimuli.html#DeToX.InfantStimuli.get_stim_original_size", "dispname": "-"}, {"name": "DeToX.Utils.InfantStimuli.get_stim_original_size", "domain": "py", "role": "function", "priority": "1", "uri": "api/InfantStimuli.html#DeToX.InfantStimuli.get_stim_original_size", "dispname": "DeToX.InfantStimuli.get_stim_original_size"}, {"name": "DeToX.InfantStimuli", "domain": "py", "role": "class", "priority": "1", "uri": "api/InfantStimuli.html#DeToX.InfantStimuli", "dispname": "-"}, {"name": "DeToX.Utils.InfantStimuli", "domain": "py", "role": "class", "priority": "1", "uri": "api/InfantStimuli.html#DeToX.InfantStimuli", "dispname": "DeToX.InfantStimuli"}, {"name": "DeToX.ETSettings.AnimationSettings", "domain": "py", "role": "class", "priority": "1", "uri": "api/ETSettings.AnimationSettings.html#DeToX.ETSettings.AnimationSettings", "dispname": "-"}, {"name": "DeToX.ETSettings.CalibrationColors", "domain": "py", "role": "class", "priority": "1", "uri": "api/ETSettings.CalibrationColors.html#DeToX.ETSettings.CalibrationColors", "dispname": "-"}, {"name": "DeToX.ETSettings.UIElementSizes", "domain": "py", "role": "class", "priority": "1", "uri": "api/ETSettings.UIElementSizes.html#DeToX.ETSettings.UIElementSizes", "dispname": "-"}, {"name": "DeToX.ETSettings.FontSizeMultipliers", "domain": "py", "role": "class", "priority": "1", "uri": "api/ETSettings.FontSizeMultipliers.html#DeToX.ETSettings.FontSizeMultipliers", "dispname": "-"}]} \ No newline at end of file diff --git a/docs/_site/resources/logo/full_logo.png b/Documentation/resources/full_logo.png similarity index 100% rename from docs/_site/resources/logo/full_logo.png rename to Documentation/resources/full_logo.png diff --git a/docs/styles.scss b/Documentation/styles.scss similarity index 100% rename from docs/styles.scss rename to Documentation/styles.scss diff --git a/_site/Vignettes/GettingStarted.html b/_site/Vignettes/GettingStarted.html new file mode 100644 index 0000000..d5a4a0f --- /dev/null +++ b/_site/Vignettes/GettingStarted.html @@ -0,0 +1,1126 @@ + + + + + + + + + + + +Getting Started with DeToX – DeToX + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+ +
+ + +
+ + + +
+ +
+
+

Getting Started with DeToX

+
+ +
+
+ Starting using DeToX +
+
+ + +
+ +
+
Author
+
+

Tommaso Ghilardi

+
+
+ + + +
+ + + +
+ + +

Great! You’ve got DeToX installed—now let’s jump into the exciting part!

+

This tutorial will walk you through an EXTREMELY basic example showing what DeToX can do and what you’ll need to get started. Think of it as your quick-start guide to running your first eye-tracking experiment.

+
+
+
+ +
+
+Before we begin +
+
+
+

This tutorial walks you through the essential steps for running an eye-tracking experiment with DeToX. We’ve designed it to be as straightforward as possible, though you’ll need some basic familiarity with PsychoPy - specifically how to create windows and display stimuli. If you’re new to PsychoPy or need a refresher, their official tutorial is an excellent starting point.

+

Don’t worry if you’re not a PsychoPy expert! The concepts we’ll use are fundamental and easy to pick up.

+
+
+

DeToX bridges two powerful Python libraries: PsychoPy and tobii_research.

+
    +

  • PsychoPy is your experiment-building toolkit. It gives you the flexibility and control to design studies exactly how you want them—from simple reaction time tasks to complex visual paradigms.

    • +

  • tobii_research is your direct line to Tobii eye trackers. It’s incredibly powerful, but let’s be honest—some of its low-level details can be… complex.

    • +
+

That’s where DeToX comes in: we’ve wrapped the tricky bits so you can focus on your research, not wrestling with SDK documentation.

+
+

Preparation

+

let’s begin importing the libraries that we will need for this example

+
+
from psychopy import visual, core
+from DeToX import ETracker
+
+

visual and core are some of PsychoPy’s main modules—it’s what you’ll use to create the window where your stimuli appear and your experiment runs.

+

ETracker is DeToX’s main class and your central hub for all eye-tracking operations. This is the object you’ll interact with throughout your experiment to control calibration, recording, and data collection.

+
+
+

Window

+

Every experiment needs a stage—in PsychoPy, that’s your Window. This is where all your stimuli will appear and where participants will interact with your study.

+
+
# Create the experiment window
+win = visual.Window(
+    size=[1920, 1080],  # Window dimensions in pixels
+    fullscr=True,       # Expand to fill the entire screen
+    units='pix'         # Use pixels as the measurement unit
+)
+
+

Breaking it down:

+
    +

  • size: Sets your window dimensions. Here we’re using 1920×1080, but adjust this to match your monitor.

    • +

  • fullscr=True: Makes the window take over the whole screen—crucial for experiments where you want to eliminate distractions.

    • +

  • units='pix': Defines how you’ll specify positions and sizes throughout your experiment. DeToX supports multiple PsychoPy unit systems—'height', 'norm', 'pix'—so choose whichever you’re most comfortable with or best fits your experimental design.

    • +
+
+
+
+ +
+
+Window size +
+
+
+

If you’re following along with this tutorial and experimenting on your own, we strongly recommend using a smaller window with fullscr=False instead of fullscreen mode. When fullscr=True, the window takes over your entire screen, making it tricky (or impossible!) to interact with your computer—like stopping the script or checking documentation. Save fullscreen for your actual experiments.

+
+
+

Perfect now we have our window where we can draw images, videos and interact with them!!

+
+
+

ETracker

+

So far we’ve focused on creating the canvas for our stimuli—but how do we actually interact with the eye tracker? Simple! We use the ETracker class we imported earlier.

+

The ETracker needs access to the window we just created, so initializing it is straightforward:

+
+
ET_controller = ETracker(win)
+
+
+
+
+ +
+
+Don’t Have an Eye Tracker? No Problem! +
+
+
+

If you’re following along without a Tobii eye tracker connected, you can still test everything using simulation mode. Just pass simulate=True when creating your ETracker:

+
+
ET_controller = ETracker(win, simulate=True)
+
+

This tells DeToX to collect data from your mouse position instead of an actual eye tracker—perfect for development, testing, or learning the workflow before you have hardware access 😉

+
+
+

Once you run this code, DeToX will connect to your eye tracker and set everything up for you. It will also gather information about the connected device and display it in a nice, readable format:

+
┌────────────────── Eyetracker Info ──────────────────┐
+│Connected to the eyetracker:                         │
+│ - Model: Tobii Pro Fusion                           │
+│ - Current frequency: 250.0 Hz                       │
+│ - Current illumination mode: Default                │
+│Other options:                                       │
+│ - Possible frequencies: (30.0, 60.0, 120.0, 250.0)  │
+│ - Possible illumination modes: ('Default',)         │
+└─────────────────────────────────────────────────────┘
+

This tells us we’re connected to the eye tracker and ready to start recording data!

+
+
+

Recod data

+

Great! You’re now connected to the eye-tracker (or simulating it). However, we’re not actually collecting any data yet - let’s fix that.

+

To begin data collection, call the start_recording method on your ETracker instance:

+
+
# Start recording data
+ET_controller.start_recording(filename="testing.h5")
+
+

The start_recording method accepts a filename parameter for naming your data file. If you don’t specify one, DeToX automatically generates a timestamp-based filename.

+

Your eye-tracking data is now being collected continuously and will be later saved in a HDF5 format, which is ideal for storing large datasets efficiently. For details on the data structure and how to analyze your files, see our DataFormats guide.

+
+
+

Events

+

OK, now that we’re recording data, we can show images, videos, or whatever we want! It’s entirely up to you and your experimental design!

+

Since this is a SUPER BASIC example to get you started, we won’t overcomplicate things with elaborate stimuli or complex tasks. Let’s keep it stupidly simple. As we show images, videos or whatnot we need to keep track at which point thesee stimuli happen in our eyetracking data. And how to do so?? well we can use the record_event function!!

+
+
# Send event 1
+ET_controller.record_event('wait 1')
+core.wait(2) # wait 2s
+
+# Send event 2
+ET_controller.record_event('wait 2')
+core.wait(2) # wait 2s
+
+

Here’s what’s happening:

+
    +

  • controller.record_event('wait 1'): Drops a timestamped marker labeled 'wait 1' into your data stream. This is like planting a flag that says “something important happened HERE.”

    • +

  • core.wait(2): Pauses execution for 2 seconds. During this time, the eye tracker keeps collecting gaze data in the background.

    • +

  • controller.record_event('wait 2'): Plants another marker at the 2-second point, labeled 'wait 2'.

    • +

  • Another core.wait(2): Waits another 2 seconds.

    • +
+

Here we’re just using core.wait() as a placeholder. In your actual experiment, this is where you’d display your stimuli—show images, play videos, present text, or run whatever task your study requires. The record_event() calls mark when those stimuli begin in this case!

+
+
+

Stop recording

+

After the experiment is done, we need to stop the recording and save the data!!!

+
+
# Stop recording data
+ET_controller.stop_recording()
+
+

Voilà! DeToX will stop the recording and automatically save all your data to a file. You’ll get another nice confirmation message showing you what happened:

+
┌────────────── Recording Complete ───────────────┐
+│Data collection lasted approximately 4.02 seconds│
+│Data has been saved to testing.h5                │
+└─────────────────────────────────────────────────┘
+

This tells you how long the recording session lasted and where your data file was saved. By default, DeToX creates a timestamped filename (like testing.h5) so you never accidentally overwrite previous recordings.

+

And that’s it! Your eye-tracking data—complete with all those event markers you recorded—is now safely stored and ready for analysis.

+ + + + +
+ + Back to top
+ + +
+ + + + + + \ No newline at end of file diff --git a/_site/Vignettes/Installation.html b/_site/Vignettes/Installation.html new file mode 100644 index 0000000..86ede74 --- /dev/null +++ b/_site/Vignettes/Installation.html @@ -0,0 +1,1010 @@ + + + + + + + + + + +Installation – DeToX + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+ +
+ + +
+ + + +
+ +
+
+

Installation

+
+ + + +
+ +
+
Author
+
+

Tommaso Ghilardi

+
+
+ + + +
+ + + +
+ + +

So you’re interested in using DeToX? Awesome! Let’s get you set up quickly.

+

DeToX is designed as a lightweight wrapper around PsychoPy and tobii_research. Here’s the good news: tobii_research usually comes bundled with PsychoPy, which means the only real hurdle is installing PsychoPy itself. And yes, PsychoPy can be a bit tricky to install due to its many dependencies—but don’t worry, we’ll walk you through it. Once PsychoPy is up and running, adding DeToX is a breeze.

+
+

Installing PsychoPy

+

Since PsychoPy is the main challenge, let’s tackle that first. You have two main options:

+
    +

  • Package Installation

    +

    Install PsychoPy like any other Python package using pip. This approach is flexible and ideal if you prefer working in an IDE (like Positron, VS Code, PyCharm, or Spyder) where you have full control over your Python environment.

    • +

  • Standalone Installation

    +

    Use the PsychoPy standalone installer, which bundles PsychoPy and all its dependencies into a single, ready-to-use application. This is often the easiest way to get started, especially if you’re not familiar with managing Python environments or just want to hit the ground running.

    • +
+

We like installing psychopy as a package but you do you!

+
+ +
+
+

This method is ideal if you prefer working in an IDE (like Positron, VS Code, PyCharm, or Spyder) and want full control over your Python environment.

+
+

Step 1: Create a Virtual Environment

+

We like to use miniforge to handle our environments and Python installations. Any other method would work as well, but for simplicity we’ll show you how we prefer to do it.

+

We recommend using Python 3.10 for the best compatibility:

+
mamba create -n detox_env python=3.10
+

This will create an environment called detox_env with python 3.10. Exactly what we need!

+

You will probably need to confirm by pressing y, and after a few seconds you’ll have your environment with Python 3.10! Great!

+
+
+

Step 2: Activate Environment and Install PsychoPy

+

Now let’s activate this environment (making sure we’re using it) and then install PsychoPy:

+
mamba activate detox_env
+pip install psychopy
+

this will take some time but if you are lucky you will have psychopy in your enviroment

+

Again, confirm if needed and you’re done! Amazing!

+
+
+
+

PsychoPy is a large package with many dependencies, and sometimes (depending on your operating system) installing it can be quite tricky! For this reason, the PsychoPy website suggests using the standalone installation method. This is like installing regular software on your computer - it will install PsychoPy and all its dependencies in one go.

+
+

Step 1: Install PsychoPy Standalone

+
    +

  1. Go to the PsychoPy download page

    2. +

  2. Download the standalone installer for your operating system

    3. +

  3. Run the installer and follow the setup instructions

    4. +
+

You are done!!! Great!

+
+
+
+
+
+
+

Installing DeToX

+

Once PsychoPy is installed, we can look at DeToX. Let’s gets our hand dirty! The installation is the same for both the Package and Standalone PsychoPy installations but some steps differ.

+
+
+
+ +
+
+DeToX is Still in Development +
+
+
+

DeToX isn’t yet available on PyPI, so you’ll need to install it directly from our GitHub repository. Don’t worry—it’s straightforward, and we’ll guide you through it!

+

One requirement: You need Git installed on your system.

+

📥 Don’t have Git? Download it from git-scm.com—installation takes just a minute.

+
+
+
+ +
+
+

Again make sure to be in the correct environment if you installed PsychoPy as a package. with the following command:

+
mamba activate detox_env
+

Then simply run:

+
pip install git+https://github.com/DevStart-Hub/DeToX.git
+

Wait a few seconds, confirm if needed, and you are done!

+
+
+
    +

  1. Open PsychoPy

    2. +

  2. Go to Coder View (the interface with the code editor)

    3. +

  3. Open the Tools menu

    4. +

  4. Select “Plugins/package manager…”

    5. +

  5. Click on “Packages” in the top tabs

    6. +

  6. Click the “Open PIP terminal” button

    7. +

  7. Type the following command: pip install git+https://github.com/DevStart-Hub/DeToX.git

    8. +
+

That’s it! You now have both PsychoPy and DeToX installed and ready to use.

+
+
+
+
+
+
+ +
+
+Important: DeToX requires coding +
+
+
+

DeToX is a code-based library that works with PsychoPy’s Coder interface. If you typically use PsychoPy’s Builder (the drag-and-drop visual interface), you’ll need to switch to the Coder interface to use DeToX. Don’t worry - we provide plenty of code examples to get you started!

+
+
+ + + + +
+ + Back to top
+ + +
+ + + + + + \ No newline at end of file diff --git a/docs/_site/api/ETracker.html b/_site/api/BaseCalibrationSession.html similarity index 50% rename from docs/_site/api/ETracker.html rename to _site/api/BaseCalibrationSession.html index a08cb56..4ee6999 100644 --- a/docs/_site/api/ETracker.html +++ b/_site/api/BaseCalibrationSession.html @@ -7,7 +7,7 @@ -etracker – DeToX +basecalibrationsession – DeToX + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+ +
+ + +
+ + + +

+ + + + +
+

ETSettings.AnimationSettings

+
ETSettings.AnimationSettings(
+    focus_time=0.5,
+    zoom_speed=6.0,
+    max_zoom_size=0.11,
+    min_zoom_size=0.05,
+    trill_size=0.075,
+    trill_rotation_range=20,
+    trill_cycle_duration=1.5,
+    trill_active_duration=1.1,
+    trill_frequency=3.0,
+)
+

Animation parameters for calibration stimuli.

+

Controls the behavior and appearance of animated calibration targets including zoom and trill animations. All size parameters are specified in height units (percentage of screen height).

+
+

Attributes

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
focus_timefloatWait time in seconds before collecting calibration data at each point. Allows participant to fixate on the target. Default is 0.5 seconds.
zoom_speedfloatSpeed multiplier for the zoom animation. Higher values make the size oscillation faster. Default is 6.0.
max_zoom_sizefloatMaximum size for zoom animation as percentage of screen height. Default is 0.11 (11% of screen height).
min_zoom_sizefloatMinimum size for zoom animation as percentage of screen height. Default is 0.05 (5% of screen height).
trill_sizefloatFixed size for trill animation as percentage of screen height. Default is 0.075 (7.5% of screen height).
trill_rotation_rangefloatMaximum rotation angle in degrees for trill animation. Default is 20 degrees.
trill_cycle_durationfloatTotal cycle time for trill animation in seconds (active + pause). Default is 1.5 seconds.
trill_active_durationfloatDuration of active trill rotation in seconds, within each cycle. Default is 1.1 seconds (leaves 0.4s pause).
trill_frequencyfloatNumber of back-and-forth rotation oscillations per second during active trill phase. Default is 3.0 oscillations/second.
+
+
+

Examples

+
>>> settings = AnimationSettings()
+>>> settings.max_zoom_size = 0.15  # Increase max size to 15%
+>>> settings.trill_frequency = 5.0  # Faster trill
+ + + + +
+
+ + Back to top
+ + +
+ + + + + + \ No newline at end of file diff --git a/_site/api/ETSettings.CalibrationColors.html b/_site/api/ETSettings.CalibrationColors.html new file mode 100644 index 0000000..edb56fd --- /dev/null +++ b/_site/api/ETSettings.CalibrationColors.html @@ -0,0 +1,1114 @@ + + + + + + + + + +etsettings.calibrationcolors – DeToX + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+ +
+ + +
+ + + +

+ + + + +
+

ETSettings.CalibrationColors

+
ETSettings.CalibrationColors(
+    left_eye=(0, 255, 0, 255),
+    right_eye=(255, 0, 0, 255),
+    mouse=(255, 128, 0, 255),
+    target_outline=(24, 24, 24, 255),
+    highlight=(255, 255, 0, 255),
+)
+

Color settings for calibration visual elements.

+

Defines RGBA color values for various calibration display components including eye tracking samples, target outlines, and highlights.

+
+

Attributes

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
left_eyetuple of intRGBA color for Tobii left eye gaze samples (R, G, B, A). Default is (0, 255, 0, 255) - bright green.
right_eyetuple of intRGBA color for Tobii right eye gaze samples (R, G, B, A). Default is (255, 0, 0, 255) - bright red.
mousetuple of intRGBA color for simulated mouse position samples (R, G, B, A). Default is (255, 128, 0, 255) - orange.
target_outlinetuple of intRGBA color for calibration target circle outlines (R, G, B, A). Default is (24, 24, 24, 255) - dark gray/black.
highlighttuple of intRGBA color for highlighting selected calibration points (R, G, B, A). Default is (255, 255, 0, 255) - bright yellow.
+
+
+

Notes

+

All color values use 8-bit channels (0-255 range) in RGBA format. The alpha channel (A) controls opacity where 255 is fully opaque.

+
+
+

Examples

+
>>> colors = CalibrationColors()
+>>> colors.highlight = (0, 255, 255, 255)  # Change to cyan
+>>> colors.left_eye = (0, 200, 0, 200)  # Semi-transparent green
+ + + + +
+
+ + Back to top
+ + +
+ + + + + + \ No newline at end of file diff --git a/_site/api/ETSettings.FontSizeMultipliers.html b/_site/api/ETSettings.FontSizeMultipliers.html new file mode 100644 index 0000000..d673e95 --- /dev/null +++ b/_site/api/ETSettings.FontSizeMultipliers.html @@ -0,0 +1,1094 @@ + + + + + + + + + +etsettings.fontsizemultipliers – DeToX + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+ +
+ + +
+ + + +

+ + + + +
+

ETSettings.FontSizeMultipliers

+
ETSettings.FontSizeMultipliers(
+    instruction_text=1.5,
+    message_text=1.3,
+    title_text=1.4,
+)
+

Font size multipliers for different text types.

+

Defines scaling factors applied to the base text size (from UIElementSizes) for different types of text displays in the calibration interface.

+
+

Attributes

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
instruction_textfloatMultiplier for instruction text displayed during calibration. Default is 1.5 (150% of base text size).
message_textfloatMultiplier for general message text. Default is 1.3 (130% of base text size).
title_textfloatMultiplier for title text in message boxes. Default is 1.4 (140% of base text size).
+
+
+

Notes

+

The final text size is calculated as: base_text_size * multiplier where base_text_size comes from UIElementSizes.text.

+
+
+

Examples

+
>>> font_sizes = FontSizeMultipliers()
+>>> font_sizes.instruction_text = 2.0  # Larger instructions
+>>> font_sizes.title_text = 1.8  # Larger titles
+ + + + +
+
+ + Back to top
+ + +
+ + + + + + \ No newline at end of file diff --git a/_site/api/ETSettings.UIElementSizes.html b/_site/api/ETSettings.UIElementSizes.html new file mode 100644 index 0000000..e4d8211 --- /dev/null +++ b/_site/api/ETSettings.UIElementSizes.html @@ -0,0 +1,1141 @@ + + + + + + + + + +etsettings.uielementsizes – DeToX + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+ +
+ + +
+ + + +

+ + + + +
+

ETSettings.UIElementSizes

+
ETSettings.UIElementSizes(
+    highlight=0.04,
+    line_width=0.003,
+    marker=0.02,
+    border=0.005,
+    plot_line=0.002,
+    text=0.025,
+    target_circle=0.012,
+    target_circle_width=0.006,
+)
+

Size settings for user interface elements.

+

Defines sizes for various UI components in the calibration interface. All sizes are specified in height units (as fraction of screen height) and are automatically converted to appropriate units based on the PsychoPy window configuration.

+
+

Attributes

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
highlightfloatRadius of circles highlighting selected calibration points for retry. Default is 0.04 (4% of screen height).
line_widthfloatThickness of lines drawn in calibration visualizations. Default is 0.003 (0.3% of screen height).
markerfloatSize of markers indicating data collection points. Default is 0.02 (2% of screen height).
borderfloatThickness of the red calibration mode border around the screen. Default is 0.005 (0.5% of screen height).
plot_linefloatWidth of lines in calibration result plots connecting targets to samples. Default is 0.002 (0.2% of screen height).
textfloatBase text height for all text displays in the calibration interface. Default is 0.025 (2.5% of screen height).
target_circlefloatRadius of target circles drawn in calibration result visualizations. Default is 0.012 (1.2% of screen height).
target_circle_widthfloatLine width for target circle outlines in result visualizations. Default is 0.006 (0.6% of screen height).
+
+
+

Notes

+

Height units provide consistent visual appearance across different screen sizes and aspect ratios. The conversion to pixels or other units is handled automatically by the coordinate conversion functions.

+
+
+

Examples

+
>>> ui_sizes = UIElementSizes()
+>>> ui_sizes.highlight = 0.06  # Larger highlight circles
+>>> ui_sizes.text = 0.035  # Larger text
+ + + + +
+
+ + Back to top
+ + +
+ + + + + + \ No newline at end of file diff --git a/docs/_site/api/ETracker.calibrate.html b/_site/api/ETracker.calibrate.html similarity index 57% rename from docs/_site/api/ETracker.calibrate.html rename to _site/api/ETracker.calibrate.html index 3ca29db..a4fa356 100644 --- a/docs/_site/api/ETracker.calibrate.html +++ b/_site/api/ETracker.calibrate.html @@ -64,6 +64,10 @@ + + + + @@ -101,9 +105,25 @@ } } + + + - - @@ -114,7 +134,7 @@
DeToX @@ -125,32 +145,22 @@ @@ -197,13 +207,13 @@
  • - Function reference + Reference
  • - Some functions + Main Eye-tracker Class @@ -211,16 +221,19 @@ +
    • +
  • +
    + + Internal Calibration + + + +
    + +
    • +
  • +
    + + Coordinate Conversion + + + +
    + +
    • +
  • +
    + + Utilities + + + +
    + +
    • +
  • +
    + + Configuration Settings + + + +
    + @@ -283,7 +466,7 @@
    -
    +

    @@ -411,10 +594,12 @@

    Notes< + + -

    + Back to top
    +
    • + diff --git a/docs/_site/api/ETracker.gaze_contingent.html b/_site/api/ETracker.gaze_contingent.html similarity index 62% rename from docs/_site/api/ETracker.gaze_contingent.html rename to _site/api/ETracker.gaze_contingent.html index 6a63a3e..a7f9752 100644 --- a/docs/_site/api/ETracker.gaze_contingent.html +++ b/_site/api/ETracker.gaze_contingent.html @@ -64,6 +64,10 @@ + + + + @@ -101,9 +105,25 @@ } } + + + - - @@ -114,7 +134,7 @@
    DeToX @@ -125,32 +145,22 @@ @@ -197,13 +207,13 @@
  • - Function reference + Reference
  • - Some functions + Main Eye-tracker Class @@ -211,16 +221,19 @@ +
    • +
  • +
    + + Internal Calibration + + + +
    + +
    • +
  • +
    + + Coordinate Conversion + + + +
    + +
    • +
  • +
    + + Utilities + + + +
    + +
    • +
  • +
    + + Configuration Settings + + + +
    + @@ -283,21 +466,16 @@
    -
    +

    @@ -306,62 +484,13 @@

    On this page

    ETracker.gaze_contingent

    ETracker.gaze_contingent(N=5)

    Initialize real-time gaze buffer for contingent applications.

    -

    Sets up rolling buffer to store recent gaze coordinates for immediate processing during experiments. Enables smooth gaze estimation and real-time gaze-contingent paradigms.

    -
    -

    Parameters

    - ------ - - - - - - - - - - - - - - - - -
    NameTypeDescriptionDefault
    NintNumber of recent gaze samples to buffer. Buffer holds coordinate pairs from both eyes.5
    -
    -
    -

    Raises

    - - - - - - - - - - - - - - - -
    NameTypeDescription
    TypeErrorIf N is not an integer.
    -
    -
    -

    Examples

    -

    tracker.gaze_contingent(10) # Buffer last 10 samples pos = tracker.get_average_gaze() # Get smoothed position

    -
    + + -
    + Back to top
    +
    • + diff --git a/_site/api/ETracker.get_gaze_position.html b/_site/api/ETracker.get_gaze_position.html new file mode 100644 index 0000000..b832aef --- /dev/null +++ b/_site/api/ETracker.get_gaze_position.html @@ -0,0 +1,1167 @@ + + + + + + + + + +etracker.get_gaze_position – DeToX + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + +
    + +
    + + +
    + + + +

    + + + + +
    +

    ETracker.get_gaze_position

    +
    ETracker.get_gaze_position(fallback_offscreen=True, method='median')
    +

    Get current gaze position from rolling buffer.

    +

    Aggregates recent gaze samples from both eyes to provide a stable, real-time gaze estimate. Handles missing or invalid data gracefully.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    fallback_offscreenboolIf True (default), returns an offscreen position (3x screen dimensions) when no valid gaze data is available. If False, returns None.True
    methodstrAggregation method for combining samples and eyes. - “median” (default): Robust to outliers, good for noisy data - “mean”: Smoother but sensitive to outliers - “last”: Lowest latency, uses only most recent sample'median'
    +
    +
    +

    Returns

    + +++++ + + + + + + + + + + + + + + +
    NameTypeDescription
    tuple or NoneGaze position (x, y) in PsychoPy coordinates (current window units), or None if no valid data and fallback_offscreen=False.
    +
    +
    +

    Raises

    + +++++ + + + + + + + + + + + + + + +
    NameTypeDescription
    RuntimeErrorIf gaze_contingent() was not called to initialize the buffer.
    +
    +
    +

    Examples

    +
    >>> # Basic usage (median aggregation)
+>>> pos = tracker.get_gaze_position()
+>>> if pos is not None:
+...     circle.pos = pos
    +
    >>> # Use mean for smoother tracking
+>>> pos = tracker.get_gaze_position(method="mean")
    +
    >>> # Lowest latency (last sample only)
+>>> pos = tracker.get_gaze_position(method="last")
    +
    >>> # Return None instead of offscreen position
+>>> pos = tracker.get_gaze_position(fallback_offscreen=False)
+>>> if pos is None:
+...     print("No valid gaze data")
    + + + + +
    +
    + + Back to top
    + + +
    + + + + + + \ No newline at end of file diff --git a/_site/api/ETracker.html b/_site/api/ETracker.html new file mode 100644 index 0000000..1005f44 --- /dev/null +++ b/_site/api/ETracker.html @@ -0,0 +1,2094 @@ + + + + + + + + + +etracker – DeToX + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + +
    + +
    + + +
    + + + +

    + + + + +
    +

    ETracker

    +
    ETracker(win, etracker_id=0, simulate=False)
    +

    A high-level controller for running eye-tracking experiments with Tobii Pro and PsychoPy.

    +

    The ETracker class is a simplified Python interface designed to streamline the process of running infant eye-tracking experiments. It acts as a bridge between the Tobii Pro SDK (version 3.0 or later) and the popular experiment-building framework, PsychoPy.

    +

    This class is the central hub for your eye-tracking experiment. Instead of managing low-level SDK functions, the TobiiController provides a clean, unified workflow for key experimental tasks. It is designed to “detoxify” the process, abstracting away complex boilerplate code so you can focus on your research.

    +

    Key features include: - Experiment Control: Start, stop, and manage eye-tracking recordings with simple method calls. - Data Management: Automatically save recorded gaze data to a specified file format. - Calibration: Easily run a calibration procedure or load an existing calibration file to prepare the eye-tracker. - Seamless Integration: Built specifically to integrate with PsychoPy’s experimental loop, making it a natural fit for your existing research designs.

    +

    This class is intended to be the first object you instantiate in your experiment script. It provides a minimal yet powerful set of methods that are essential for conducting a reliable and reproducible eye-tracking study.

    +
    +

    Methods

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameDescription
    calibrateRun the infant-friendly calibration procedure.
    gaze_contingentInitialize real-time gaze buffer for contingent applications.
    get_gaze_positionGet current gaze position from rolling buffer.
    load_calibrationLoads calibration data from a file and applies it to the eye tracker.
    record_eventRecord timestamped experimental event during data collection.
    save_calibrationSave the current calibration data to a file.
    save_dataSave buffered gaze and event data to file with optimized processing.
    set_eyetracking_settingsConfigure and apply Tobii eye tracker settings.
    show_statusReal-time visualization of participant’s eye position in track box.
    start_recordingBegin gaze data recording session.
    stop_recordingStop gaze data recording and finalize session.
    +
    +

    calibrate

    +
    ETracker.calibrate(
+    calibration_points,
+    infant_stims,
+    shuffle=True,
+    audio=None,
+    anim_type='zoom',
+    save_calib=False,
+    num_samples=5,
+)
    +

    Run the infant-friendly calibration procedure.

    +

    Automatically selects the calibration method based on operating mode (real eye tracker vs. simulation). Uses animated stimuli and optional audio to engage infants during calibration.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    calibration_pointslist[tuple[float, float]]Target locations in PsychoPy coordinates (e.g., height units). Typically 5�9 points distributed across the screen.required
    infant_stimslist[str]Paths to engaging image files for calibration targets (e.g., animated characters, colorful objects).required
    shuffleboolWhether to randomize stimulus presentation order. Default True.True
    audiopsychopy.sound.Sound | NoneAttention-getting sound to play during calibration. Default None.None
    anim_type(zoom, trill)Animation style for the stimuli. Default ‘zoom’.'zoom'
    save_calibbool | strControls saving of calibration after a successful run: - False: do not save (default) - True: save using default naming (timestamped) - str: save to this filename; if it has no extension, ‘.dat’ is added.False
    num_samplesintSamples per point in simulation mode. Default 5.5
    +
    +
    +

    Returns

    + +++++ + + + + + + + + + + + + + + +
    NameTypeDescription
    boolTrue if calibration completed successfully, False otherwise.
    +
    +
    +

    Notes

    +
      +
    • Real mode uses Tobii’s calibration with result visualization.
      • +
    • Simulation mode uses mouse position to approximate the process.
      • +
    • If in simulation mode, any save request is safely skipped with a warning.
      • +
    +
    +
    +
    +

    gaze_contingent

    +
    ETracker.gaze_contingent(N=5)
    +

    Initialize real-time gaze buffer for contingent applications.

    +
    +
    +

    get_gaze_position

    +
    ETracker.get_gaze_position(fallback_offscreen=True, method='median')
    +

    Get current gaze position from rolling buffer.

    +

    Aggregates recent gaze samples from both eyes to provide a stable, real-time gaze estimate. Handles missing or invalid data gracefully.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    fallback_offscreenboolIf True (default), returns an offscreen position (3x screen dimensions) when no valid gaze data is available. If False, returns None.True
    methodstrAggregation method for combining samples and eyes. - “median” (default): Robust to outliers, good for noisy data - “mean”: Smoother but sensitive to outliers - “last”: Lowest latency, uses only most recent sample'median'
    +
    +
    +

    Returns

    + +++++ + + + + + + + + + + + + + + +
    NameTypeDescription
    tuple or NoneGaze position (x, y) in PsychoPy coordinates (current window units), or None if no valid data and fallback_offscreen=False.
    +
    +
    +

    Raises

    + +++++ + + + + + + + + + + + + + + +
    NameTypeDescription
    RuntimeErrorIf gaze_contingent() was not called to initialize the buffer.
    +
    +
    +

    Examples

    +
    >>> # Basic usage (median aggregation)
+>>> pos = tracker.get_gaze_position()
+>>> if pos is not None:
+...     circle.pos = pos
    +
    >>> # Use mean for smoother tracking
+>>> pos = tracker.get_gaze_position(method="mean")
    +
    >>> # Lowest latency (last sample only)
+>>> pos = tracker.get_gaze_position(method="last")
    +
    >>> # Return None instead of offscreen position
+>>> pos = tracker.get_gaze_position(fallback_offscreen=False)
+>>> if pos is None:
+...     print("No valid gaze data")
    +
    +
    +
    +

    load_calibration

    +
    ETracker.load_calibration(filename=None, use_gui=False)
    +

    Loads calibration data from a file and applies it to the eye tracker.

    +

    This method allows reusing a previously saved calibration, which can save significant time for participants, especially in multi-session studies. The calibration data must be a binary file generated by a Tobii eye tracker, typically via the save_calibration() method. This operation is only available when connected to a physical eye tracker.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    filenamestrThe path to the calibration data file (e.g., “subject_01_calib.dat”). If use_gui is True, this path is used as the default suggestion in the file dialog. If use_gui is False, this parameter is required.None
    use_guiboolIf True, a graphical file-open dialog is displayed for the user to select the calibration file. Defaults to False.False
    +
    +
    +

    Returns

    + +++++ + + + + + + + + + + + + + + +
    NameTypeDescription
    boolReturns True if the calibration was successfully loaded and applied, and False otherwise (e.g., user cancelled the dialog, file not found, or data was invalid).
    +
    +
    +

    Raises

    + +++++ + + + + + + + + + + + + + + + + + + + +
    NameTypeDescription
    RuntimeErrorIf the method is called while the ETracker is in simulation mode.
    ValueErrorIf use_gui is False and filename is not provided.
    +
    +
    +
    +

    record_event

    +
    ETracker.record_event(label)
    +

    Record timestamped experimental event during data collection.

    +

    Events are merged with gaze data based on timestamp proximity during save operations. Uses appropriate timing source for simulation vs. real eye tracker modes.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    labelstrDescriptive label for the event (e.g., ‘trial_start’, ‘stimulus_onset’).required
    +
    +
    +

    Raises

    + + + + + + + + + + + + + + + +
    NameTypeDescription
    RuntimeWarningIf called when recording is not active.
    +
    +
    +

    Examples

    +

    tracker.record_event(‘trial_1_start’) # … present stimulus … tracker.record_event(‘stimulus_offset’)

    +
    +
    +
    +

    save_calibration

    +
    ETracker.save_calibration(filename=None, use_gui=False)
    +

    Save the current calibration data to a file.

    +

    Retrieves the active calibration data from the connected Tobii eye tracker and saves it as a binary file. This can be reloaded later with load_calibration() to avoid re-calibrating the same participant.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    filenamestr | NoneDesired output path. If None and use_gui is False, a timestamped default name is used (e.g., ‘YYYY-mm-dd_HH-MM-SS_calibration.dat’). If provided without an extension, ‘.dat’ is appended. If an extension is already present, it is left unchanged.None
    use_guiboolIf True, opens a file-save dialog (Psychopy) where the user chooses the path. The suggested name respects the logic above. Default False.False
    +
    +
    +

    Returns

    + +++++ + + + + + + + + + + + + + + +
    NameTypeDescription
    boolTrue if saved successfully; False if cancelled, no data available, in simulation mode, or on error.
    +
    +
    +

    Notes

    +
      +
    • In simulation mode, saving is skipped and a warning is issued.
      • +
    • If use_gui is True and the dialog is cancelled, returns False.
      • +
    +
    +
    +
    +

    save_data

    +
    ETracker.save_data()
    +

    Save buffered gaze and event data to file with optimized processing.

    +

    Uses thread-safe buffer swapping to minimize lock time, then processes and saves data in CSV or HDF5 format. Events are merged with gaze data based on timestamp proximity.

    +
    +
    +

    set_eyetracking_settings

    +
    ETracker.set_eyetracking_settings(
+    desired_fps=None,
+    desired_illumination_mode=None,
+    use_gui=False,
+)
    +

    Configure and apply Tobii eye tracker settings.

    +

    This method updates the eye tracker’s sampling frequency (FPS) and illumination mode, either programmatically or via a graphical interface. It ensures that configuration changes are only made when the device is idle and connected.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    desired_fpsintDesired sampling frequency in Hz (e.g., 60, 120, 300). If None, the current frequency is retained.None
    desired_illumination_modestrDesired illumination mode (e.g., ‘Auto’, ‘Bright’, ‘Dark’). If None, the current illumination mode is retained.None
    use_guiboolIf True, opens a PsychoPy GUI dialog that allows users to select settings interactively. Defaults to False.False
    +
    +
    +

    Raises

    + +++++ + + + + + + + + + + + + + + + + + + + +
    NameTypeDescription
    RuntimeErrorIf no physical eye tracker is connected or if the function is called in simulation mode.
    ValueErrorIf the specified FPS or illumination mode is not supported by the connected device.
    +
    +
    +

    Notes

    +
      +
    • Settings cannot be changed during active recording. If an ongoing recording is detected, a non-blocking warning is issued and the function exits safely.
      • +
    • When use_gui=True, a PsychoPy dialog window appears. It must be closed manually before the program continues.
      • +
    • After successfully applying new settings, the internal attributes self.fps and self.illum_mode are updated to reflect the current device configuration.
      • +
    +
    +
    +
    +

    show_status

    +
    ETracker.show_status(decision_key='space')
    +

    Real-time visualization of participant’s eye position in track box.

    +

    Creates interactive display showing left/right eye positions and distance from screen. Useful for positioning participants before data collection. Updates continuously until exit key is pressed.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    decision_keystrKey to press to exit visualization. Default ‘space’.'space'
    +
    +
    +

    Notes

    +

    In simulation mode, use scroll wheel to adjust simulated distance. Eye positions shown as green (left) and red (right) circles.

    +
    +
    +
    +

    start_recording

    +
    ETracker.start_recording(filename=None, raw_format=False)
    +

    Begin gaze data recording session.

    +

    Initializes file structure, clears any existing buffers, and starts data collection from either the eye tracker or simulation mode. Creates HDF5 or CSV files based on filename extension.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    filenamestrOutput filename for gaze data. If None, generates timestamp-based name. File extension determines format (.h5/.hdf5 for HDF5, .csv for CSV, defaults to .h5).None
    raw_formatboolIf True, preserves all original Tobii SDK column names and data. If False (default), uses simplified column names and subset of columns. Raw format is useful for advanced analysis requiring full metadata.False
    +
    +
    +

    Examples

    +
    +
    +
    +
    +
    +

    Standard format (simplified columns)

    +

    tracker.start_recording(‘data.h5’)

    +
    +
    +

    Raw format (all Tobii SDK columns preserved)

    +

    tracker.start_recording(‘data_raw.h5’, raw_format=True)

    +
    +

    stop_recording

    +
    ETracker.stop_recording()
    +

    Stop gaze data recording and finalize session.

    +

    Performs complete shutdown: stops data collection, cleans up resources, saves all buffered data, and reports session summary. Handles both simulation and real eye tracker modes appropriately.

    +
    +

    Raises

    + + + + + + + + + + + + + + + +
    NameTypeDescription
    UserWarningIf recording is not currently active.
    +
    +
    +

    Notes

    +

    All pending data in buffers is automatically saved before completion. Recording duration is measured from start_recording() call.

    + + + + +
    +
    +
    + + Back to top
    + + +
    + + + + + + \ No newline at end of file diff --git a/docs/_site/api/ETracker.load_calibration.html b/_site/api/ETracker.load_calibration.html similarity index 59% rename from docs/_site/api/ETracker.load_calibration.html rename to _site/api/ETracker.load_calibration.html index a8c9c36..3b93ee0 100644 --- a/docs/_site/api/ETracker.load_calibration.html +++ b/_site/api/ETracker.load_calibration.html @@ -64,6 +64,10 @@ + + + + @@ -101,9 +105,25 @@ } } + + + - - @@ -114,7 +134,7 @@
    DeToX @@ -125,32 +145,22 @@ @@ -197,13 +207,13 @@
  • - Function reference + Reference
  • - Some functions + Main Eye-tracker Class @@ -211,16 +221,19 @@ +
    • +
  • +
    + + Internal Calibration + + + +
    + +
    • +
  • +
    + + Coordinate Conversion + + + +
    + +
    • +
  • +
    + + Utilities + + + +
    + +
    • +
  • +
    + + Configuration Settings + + + +
    + @@ -283,7 +466,7 @@
    -
    +

    @@ -394,10 +577,12 @@

    Rais + + -

    + Back to top
    +
    • + diff --git a/docs/_site/api/ETracker.record_event.html b/_site/api/ETracker.record_event.html similarity index 60% rename from docs/_site/api/ETracker.record_event.html rename to _site/api/ETracker.record_event.html index b7696da..0b49f14 100644 --- a/docs/_site/api/ETracker.record_event.html +++ b/_site/api/ETracker.record_event.html @@ -64,6 +64,10 @@ + + + + @@ -101,9 +105,25 @@ } } + + + - - @@ -114,7 +134,7 @@
    DeToX @@ -125,32 +145,22 @@ @@ -197,13 +207,13 @@
  • - Function reference + Reference
  • - Some functions + Main Eye-tracker Class @@ -211,16 +221,19 @@ +
    • +
  • +
    + + Internal Calibration + + + +
    + +
    • +
  • +
    + + Coordinate Conversion + + + +
    + +
    • +
  • +
    + + Utilities + + + +
    + +
    • +
  • +
    + + Configuration Settings + + + +
    + @@ -283,7 +466,7 @@
    -
    +

    @@ -358,10 +541,12 @@

    tracker.record_event(‘trial_1_start’) # … present stimulus … tracker.record_event(‘stimulus_offset’)

    + + -

    + Back to top
    +
    • + diff --git a/docs/_site/api/ETracker.save_calibration.html b/_site/api/ETracker.save_calibration.html similarity index 59% rename from docs/_site/api/ETracker.save_calibration.html rename to _site/api/ETracker.save_calibration.html index e21e209..1a24043 100644 --- a/docs/_site/api/ETracker.save_calibration.html +++ b/_site/api/ETracker.save_calibration.html @@ -64,6 +64,10 @@ + + + + @@ -101,9 +105,25 @@ } } + + + - - @@ -114,7 +134,7 @@
    DeToX @@ -125,32 +145,22 @@ @@ -197,13 +207,13 @@
  • - Function reference + Reference
  • - Some functions + Main Eye-tracker Class @@ -211,16 +221,19 @@ +
    • +
  • +
    + + Internal Calibration + + + +
    + +
    • +
  • +
    + + Coordinate Conversion + + + +
    + +
    • +
  • +
    + + Utilities + + + +
    + +
    • +
  • +
    + + Configuration Settings + + + +
    + @@ -283,7 +466,7 @@
    -
    +

    @@ -372,10 +555,12 @@

    Notes< + + -

    + Back to top
    +
    • + diff --git a/docs/_site/api/ETracker.save_data.html b/_site/api/ETracker.save_data.html similarity index 62% rename from docs/_site/api/ETracker.save_data.html rename to _site/api/ETracker.save_data.html index 527957d..5b4758f 100644 --- a/docs/_site/api/ETracker.save_data.html +++ b/_site/api/ETracker.save_data.html @@ -64,6 +64,10 @@ + + + + @@ -101,9 +105,25 @@ } } + + + - - @@ -114,7 +134,7 @@
    DeToX @@ -125,32 +145,22 @@ @@ -197,13 +207,13 @@
  • - Function reference + Reference
  • - Some functions + Main Eye-tracker Class @@ -211,16 +221,19 @@ +
    • +
  • +
    + + Internal Calibration + + + +
    + +
    • +
  • +
    + + Coordinate Conversion + + + +
    + +
    • +
  • +
    + + Utilities + + + +
    + +
    • +
  • +
    + + Configuration Settings + + + +
    + @@ -283,7 +466,7 @@
    -
    +

    @@ -304,9 +487,11 @@

    ETracker.save_data

    Uses thread-safe buffer swapping to minimize lock time, then processes and saves data in CSV or HDF5 format. Events are merged with gaze data based on timestamp proximity.

    + + -
    + Back to top
    +
    • + diff --git a/docs/_site/api/ETracker.show_status.html b/_site/api/ETracker.show_status.html similarity index 61% rename from docs/_site/api/ETracker.show_status.html rename to _site/api/ETracker.show_status.html index e126ab5..7069c01 100644 --- a/docs/_site/api/ETracker.show_status.html +++ b/_site/api/ETracker.show_status.html @@ -64,6 +64,10 @@ + + + + @@ -101,9 +105,25 @@ } } + + + - - @@ -114,7 +134,7 @@
    DeToX @@ -125,32 +145,22 @@ @@ -197,13 +207,13 @@
  • - Function reference + Reference
  • - Some functions + Main Eye-tracker Class @@ -211,16 +221,19 @@ +
    • +
  • +
    + + Internal Calibration + + + +
    + +
    • +
  • +
    + + Coordinate Conversion + + + +
    + +
    • +
  • +
    + + Utilities + + + +
    + +
    • +
  • +
    + + Configuration Settings + + + +
    + @@ -283,7 +466,7 @@
    -
    +

    @@ -338,10 +521,12 @@

    Notes<

    In simulation mode, use scroll wheel to adjust simulated distance. Eye positions shown as green (left) and red (right) circles.

    + + -

    + Back to top
    +
    • + diff --git a/docs/_site/api/ETracker.start_recording.html b/_site/api/ETracker.start_recording.html similarity index 57% rename from docs/_site/api/ETracker.start_recording.html rename to _site/api/ETracker.start_recording.html index 3977e04..8641ee2 100644 --- a/docs/_site/api/ETracker.start_recording.html +++ b/_site/api/ETracker.start_recording.html @@ -64,6 +64,10 @@ + + + + @@ -101,9 +105,25 @@ } } + + + - - @@ -114,7 +134,7 @@
    DeToX @@ -125,32 +145,22 @@ @@ -197,13 +207,13 @@
  • - Function reference + Reference
  • - Some functions + Main Eye-tracker Class @@ -211,16 +221,19 @@ +
    • +
  • +
    + + Internal Calibration + + + +
    + +
    • +
  • +
    + + Coordinate Conversion + + + +
    + +
    • +
  • +
    + + Utilities + + + +
    + +
    • +
  • +
    + + Configuration Settings + + + +
    + @@ -283,27 +466,29 @@
    -
    +

    ETracker.start_recording

    -
    ETracker.start_recording(filename=None)
    +
    ETracker.start_recording(filename=None, raw_format=False)

    Begin gaze data recording session.

    Initializes file structure, clears any existing buffers, and starts data collection from either the eye tracker or simulation mode. Creates HDF5 or CSV files based on filename extension.

    @@ -311,9 +496,9 @@

    + + - - @@ -330,33 +515,33 @@

    -

    Raises

    - - - - - - - - - - - - - + + + + +
    NameTypeDescription
    UserWarningIf recording is already in progress.
    raw_formatboolIf True, preserves all original Tobii SDK column names and data. If False (default), uses simplified column names and subset of columns. Raw format is useful for advanced analysis requiring full metadata.False
    +
    +
    +

    Examples

    +
    +
    +
    +

    Standard format (simplified columns)

    +

    tracker.start_recording(‘data.h5’)

    +
    +
    +

    Raw format (all Tobii SDK columns preserved)

    +

    tracker.start_recording(‘data_raw.h5’, raw_format=True)

    -
    + + -
    + Back to top
    +
    • + diff --git a/docs/_site/api/ETracker.stop_recording.html b/_site/api/ETracker.stop_recording.html similarity index 61% rename from docs/_site/api/ETracker.stop_recording.html rename to _site/api/ETracker.stop_recording.html index e520186..1b35f1e 100644 --- a/docs/_site/api/ETracker.stop_recording.html +++ b/_site/api/ETracker.stop_recording.html @@ -64,6 +64,10 @@ + + + + @@ -101,9 +105,25 @@ } } + + + - - @@ -114,7 +134,7 @@
    DeToX @@ -125,32 +145,22 @@ @@ -197,13 +207,13 @@
  • - Function reference + Reference
  • - Some functions + Main Eye-tracker Class @@ -211,16 +221,19 @@ +
    • +
  • +
    + + Internal Calibration + + + +
    + +
    • +
  • +
    + + Coordinate Conversion + + + +
    + +
    • +
  • +
    + + Utilities + + + +
    + +
    • +
  • +
    + + Configuration Settings + + + +
    + @@ -283,7 +466,7 @@
    -
    +

    @@ -330,10 +513,12 @@

    Notes<

    All pending data in buffers is automatically saved before completion. Recording duration is measured from start_recording() call.

    + + -

    + Back to top
    +
    • + diff --git a/_site/api/InfantStimuli.html b/_site/api/InfantStimuli.html new file mode 100644 index 0000000..928f1f8 --- /dev/null +++ b/_site/api/InfantStimuli.html @@ -0,0 +1,1306 @@ + + + + + + + + + +infantstimuli – DeToX + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + +
    + +
    + + +
    + + + +

    + + + + +
    +

    InfantStimuli

    +
    InfantStimuli(win, infant_stims, shuffle=True, **kwargs)
    +

    Stimuli manager for infant-friendly calibration procedures.

    +

    This class provides a sophisticated stimulus presentation system designed specifically for infant eye tracking calibration. It manages a collection of engaging visual stimuli (typically colorful, animated images) and handles their sequential presentation during calibration procedures.

    +

    The class maintains the original size information for each stimulus and supports randomized presentation order to prevent habituation. It’s designed to work seamlessly with both Tobii hardware calibration and mouse-based simulation modes.

    +

    Key features include: - Automatic stimulus loading from image files - Configurable presentation order (sequential or randomized) - Size preservation for animation calculations - Modulo indexing for circular stimulus access - Integration with PsychoPy’s visual system

    +
    +

    Attributes

    + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescription
    winpsychopy.visual.WindowThe PsychoPy window used for rendering.
    stimsdictDictionary mapping indices to ImageStim objects.
    stim_sizedictDictionary mapping indices to original stimulus sizes.
    present_orderlistList defining the presentation sequence of stimuli.
    +
    +
    +

    Methods

    + + + + + + + + + + + + + + + + + +
    NameDescription
    get_stimGet the stimulus by presentation order.
    get_stim_original_sizeGet the original size of the stimulus by presentation order.
    +
    +

    get_stim

    +
    InfantStimuli.get_stim(idx)
    +

    Get the stimulus by presentation order.

    +

    Retrieves a stimulus based on its position in the presentation sequence. Uses modulo arithmetic to wrap around when the index exceeds the number of available stimuli, enabling circular access patterns.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    idxintThe index of the stimulus in the presentation order. Can be any non-negative integer; values beyond the stimulus count will wrap around using modulo operation.required
    +
    +
    +

    Returns

    + +++++ + + + + + + + + + + + + + + +
    NameTypeDescription
    psychopy.visual.ImageStimThe stimulus corresponding to the given index in the presentation order. The returned stimulus is ready for positioning, animation, and drawing operations.
    +
    +
    +

    Examples

    +
    >>> stim_manager = InfantStimuli(win, ['img1.png', 'img2.png'])
+>>> stim = stim_manager.get_stim(0)  # Get first stimulus
+>>> stim = stim_manager.get_stim(5)  # Wraps around if only 2 stimuli
    +
    +
    +
    +

    get_stim_original_size

    +
    InfantStimuli.get_stim_original_size(idx)
    +

    Get the original size of the stimulus by presentation order.

    +

    Returns the original dimensions of a stimulus as loaded from the image file. This is useful for animation calculations where you need to know the base size before applying scaling transformations.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    idxintThe index of the stimulus in the presentation order. Can be any non-negative integer; values beyond the stimulus count will wrap around using modulo operation.required
    +
    +
    +

    Returns

    + +++++ + + + + + + + + + + + + + + +
    NameTypeDescription
    tupleThe original size of the stimulus as (width, height) in the units specified during stimulus creation. These values represent the stimulus dimensions before any scaling or animation effects.
    +
    +
    +

    Notes

    +

    The original size is preserved at initialization and remains constant throughout the session, regardless of any size modifications made to the stimulus during animation.

    + + + + +
    +
    +
    +
    + + Back to top
    + + +
    + + + + + + \ No newline at end of file diff --git a/_site/api/MouseCalibrationSession.html b/_site/api/MouseCalibrationSession.html new file mode 100644 index 0000000..003228f --- /dev/null +++ b/_site/api/MouseCalibrationSession.html @@ -0,0 +1,1159 @@ + + + + + + + + + +mousecalibrationsession – DeToX + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + +
    + +
    + + +
    + + + +

    + + + + +
    +

    MouseCalibrationSession

    +
    MouseCalibrationSession(
+    win,
+    infant_stims,
+    mouse,
+    shuffle=True,
+    audio=None,
+    anim_type='zoom',
+)
    +

    Mouse-based calibration session for simulation mode.

    +

    This class provides a calibration interface for testing and development when no physical eye tracker is available. It simulates the calibration process using mouse position as a proxy for gaze, allowing experimenters to test calibration procedures and develop experiments without hardware.

    +

    The mouse calibration follows the same interaction pattern as Tobii calibration, collecting position samples at each calibration target and visualizing the results. This ensures consistent user experience between simulation and real data collection modes.

    +
    +

    Methods

    + + + + + + + + + + + + + +
    NameDescription
    runMain function to run the mouse-based calibration routine.
    +
    +

    run

    +
    MouseCalibrationSession.run(calibration_points, num_samples=5)
    +

    Main function to run the mouse-based calibration routine.

    +

    Executes the complete calibration workflow using mouse position as a proxy for gaze data. Follows the same interaction pattern as Tobii calibration to ensure consistency across modes.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    calibration_pointslist of (float, float)List of target positions in PsychoPy coordinates. Typically 5-9 points distributed across the screen.required
    num_samplesintHow many mouse position samples to collect at each calibration point. More samples provide smoother averaging. Default 5.5
    +
    +
    +

    Returns

    + +++++ + + + + + + + + + + + + + + +
    NameTypeDescription
    boolTrue if calibration finished successfully and was accepted by user, False if the user exits early via escape key.
    + + + + +
    +
    +
    +
    + + Back to top
    + + +
    + + + + + + \ No newline at end of file diff --git a/docs/_site/api/index.html b/_site/api/NicePrint.html similarity index 56% rename from docs/_site/api/index.html rename to _site/api/NicePrint.html index a38852a..e066dea 100644 --- a/docs/_site/api/index.html +++ b/_site/api/NicePrint.html @@ -7,7 +7,7 @@ -index – DeToX +niceprint – DeToX @@ -30,6 +64,10 @@ + + + + @@ -67,9 +105,25 @@ } } + + + - - @@ -80,7 +134,7 @@
    DeToX @@ -91,32 +145,22 @@ @@ -162,14 +206,14 @@ + + + +
  • +
    + + Internal Calibration + + + +
    + +
    • +
  • +
    + + Coordinate Conversion + + + +
    + +
    • +
  • +
    + + Utilities + + + +
    +
    • +
  • +
    + + Configuration Settings + + + +
    +
    • @@ -282,111 +466,94 @@
    -
    +

    -
    -

    Function reference

    -
    -

    Main Eye Tracker Class

    -

    The central class of the DeToX package, responsible for connecting to and managing the Tobii eye tracker. This class must be instantiated before any other functionality can be used. It provides access to calibration, recording control, and gaze-contingent presentation methods.

    +
    +

    NicePrint

    +
    NicePrint(body, title='')
    +

    Print a message in a box with an optional title AND return the formatted text.

    +

    Creates a visually appealing text box using Unicode box-drawing characters that displays both in the console and can be used in PsychoPy visual stimuli. This function is particularly useful for presenting instructions, status messages, and calibration information in a consistent, professional format.

    +

    The box automatically adjusts its width to accommodate the longest line of text and centers the title if provided. The formatted output uses Unicode characters for smooth, connected borders that render well in both terminal and graphical environments.

    +
    +

    Parameters

    - - - - ++++++ + + + + + + - -
    ETrackerA high-level controller for running eye-tracking experiments with Tobii Pro and PsychoPy.
    NameTypeDescriptionDefault
    -
    -

    Control the Recording

    -

    Functions for starting, stopping, and managing the capture of eye-tracking data. These methods allow you to initiate and terminate recordings, mark events of interest, and save collected data to disk.

    - + - - - - - - - - - - + + + + - - + + + +
    ETracker.start_recordingBegin gaze data recording session.
    ETracker.stop_recordingStop gaze data recording and finalize session.
    ETracker.record_eventRecord timestamped experimental event during data collection.bodystrThe string to print inside the box. Can contain multiple lines separated by newline characters. Each line will be padded to align within the box.required
    ETracker.save_dataSave buffered gaze and event data to file with optimized processing.titlestrA title to print on the top border of the box. The title will be centered within the top border. If empty string or not provided, the top border will be solid. Default empty string.''
    -
    -

    Calibration

    -

    Methods for running and managing eye tracker calibration. These include displaying calibration status, initiating calibration routines, and saving or loading calibration settings to ensure accurate gaze data.

    +
    +

    Returns

    - - - - - - - - - - - - - - - - +++++ + + + + + - -
    ETracker.show_statusReal-time visualization of participant’s eye position in track box.
    ETracker.calibrateRun the infant-friendly calibration procedure.
    ETracker.save_calibrationSave the current calibration data to a file.
    ETracker.load_calibrationLoads calibration data from a file and applies it to the eye tracker.
    NameTypeDescription
    -
    -
    -

    Gaze Contingent

    -

    Tools for running gaze-contingent experiments, where visual presentation adapts dynamically to a participant’s gaze position. Includes functionality for live gaze-contingent control and methods to compute average gaze positions for experimental logic.

    - + - - - - - - + + +
    ETracker.gaze_contingentInitialize real-time gaze buffer for contingent applications.
    ETracker.get_average_gazeCompute smoothed gaze position from recent samples.strThe formatted text with box characters, ready for display in console or use with PsychoPy TextStim objects. Includes all box-drawing characters and proper spacing.
    -
    + +
    -
    + Back to top
    +
    + diff --git a/_site/api/TobiiCalibrationSession.html b/_site/api/TobiiCalibrationSession.html new file mode 100644 index 0000000..56a777f --- /dev/null +++ b/_site/api/TobiiCalibrationSession.html @@ -0,0 +1,1152 @@ + + + + + + + + + +tobiicalibrationsession – DeToX + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + +
    + +
    + + +
    + + + +

    + + + + +
    +

    TobiiCalibrationSession

    +
    TobiiCalibrationSession(
+    win,
+    calibration_api,
+    infant_stims,
+    shuffle=True,
+    audio=None,
+    anim_type='zoom',
+)
    +

    Tobii-based calibration session for real eye tracking.

    +

    This class implements the calibration protocol for physical Tobii eye trackers, extending the base calibration functionality with hardware-specific data collection and validation. It interfaces directly with the Tobii Pro SDK to collect gaze samples, compute calibration models, and visualize tracking accuracy.

    +

    The Tobii calibration process involves presenting targets at known positions, collecting gaze data while participants look at these targets, and computing a mapping between eye features and screen coordinates. This class provides an infant-friendly implementation with animated stimuli and interactive controls.

    +
    +

    Methods

    + + + + + + + + + + + + + +
    NameDescription
    runMain routine to run the full Tobii calibration workflow.
    +
    +

    run

    +
    TobiiCalibrationSession.run(calibration_points)
    +

    Main routine to run the full Tobii calibration workflow.

    +

    This function presents each calibration target, collects gaze data via the eye tracker, shows the results, and allows the user to retry any subset of points until satisfied.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    calibration_pointslist of (float, float)List of PsychoPy (x, y) positions for calibration targets. Typically 5-9 points distributed across the screen for comprehensive coverage.required
    +
    +
    +

    Returns

    + +++++ + + + + + + + + + + + + + + +
    NameTypeDescription
    boolTrue if calibration was successful and accepted by user, False if aborted via escape key or if calibration computation failed.
    + + + + +
    +
    +
    +
    + + Back to top
    + + +
    + + + + + + \ No newline at end of file diff --git a/_site/api/convert_height_to_units.html b/_site/api/convert_height_to_units.html new file mode 100644 index 0000000..62403e4 --- /dev/null +++ b/_site/api/convert_height_to_units.html @@ -0,0 +1,1119 @@ + + + + + + + + + +convert_height_to_units – DeToX + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + +
    + +
    + + +
    + + + +

    + + + + +
    +

    convert_height_to_units

    +
    convert_height_to_units(win, height_value)
    +

    Convert a size from height units to the current window units.

    +

    Provides unit-agnostic size conversion for consistent visual appearance across different PsychoPy coordinate systems. This function is essential for maintaining proper stimulus sizing when the window units differ from the standard height units used in configuration files.

    +

    The conversion maintains the visual size of objects regardless of the coordinate system in use, ensuring that calibration targets, borders, and other visual elements appear at the intended size on screen.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    winpsychopy.visual.WindowThe PsychoPy window which provides information about units and size. The window’s current unit system determines the conversion method.required
    height_valuefloatSize in height units (fraction of screen height). For example, 0.1 represents 10% of the screen height.required
    +
    +
    +

    Returns

    + +++++ + + + + + + + + + + + + + + +
    NameTypeDescription
    floatSize converted to current window units. The returned value maintains the same visual size on screen as the original height specification.
    +
    +
    +

    Notes

    +

    Height units are PsychoPy’s recommended unit system for maintaining consistent appearance across different screen sizes and aspect ratios. This function enables that consistency when working with other unit systems.

    +

    Supported unit conversions: - height: No conversion needed (identity transform) - norm: Scales by 2.0 to match normalized coordinate range - pix: Multiplies by screen height in pixels - cm/deg: Converts through pixels using monitor calibration

    + + + + +
    +
    + + Back to top
    + + +
    + + + + + + \ No newline at end of file diff --git a/_site/api/get_psychopy_pos.html b/_site/api/get_psychopy_pos.html new file mode 100644 index 0000000..1e587e6 --- /dev/null +++ b/_site/api/get_psychopy_pos.html @@ -0,0 +1,1160 @@ + + + + + + + + + +get_psychopy_pos – DeToX + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + +
    + +
    + + +
    + + + +

    + + + + +
    +

    get_psychopy_pos

    +
    get_psychopy_pos(win, p, units=None)
    +

    Convert Tobii ADCS coordinates to PsychoPy coordinates.

    +

    Transforms eye tracker coordinates from Tobii’s Active Display Coordinate System (ADCS) to PsychoPy’s coordinate system. ADCS uses normalized coordinates where (0,0) is top-left and (1,1) is bottom-right, while PsychoPy typically uses centered coordinates with various unit systems.

    +

    This function is critical for correctly positioning gaze data within PsychoPy stimuli and for accurate visualization of eye tracking results.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    winpsychopy.visual.WindowThe PsychoPy window which provides information about units and size. Window properties determine the target coordinate system.required
    ptuple or array - likeThe Tobii ADCS coordinates to convert. Can be: - Single coordinate: (x, y) tuple - Multiple coordinates: (N, 2) array where N is number of samples Values should be in range [0, 1] where (0, 0) is top-left and (1, 1) is bottom-right.required
    unitsstrThe target units for the PsychoPy coordinates. If None, uses the window’s default units. Supported: ‘norm’, ‘height’, ‘pix’, ‘cm’, ‘deg’, ‘degFlat’, ‘degFlatPos’.None
    +
    +
    +

    Returns

    + +++++ + + + + + + + + + + + + + + +
    NameTypeDescription
    tuple or ndarrayThe converted PsychoPy coordinates in the specified unit system. - Single input: returns (x, y) tuple - Array input: returns (N, 2) array Origin is at screen center for most unit systems.
    +
    +
    +

    Raises

    + +++++ + + + + + + + + + + + + + + +
    NameTypeDescription
    ValueErrorIf the provided units are not supported by PsychoPy.
    +
    +
    +

    Examples

    +
    >>> # Single coordinate
+>>> pos = get_psychopy_pos(win, (0.5, 0.5))  # Returns (0, 0) in most units
    +
    >>> # Multiple coordinates (vectorized)
+>>> coords = np.array([[0.5, 0.5], [0.0, 0.0], [1.0, 1.0]])
+>>> positions = get_psychopy_pos(win, coords)  # Returns (N, 2) array
    + + + + +
    +
    + + Back to top
    + + +
    + + + + + + \ No newline at end of file diff --git a/_site/api/get_psychopy_pos_from_trackbox.html b/_site/api/get_psychopy_pos_from_trackbox.html new file mode 100644 index 0000000..b1622f5 --- /dev/null +++ b/_site/api/get_psychopy_pos_from_trackbox.html @@ -0,0 +1,1150 @@ + + + + + + + + + +get_psychopy_pos_from_trackbox – DeToX + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + +
    + +
    + + +
    + + + +

    + + + + +
    +

    get_psychopy_pos_from_trackbox

    +
    get_psychopy_pos_from_trackbox(win, p, units=None)
    +

    Convert Tobii TBCS coordinates to PsychoPy coordinates.

    +

    Transforms coordinates from Tobii’s Track Box Coordinate System (TBCS) to PsychoPy’s coordinate system. TBCS is used for the user position guide, showing where the participant’s eyes are located within the eye tracker’s track box (the 3D volume where eyes can be tracked).

    +

    In TBCS, coordinates represent position within the track box where (0,0) indicates the participant is positioned at the right edge from the tracker’s perspective, and (1,1) indicates the left edge. This apparent reversal is because TBCS uses the tracker’s perspective, not the user’s.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    winpsychopy.visual.WindowThe PsychoPy window which provides information about units and size. Window properties determine the target coordinate system.required
    ptupleThe Tobii TBCS coordinates to convert as (x, y). Values are in range [0, 1] representing position within the track box from the tracker’s perspective.required
    unitsstrThe target units for the PsychoPy coordinates. If None, uses the window’s default units. Supported: ‘norm’, ‘height’, ‘pix’, ‘cm’, ‘deg’, ‘degFlat’, ‘degFlatPos’.None
    +
    +
    +

    Returns

    + +++++ + + + + + + + + + + + + + + +
    NameTypeDescription
    tupleThe converted PsychoPy coordinates in the specified unit system. Suitable for positioning visual feedback about user position.
    +
    +
    +

    Raises

    + + + + + + + + + + + + + + + +
    NameTypeDescription
    ValueErrorIf the provided units are not supported.
    +
    +
    +

    Notes

    +

    TBCS coordinates are primarily used in the show_status() method to provide visual feedback about participant positioning. The X-axis is reversed compared to ADCS because TBCS uses the tracker’s perspective.

    +

    This function handles the perspective reversal and transforms to PsychoPy’s coordinate conventions for proper visualization.

    + + + + +
    +
    + + Back to top
    + + +
    + + + + + + \ No newline at end of file diff --git a/_site/api/get_tobii_pos.html b/_site/api/get_tobii_pos.html new file mode 100644 index 0000000..81c9daa --- /dev/null +++ b/_site/api/get_tobii_pos.html @@ -0,0 +1,1145 @@ + + + + + + + + + +get_tobii_pos – DeToX + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + +
    + +
    + + +
    + + + +

    + + + + +
    +

    get_tobii_pos

    +
    get_tobii_pos(win, p, units=None)
    +

    Convert PsychoPy coordinates to Tobii ADCS coordinates.

    +

    Transforms coordinates from PsychoPy’s coordinate system to Tobii’s Active Display Coordinate System (ADCS). This conversion is essential for sending calibration target positions to the Tobii eye tracker during calibration procedures.

    +

    ADCS uses normalized coordinates where (0,0) is top-left and (1,1) is bottom-right, regardless of screen size or resolution. This provides a hardware-independent coordinate system for eye tracking data.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    winpsychopy.visual.WindowThe PsychoPy window which provides information about units and size. Window properties determine the source coordinate system.required
    ptupleThe PsychoPy coordinates to convert as (x, y) in specified units.required
    unitsstrThe units of the input PsychoPy coordinates. If None, uses the window’s default units. Supported: ‘norm’, ‘height’, ‘pix’, ‘cm’, ‘deg’, ‘degFlat’, ‘degFlatPos’.None
    +
    +
    +

    Returns

    + +++++ + + + + + + + + + + + + + + +
    NameTypeDescription
    tupleThe converted Tobii ADCS coordinates as (x, y) where both values are in range [0, 1]. (0, 0) is top-left, (1, 1) is bottom-right.
    +
    +
    +

    Raises

    + + + + + + + + + + + + + + + +
    NameTypeDescription
    ValueErrorIf the provided units are not supported.
    +
    +
    +

    Notes

    +

    This function is the inverse of get_psychopy_pos() and is primarily used during calibration to inform the eye tracker where calibration targets are displayed on screen.

    + + + + +
    +
    + + Back to top
    + + +
    + + + + + + \ No newline at end of file diff --git a/_site/api/index.html b/_site/api/index.html new file mode 100644 index 0000000..802939d --- /dev/null +++ b/_site/api/index.html @@ -0,0 +1,1279 @@ + + + + + + + + + +index – DeToX + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + +
    + +
    + + +
    + + + +

    + + + + +
    +

    Reference

    +
    +

    Main Eye-tracker Class

    +

    The central class of the DeToX package, responsible for connecting to and managing the Tobii eye tracker. This class must be instantiated before any other functionality can be used. It provides access to calibration, recording control, and gaze-contingent presentation methods. Below are the main methods and properties of this class:

    + + + + + + + +
    ETrackerA high-level controller for running eye-tracking experiments with Tobii Pro and PsychoPy.
    +
    +

    Control the Recording

    +

    Functions for starting, stopping, and managing the capture of eye-tracking data. These methods allow you to initiate and terminate recordings, mark events of interest, and save collected data to disk.

    + + + + + + + + + + + + + + + + + + + +
    ETracker.start_recordingBegin gaze data recording session.
    ETracker.stop_recordingStop gaze data recording and finalize session.
    ETracker.record_eventRecord timestamped experimental event during data collection.
    ETracker.save_dataSave buffered gaze and event data to file with optimized processing.
    +
    +
    +

    Calibration

    +

    Methods for running and managing eye tracker calibration. These include displaying calibration status, initiating calibration routines, and saving or loading calibration settings to ensure accurate gaze data.

    + + + + + + + + + + + + + + + + + + + +
    ETracker.show_statusReal-time visualization of participant’s eye position in track box.
    ETracker.calibrateRun the infant-friendly calibration procedure.
    ETracker.save_calibrationSave the current calibration data to a file.
    ETracker.load_calibrationLoads calibration data from a file and applies it to the eye tracker.
    +
    +
    +

    Gaze Contingent

    +

    Tools for running gaze-contingent experiments, where visual presentation adapts dynamically to a participants gaze position. Includes functionality for live gaze-contingent control and methods to compute average gaze positions for experimental logic.

    + + + + + + + + + + + +
    ETracker.gaze_contingentInitialize real-time gaze buffer for contingent applications.
    ETracker.get_gaze_positionGet current gaze position from rolling buffer.
    +
    +
    +
    +

    Internal Calibration

    +

    Classes for running eye-tracker calibration. These get called internally by the ETracker class, and are reported here only for completeness. They are comprise of a base calibration class that set the common interface, and the specific implementations for Tobii and Mouse calibration.

    + + + + + + + + + + + + + + + +
    BaseCalibrationSessionBase class with common functionality for both calibration types.
    TobiiCalibrationSessionTobii-based calibration session for real eye tracking.
    MouseCalibrationSessionMouse-based calibration session for simulation mode.
    +
    +
    +

    Coordinate Conversion

    +

    A collection of utility functions designed to help the conversion of the data from different formats. These are called internally by the ETracker class, but can be used independently if needed.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    convert_height_to_unitsConvert a size from height units to the current window units.
    get_psychopy_posConvert Tobii ADCS coordinates to PsychoPy coordinates.
    psychopy_to_pixelsConvert PsychoPy coordinates to pixel coordinates.
    get_tobii_posConvert PsychoPy coordinates to Tobii ADCS coordinates.
    pix2tobiiConvert PsychoPy pixel coordinates to Tobii ADCS coordinates.
    tobii2pixConvert Tobii ADCS coordinates to PsychoPy pixel coordinates.
    get_psychopy_pos_from_trackboxConvert Tobii TBCS coordinates to PsychoPy coordinates.
    +
    +
    +

    Utilities

    +

    A set of utility classes and functions for presenting stimuli and formatted text. These are called internally by the ETracker class.

    + + + + + + + + + + + +
    NicePrintPrint a message in a box with an optional title AND return the formatted text.
    InfantStimuliStimuli manager for infant-friendly calibration procedures.
    +
    +
    +

    Configuration Settings

    +

    Configuration classes and module-level instances for customizing the behavior and appearance of the DeToX eye-tracking system. These settings control animation parameters, colors, UI element sizes, and data formats. Note: These settings should generally not be changed unless you have specific requirements. However, they can be modified through the module-level instances (e.g., ETSettings.animation) for easy configuration of your experiments.

    + + + + + + + + + + + + + + + + + + + +
    ETSettings.AnimationSettingsAnimation parameters for calibration stimuli.
    ETSettings.CalibrationColorsColor settings for calibration visual elements.
    ETSettings.UIElementSizesSize settings for user interface elements.
    ETSettings.FontSizeMultipliersFont size multipliers for different text types.
    + + + + +
    +
    + + Back to top
    + + +
    + + + + + + \ No newline at end of file diff --git a/_site/api/pix2tobii.html b/_site/api/pix2tobii.html new file mode 100644 index 0000000..bf49b36 --- /dev/null +++ b/_site/api/pix2tobii.html @@ -0,0 +1,1112 @@ + + + + + + + + + +pix2tobii – DeToX + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + +
    + +
    + + +
    + + + +

    + + + + +
    +

    pix2tobii

    +
    pix2tobii(win, p)
    +

    Convert PsychoPy pixel coordinates to Tobii ADCS coordinates.

    +

    Low-level conversion function that transforms pixel coordinates with a centered origin (PsychoPy convention) to Tobii’s normalized ADCS coordinates with top-left origin. This is a fundamental building block for other coordinate conversion functions.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    winpsychopy.visual.WindowThe PsychoPy window which provides screen dimensions for normalization.required
    ptupleThe PsychoPy pixel coordinates to convert as (x, y). Origin is at screen center, x increases rightward, y increases upward.required
    +
    +
    +

    Returns

    + +++++ + + + + + + + + + + + + + + +
    NameTypeDescription
    tupleThe converted Tobii ADCS coordinates as (x, y) in range [0, 1]. Origin is top-left, x increases rightward, y increases downward.
    +
    +
    +

    Notes

    +

    The conversion involves: 1. Translating the origin from center to top-left (+0.5 offset) 2. Normalizing by screen dimensions to get [0, 1] range 3. Inverting the Y-axis to match Tobii’s top-down convention

    +

    This function assumes PsychoPy’s pixel coordinate convention where (0, 0) is at screen center.

    + + + + +
    +
    + + Back to top
    + + +
    + + + + + + \ No newline at end of file diff --git a/_site/api/psychopy_to_pixels.html b/_site/api/psychopy_to_pixels.html new file mode 100644 index 0000000..130ac1e --- /dev/null +++ b/_site/api/psychopy_to_pixels.html @@ -0,0 +1,1115 @@ + + + + + + + + + +psychopy_to_pixels – DeToX + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + +
    + +
    + + +
    + + + +

    + + + + +
    +

    psychopy_to_pixels

    +
    psychopy_to_pixels(win, pos)
    +

    Convert PsychoPy coordinates to pixel coordinates.

    +

    Transforms coordinates from any PsychoPy coordinate system to pixel coordinates suitable for image drawing operations. This function is essential for creating calibration result visualizations and other pixel-based graphics.

    +

    The conversion accounts for PsychoPy’s centered coordinate system and transforms to a top-left origin system used by image libraries like PIL.

    +
    +

    Parameters

    + ++++++ + + + + + + + + + + + + + + + + + + + + + + +
    NameTypeDescriptionDefault
    winpsychopy.visual.WindowThe PsychoPy window which provides information about units and size. Window units and dimensions determine the conversion method.required
    postupleThe PsychoPy coordinates to convert as (x, y) in current window units.required
    +
    +
    +

    Returns

    + +++++ + + + + + + + + + + + + + + +
    NameTypeDescription
    tupleThe converted pixel coordinates as (int, int) with origin at top-left. Values are rounded to nearest integer for pixel alignment.
    +
    +
    +

    Notes

    +

    This function handles the main PsychoPy coordinate systems: - ‘height’: Screen height = 1, width adjusted by aspect ratio, centered origin - ‘norm’: Screen ranges from -1 to 1 in both dimensions, centered origin - Other units: Assumes coordinates are already close to pixel values

    +

    The output uses standard image coordinates where (0,0) is top-left and y increases downward, suitable for PIL and similar libraries.

    + + + + +
    +
    + + Back to top
    + + +
    + + + + + + \ No newline at end of file diff --git a/docs/_site/api/ETracker.get_average_gaze.html b/_site/api/tobii2pix.html similarity index 55% rename from docs/_site/api/ETracker.get_average_gaze.html rename to _site/api/tobii2pix.html index ef9c181..889daef 100644 --- a/docs/_site/api/ETracker.get_average_gaze.html +++ b/_site/api/tobii2pix.html @@ -7,7 +7,7 @@ -etracker.get_average_gaze – DeToX +tobii2pix – DeToX @@ -32,6 +65,8 @@ + + @@ -69,9 +104,25 @@ } } + + + - - @@ -82,7 +133,7 @@
    DeToX @@ -93,32 +144,22 @@ +
    diff --git a/docs/api/BaseCalibrationSession.html b/docs/api/BaseCalibrationSession.html index 4ee6999..40ab541 100644 --- a/docs/api/BaseCalibrationSession.html +++ b/docs/api/BaseCalibrationSession.html @@ -122,6 +122,18 @@ }); + @@ -158,6 +170,10 @@
  • Getting Started +
    • +
  • + + Calibration
    • @@ -197,6 +213,9 @@
    +
    @@ -228,7 +247,7 @@
  • + Calibration @@ -236,41 +255,6 @@ -
    • -
  • -
    - - -
    -
      -
    • -
      ETracker.show_status
      @@ -297,13 +281,13 @@
    • - -
      -
        +
        • @@ -322,13 +306,13 @@
        • - + Internal Calibration - +
          -
    • +| Name | Type | Description | Default | +|--------|--------|-------------------------------------------------------------------|--------------| +| body | str | The main message text to display. | _required_ | +| title | str | Title for the message box. Default empty string. | `''` | +| pos | tuple | Position of the message box center on screen. Default (0, -0.15). | `(0, -0.15)` |
    diff --git a/docs/api/ETSettings.AnimationSettings.html b/docs/api/ETSettings.AnimationSettings.html index ca63be8..7d25691 100644 --- a/docs/api/ETSettings.AnimationSettings.html +++ b/docs/api/ETSettings.AnimationSettings.html @@ -64,7 +64,7 @@ - + @@ -122,6 +122,18 @@ }); + @@ -158,6 +170,10 @@
  • Getting Started +
    • +
  • + + Calibration
    • @@ -197,6 +213,9 @@
    +
    @@ -228,7 +247,7 @@
  • + Calibration @@ -236,41 +255,6 @@ -
    • -
  • -
    - - -
    -
    • +
    @@ -228,7 +247,7 @@
  • + Calibration @@ -236,41 +255,6 @@ -
    • -
  • -
    - - -
    -
      -
    • -
      ETracker.show_status
      @@ -297,13 +281,13 @@
    • - -
      -
        +
        • @@ -322,13 +306,13 @@
        • - + Internal Calibration - +
          -
    • +
    @@ -228,7 +246,7 @@
  • + Calibration @@ -236,41 +254,6 @@ -
    • -
  • -
    - - -
    -

    • Size settings for user interface elements.

    Defines sizes for various UI components in the calibration interface. All sizes are specified in height units (as fraction of screen height) and are automatically converted to appropriate units based on the PsychoPy window configuration.

    @@ -518,7 +506,7 @@

    highlight float -Radius of circles highlighting selected calibration points for retry. Default is 0.04 (4% of screen height). +Radius of circles highlighting selected calibration points for retry. Default is 0.02 (2% of screen height). line_width @@ -543,7 +531,7 @@

    text float -Base text height for all text displays in the calibration interface. Default is 0.025 (2.5% of screen height). +Base text height (deprecated - use specific text sizes below). Default is 0.025 (2.5% of screen height). target_circle @@ -553,7 +541,32 @@

    target_circle_width float -Line width for target circle outlines in result visualizations. Default is 0.006 (0.6% of screen height). +Line width for target circle outlines in result visualizations. Default is 0.003 (0.3% of screen height). + + +sample_marker +float +Radius of sample markers in circle visualization style. Default is 0.005 (0.5% of screen height). + + +instruction_text +float +Text height for instruction displays during calibration. Default is 0.019 (1.9% of screen height). + + +message_text +float +Text height for general message displays. Default is 0.016 (1.6% of screen height). + + +title_text +float +Text height for title text in message boxes. Default is 0.018 (1.8% of screen height). + + +legend_text +float +Text height for legend labels showing eye color coding. Default is 0.015 (1.5% of screen height). @@ -566,7 +579,7 @@

    Notes<

    Examples

    >>> ui_sizes = UIElementSizes()
 >>> ui_sizes.highlight = 0.06  # Larger highlight circles
->>> ui_sizes.text = 0.035  # Larger text
    +>>> ui_sizes.instruction_text = 0.025 # Larger instructions
    @@ -1053,59 +1066,66 @@

    - - ETSettings.FontSizeMultipliers -