aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: 749c6cfd0899df8fa9b5617c62243c5ef0aaa96e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
**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 **<a href="https://docs.opencv.org/4.x/d5/dae/tutorial_aruco_detection.html" target="_blank">OpenCV ArUco markers</a>** 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. 

ArGaze can be combined with any wearable eye tracking device python library like Tobii or Pupil glasses.

# 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.*