From f93d3e2b011fe1c1de93d0094ca45584ddd49936 Mon Sep 17 00:00:00 2001
From: Théo de la Hogue
Date: Mon, 28 Aug 2023 15:05:01 +0200
Subject: Improving gaze analysis pipeline documentation.

---
 .../heatmap_visualisation.md                       | 71 ++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 docs/user_guide/gaze_analysis_pipeline/heatmap_visualisation.md

(limited to 'docs/user_guide/gaze_analysis_pipeline/heatmap_visualisation.md')

diff --git a/docs/user_guide/gaze_analysis_pipeline/heatmap_visualisation.md b/docs/user_guide/gaze_analysis_pipeline/heatmap_visualisation.md
new file mode 100644
index 0000000..24a8f32
--- /dev/null
+++ b/docs/user_guide/gaze_analysis_pipeline/heatmap_visualisation.md
@@ -0,0 +1,71 @@
+Visualize heatmap
+=================
+
+Heatmap is an optional [ArFrame](../../../argaze/#argaze.ArFeatures.ArFrame) pipeline step. It is executed at each new gaze position to update heatmap image.
+
+![Heatmap](../../img/ar_frame_heatmap.png)
+
+## Enable ArFrame heatmap
+
+[ArFrame](../../../argaze/#argaze.ArFeatures.ArFrame) heatmap visualization can be enabled thanks to a dedicated JSON entry.
+
+Here is the JSON ArFrame configuration file example where heatmap visualization is enabled:
+
+```json
+{
+    "name": "My FullHD screen",
+    "size": [1920, 1080],
+    ...
+    "heatmap": {
+        "size": [320, 180],
+        "sigma": 0.025,
+        "buffer": 0
+    }
+}
+```
+
+Then, here is how to access to heatmap object:
+
+```python
+
+# Assuming an ArFrame is loaded
+...
+
+print("heatmap:", ar_frame.heatmap)
+```
+
+Finally, here is what the program writes in console:
+
+```txt
+heatmap: Heatmap(size=[320, 180], buffer=0, sigma=0.025)
+```
+
+Now, let's understand the meaning of each JSON entry.
+
+### Size
+
+The heatmap image size in pixel. Higher size implies higher CPU load.
+
+### Sigma
+
+The gaussian point spreading to draw at each gaze position.
+
+![Point spread](../../img/point_spread.png)
+
+### Buffer 
+
+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/#argaze.ArFeatures.ArFrame.look) method, it is possible to write heatmap image thanks to OpenCV package.
+
+```python
+import cv2
+
+# Assuming that timestamped gaze positions have been processed by ArFrame.look method
+...
+
+# Export heatmap image
+cv2.imwrite('./heatmap.png', ar_frame.heatmap.image)
+```
\ No newline at end of file
-- 
cgit v1.1