From 31df32870f06460be8069c171cb032f5aa74a098 Mon Sep 17 00:00:00 2001
From: Théo de la Hogue
Date: Wed, 30 Aug 2023 23:15:59 +0200
Subject: More documention about gaze analysis pipeline.

---
 .../gaze_analysis_pipeline/background.md           | 56 ++++++++++++++++++++++
 docs/user_guide/gaze_analysis_pipeline/heatmap.md  | 24 ++++------
 .../gaze_analysis_pipeline/visualisation.md        | 11 ++++-
 3 files changed, 75 insertions(+), 16 deletions(-)
 create mode 100644 docs/user_guide/gaze_analysis_pipeline/background.md

(limited to 'docs/user_guide')

diff --git a/docs/user_guide/gaze_analysis_pipeline/background.md b/docs/user_guide/gaze_analysis_pipeline/background.md
new file mode 100644
index 0000000..420dbdf
--- /dev/null
+++ b/docs/user_guide/gaze_analysis_pipeline/background.md
@@ -0,0 +1,56 @@
+Add Background
+==============
+
+Background is an optional [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) attribute to display any image.
+
+![Background](../../img/ar_frame_background.png)
+
+## Load and display ArFrame background
+
+[ArFrame.background](../../argaze.md/#argaze.ArFeatures.ArFrame.background) can be enabled thanks to a dedicated JSON entry.
+
+Here is the JSON ArFrame configuration file example where a background picture is loaded and displayed:
+
+```json
+{
+    "name": "My FullHD screen",
+    "size": [1920, 1080],
+    ...
+    "background": "./joconde.png",
+    ...
+    "image_parameters": {
+        ...
+        "background_weight": 1
+    }
+}
+```
+
+Now, let's understand the meaning of each JSON entry.
+
+### Background
+
+The path to an image file on disk.
+
+### Background weight
+
+The weight of background overlay in [ArFrame.image](../../argaze.md/#argaze.ArFeatures.ArFrame.image) between 0 and 1.
+
+## Edit ArFrame background
+
+It is also possible to set background image and display it from script:
+
+```python
+import numpy
+
+# Assuming an ArFrame is loaded
+...
+
+# Set ArFrame background as gray
+ar_frame.background = numpy.full((ar_frame.size[1], ar_frame.size[0], 3), 127).astype(numpy.uint8)
+
+# Get ArFrame image with background and any other options
+ar_frame_image = ar_frame.image(background_weight = 1, ...)
+
+# Do something with ArFrame image
+...
+```
diff --git a/docs/user_guide/gaze_analysis_pipeline/heatmap.md b/docs/user_guide/gaze_analysis_pipeline/heatmap.md
index 35674a1..a741810 100644
--- a/docs/user_guide/gaze_analysis_pipeline/heatmap.md
+++ b/docs/user_guide/gaze_analysis_pipeline/heatmap.md
@@ -5,11 +5,11 @@ Heatmap is an optional [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) pip
 
 ![Heatmap](../../img/ar_frame_heatmap.png)
 
-## Enable ArFrame heatmap
+## Enable and display ArFrame heatmap
 
-[ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) heatmap visualization can be enabled thanks to a dedicated JSON entry.
+[ArFrame.heatmap](../../argaze.md/#argaze.ArFeatures.ArFrame.heatmap) can be enabled thanks to a dedicated JSON entry.
 
-Here is the JSON ArFrame configuration file example where heatmap visualization is enabled:
+Here is the JSON ArFrame configuration file example where heatmap is enabled and displayed:
 
 ```json
 {
@@ -20,6 +20,11 @@ Here is the JSON ArFrame configuration file example where heatmap visualization
         "size": [320, 180],
         "sigma": 0.025,
         "buffer": 0
+    },
+    ...
+    "image_parameters": {
+        ...
+        "heatmap_weight": 1
     }
 }
 ```
@@ -56,16 +61,7 @@ The gaussian point spreading to draw at each gaze position.
 
 The size of point spread images buffer (0 means no buffering) to visualize only last N gaze positions.
 
-## Export heatmap to PNG file
-
-Once timestamped gaze positions have been processed by [ArFrame.look](../../argaze.md/#argaze.ArFeatures.ArFrame.look) method, it is possible to write heatmap image thanks to OpenCV package.
+### Heatmap weight
 
-```python
-import cv2
-
-# Assuming that timestamped gaze positions have been processed by ArFrame.look method
-...
+The weight of heatmap overlay in [ArFrame.image](../../argaze.md/#argaze.ArFeatures.ArFrame.image) between 0 and 1.
 
-# Export heatmap image
-cv2.imwrite('./heatmap.png', ar_frame.heatmap.image)
-```
\ No newline at end of file
diff --git a/docs/user_guide/gaze_analysis_pipeline/visualisation.md b/docs/user_guide/gaze_analysis_pipeline/visualisation.md
index 5eae7f5..ad59d54 100644
--- a/docs/user_guide/gaze_analysis_pipeline/visualisation.md
+++ b/docs/user_guide/gaze_analysis_pipeline/visualisation.md
@@ -1,7 +1,7 @@
 Visualize ArFrame and ArLayers
 ==============================
 
-All [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) and [ArLayers](../../argaze.md/#argaze.ArFeatures.ArFrame) pipeline steps can be drawn in real time or afterward.
+All [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) and [ArLayers](../../argaze.md/#argaze.ArFeatures.ArFrame) pipeline steps result can be drawn in real time or afterward.
 
 ![ArFrame visualisation](../../img/ar_frame_visualisation.png)
 
@@ -76,6 +76,9 @@ if __name__ == '__main__':
 [ArFrame.image](../../argaze.md/#argaze.ArFeatures.ArFrame.image) method parameters can be configured thanks to dictionary.
 
 ```python
+# Assuming ArFrame is loaded
+...
+
 # Edit ArFrame image parameters
 image_parameters = {
     "draw_scan_path": {
@@ -187,4 +190,8 @@ Here is the JSON ArFrame configuration file example with image parameters includ
         }
     }
 }
-```
\ No newline at end of file
+```
+
+!!! warning
+	Most of *image_parameters* entries work if related ArFrame/ArLayer pipeline steps are enabled.  
+	For example, JSON *draw_scan_path* entry needs GazeMovementIdentifier and ScanPath steps to be enabled.
\ No newline at end of file
-- 
cgit v1.1