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)
```