Skip to content

Generate Scanpath Visualisations


Picture this: Build and customize scanpath visualizations with your Reference Image Mapper exports!

Visualizing Gaze Exploration With Scanpaths

Scanpaths are graphical representations of gaze over time. They provide a glimpse into how the observer has focused their attention on different aspects of a scene, making them a valuable tool for understanding a person's visual attention and perception. The video above illustrates this concept. It shows:

  • Fixation locations, visualized as blue numbered circles
  • Fixation durations, which are mapped to the size of the circles. Longer fixations correspond to larger circles
  • Saccades, represented by blue lines connecting the fixations
  • Saccade amplitudes, reflected by the length of the lines. Longer lines correspond to larger saccade amplitudes, indicating larger shifts in gaze

In this guide, we will show you how to generate both static and dynamic scanpath visualisations using your Reference Image Mapper exported data.


Before continuing, ensure you are familiar with the Reference Image Mapper enrichment. Check out this explainer video for reference.

Extending Current Tools

The Reference Image Mapper enrichment available in Pupil Cloud is a tool that maps gaze onto 2D images and can subsequently generate heatmaps. However, it currently does not support the production of scanpath visualizations. Thus, we chose to develop a script that shows you how to build your own scanpaths using Reference Image Mapped data.


  1. Run a Reference Image Mapper enrichment and download the results
  2. Download this script and follow the installation instructions

Review the Scanpaths

After the script has completed its execution, you'll find the resulting scanpath visualizations stored in a newly created sub-folder named "scanpath." For each participant, you will obtain a reference image with the scanpath superimposed on it. You will also find a video featuring a dynamic scanpath overlay. Finally, if you had multiple participants, an aggregated visualization combining all participants' scanpaths will be available, enabling a more comprehensive overview of the subjects' gaze behavior.

Jack Scanpath

General Scanpath


If you need assistance in using this application, reach out to us via email at, on our Discord server, or visit our Support Page for dedicated support options.