Reorganizing gaze analizis pipeline documentation.

1 files changed, 71 insertions, 0 deletions

diff --git a/docs/user_guide/gaze_analysis_pipeline/heatmap.md b/docs/user_guide/gaze_analysis_pipeline/heatmap.md
new file mode 100644
index 0000000..35674a1
--- /dev/null
+++ b/docs/user_guide/gaze_analysis_pipeline/heatmap.md
@@ -0,0 +1,71 @@
+Add Heatmap
+===========
+
+Heatmap is an optional [ArFrame](../../argaze.md/#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.md/#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.md/#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