**ArGaze** is a python toolkit to deal with gaze tracking in **Augmented Reality (AR) environment**.

The ArGaze toolkit provides solutions to build 3D modeled AR environment defining **Areas Of Interest (AOI)** mapped on **ArUco markers** and so ease experimentation design with wearable eye tracker device.

Further, tracked gaze can be projected onto AR environment for live or post **gaze analysis** thanks to **timestamped data** features. 

# Architecture

ArGaze is divided in submodules dedicated to various specifics features:

* `argaze.ArUcoMarkers`: ArUco markers generator, detector, camera calibration, scene description, ...
* `argaze.AreaOfInterest`: Area Of Interest (AOI) scene management for 2D and 3D environment.
* `argaze.ArFeatures`: Load and manage AR environement assets.
* `argaze.GazeFeatures`: Generic gaze data and class definitions.
* `argaze.GazeAnalysis`: Various gaze analysis algorithms.
* `argaze.DataStructures`: Timestamped data features.
* `argaze.utils`: Collection of command-line high level features scripts.

# Installation

Consider that all inline commands below have to be executed into ArGaze root folder.

- Install build tool package: 

```
pip install build
```

- Then, build ArGaze package: 

```
python -m build
```

- Then, install ArGaze package (replace VERSION by what has been built into dist folder):

```
pip install ./dist/argaze-VERSION.whl
```

.. note:: As Argaze library developper
   *You should prefer to install the package in developer mode to test live code changes:*

   ```
   pip install -e .
   ```

# Documentation

## Wiki

The [wiki](https://git.recherche.enac.fr/projects/argaze/wiki) provides many explanations about how works ArGaze, what is possible to do and code samples.

## Cookbook

The `argaze.utils` submodule is a good place to get ready made code examples.

## Code

ArGaze code documentation is based on [pdoc](https://pdoc.dev/).
To generate html documentation: 

- Install 'pdoc' package:

```
pip install pdoc
```

- Then, build documentation into doc folder:

```
pdoc -o ./doc ./src/argaze/ 
```

.. note:: As Argaze library developper
   *You should prefer to create a local html server to watch live documentation changes:*

   ```
   pdoc ./src/argaze/
   ```

# Test

ArGaze package unitary tests are based on [unittest](https://docs.python.org/fr/3.10/library/unittest.html) module.  
Test files tree structure is mirroring the file tree structure of src/argaze folder.

To run all unitary tests:

```
python -m unittest discover ./src/argaze.test "*.py"
```

To run only submodule unitary tests:

```
python -m unittest discover ./src/argaze.test/SUBMODULE "*.py"
```

To run only a single unitary test file from a submodule:

```
python -m unittest discover ./src/argaze.test/SUBMODULE/ TEST_FILE.py
```

.. note:: Verbose mode
   *Use -v option to get more details.*