> For the complete documentation index, see [llms.txt](https://vinayin.gitbook.io/pyeta/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vinayin.gitbook.io/pyeta/description/methodology.md).

# Methodology

The `pyETA` tool is built to handle eye-tracking data with a real-time focus. The idea is all about grabbing raw gaze data, processing it with a velocity-based approach (I-VT), and producing fixation start timestamps & duration to assist the researcher. 

The toolbox leans on `tobii_research` for communicating with the eye-tracker device, `PyQt6` for the GUI, `click`  for CLI and `pylsl` / `mne_lsl` for  LSL streaming. 

### **Core Components**

* **Data Collection**: Hooks into a Tobii eye tracker or mocks it if you’re testing.
* **Processing**: Uses velocity thresholds to tag fixations, smoothed out with `OneEuroFilter`.
* **Validation**: Cross-checks gaze against known targets of 3x3 grid for accuracy/precision.
* **Visualization**: Real-time gaze plot & fixation tracking plot.

### **Workflow**

`application.py` orchestrates two main use cases in the GUI with `reader.TrackerThread` and `reader.StreamThread` for tracking and validation process

`track.py`  in CLI is does the tracking and `window.py`  does the validation process.

{% tabs %}
{% tab title="Tracking" %}
`StreamThread`thread runs in the background and gets data from an LSL stream on-demand, the LSL streams is being send continuously by `TrackerThread`  and being stored in buffer of max length 10000 for gaze and 10 for fixation.

{% hint style="info" %}
Tracking uses **TrackerThread + StreamThread** threads to plot the graphs
{% endhint %}
{% endtab %}

{% tab title="Validation" %}
This process starts a new window, the `validate_eye_tracker()`  pops a dialog to pick a screen, then launches a validation window of 3x3 grid with a blue dot moving and being fixated at targets randomly.

Here, `TrackerThread` runs along with when the validation window launches with an intention to stop when all targets are traversed, collecting gaze data while the validation grid runs. The thread is also set to save the data to a file which are later used for calculating metrics.

{% hint style="info" %}
validation uses **ValidationWindow + TrackerThread** to capture the data and saves them to files
{% endhint %}
{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://vinayin.gitbook.io/pyeta/description/methodology.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.