From c4552e04e1271a9210a934233beae5be1943d034 Mon Sep 17 00:00:00 2001
From: Théo de la Hogue
Date: Wed, 7 Jun 2023 14:34:14 +0200
Subject: Writing User guide and use cases section.

---
 docs/user_guide/gaze_analysis/gaze_position.md | 68 ++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 docs/user_guide/gaze_analysis/gaze_position.md

(limited to 'docs/user_guide/gaze_analysis/gaze_position.md')

diff --git a/docs/user_guide/gaze_analysis/gaze_position.md b/docs/user_guide/gaze_analysis/gaze_position.md
new file mode 100644
index 0000000..67f15f8
--- /dev/null
+++ b/docs/user_guide/gaze_analysis/gaze_position.md
@@ -0,0 +1,68 @@
+Gaze position
+=============
+
+[GazeFeatures](/argaze/#argaze.GazeFeatures) defines a [GazePosition](/argaze/#argaze.GazeFeatures.GazePosition) class to handle point coordinates with a precision value.
+
+``` python
+from argaze import GazeFeatures
+
+# Define a basic gaze position
+gaze_position = GazeFeatures.GazePosition((123, 456))
+
+# Define a gaze position with a precision value
+gaze_position = GazeFeatures.GazePosition((789, 765), precision=10)
+
+# Access to gaze position value and precision
+print(f'position: {gaze_position.value}')
+print(f'precision: {gaze_position.precision}')
+
+```
+
+## Validity
+
+[GazeFeatures](/argaze/#argaze.GazeFeatures) defines also a [UnvalidGazePosition](/argaze/#argaze.GazeFeatures.UnvalidGazePosition) class that inherits from [GazePosition](/argaze/#argaze.GazeFeatures.GazePosition) to handle case where no gaze position exists because of any specific device reason.
+
+``` python
+from argaze import GazeFeatures
+
+# Define a basic unvalid gaze position
+gaze_position = GazeFeatures.UnvalidGazePosition()
+
+# Define a basic unvalid gaze position with a message value
+gaze_position = GazeFeatures.UnvalidGazePosition("Something bad happened")
+
+# Access to gaze position validity
+print(f'validity: {gaze_position.valid}')
+
+```
+
+## Distance
+
+[GazePosition](/argaze/#argaze.GazeFeatures.GazePosition) class provides a **distance** method to calculate the distance to another gaze position instance.
+
+![Distance](../../img/distance.png)
+
+``` python
+# Distance between A and B positions
+d = gaze_position_A.distance(gaze_position_B)
+``` 
+
+## Overlapping
+
+[GazePosition](/argaze/#argaze.GazeFeatures.GazePosition) class provides an **overlap** method to test if a gaze position overlaps another one considering their precisions.
+
+![Gaze overlapping](../../img/overlapping.png)
+
+``` python
+# Check that A overlaps B
+if gaze_position_A.overlap(gaze_position_B): 
+
+        # Do something if A overlaps B
+        ...
+
+# Check that A overlaps B and B overlaps A
+if gaze_position_A.overlap(gaze_position_B, both=True): 
+
+        # Do something if A overlaps B AND B overlaps A
+        ...
+```
-- 
cgit v1.1