# Generate static and dynamic scanpaths with Reference Image Mapper
The Reference Image Mapper is a powerful tool that maps gaze onto 2D images of real-world environments and generates heatmaps. Now, we offer a new way to visualize your Reference Image Mapper data. We have created a ready-to-use script that generates static and dynamic scanpaths, providing deeper insights into patterns of visual behavior.
Before continuing, ensure you are familiar with the Reference Image Mapper enrichment. Check out this explainer video for reference.
# What is a scanpath?
A scanpath is a graphical representation of an individual's gaze movements. It shows the sequence of fixations, or pauses in gaze, and the rapid eye movements made between fixations, known as saccades. The scanpath offers a glimpse into what the observer is focusing on and the duration and frequency of their attention to different aspects of the scene. This information is a valuable tool for understanding a person's visual attention and perception.

# What you'll need:
- A Reference Image Mapper export download
- Python 3.7 or higher
- This ready-to-go script
# Running the code
All you need to do is run the command python3 RIM_scanpath.py
in your terminal. A prompt will then appear asking for
the location of the Reference Image Mapper export folder. After this, just sit back and wait for the processing to finish.
Upon completion, the resulting scanpath visualisations will be saved in a newly created sub-folder called "scanpath”.
If you wish to enhance the appearance of your scanpaths, keep reading for additional instructions!
# Personalization
# To each their own color
This function generates random colors for each participant based on their names.
def color_generator(...):
colors = {
subj: (
random.randint(0, 255),
random.randint(0, 255),
random.randint(0, 255),
)
for subj in names
}
return colors
However, if you prefer to assign specific colors to each participant, you can easily modify the function to suit your needs. An example could be:
def color_generator():
colors = {}
colors['Subject1'] = (0, 0, 255)
colors['Subject2'] = (255, 0, 0)
colors['Subject3'] = (0, 255, 0)
return colors
# Make it font-tastic
If you have a preferred font or would like to change the size, simply edit the draw_on_frame() function. The fixation
IDs are displayed in black text with a white border to make them stand out from the background. If you adjust the font
size, it's also recommended to increase the values of font_thick_w
and font_thick_b
to maintain visual contrast.
def draw_on_frame(...):
# text aesthetics
font = cv2.FONT_HERSHEY_DUPLEX
font_size = 1
font_thick_w = 3
font_thick_b = 1
...
# My name is legend
The script includes two functions for creating a legend to display the wearer names and corresponding colors:
draw_name_legend()
: This function creates a legend box that displays only the name of the wearer on their individual scanpath video and image.draw_all_names_legend()
: This function creates a legend that displays all the wearer names on the final general scanpath image.
To customize the appearance of the legend, such as the position, dimensions, or colors of the rectangular white box or the colored line, you can modify the following parameters in both functions:
r_end_point
- x and y values of the ending coordinates of the rectangular legend boxr_start_point
- x and y values of the starting coordinates of the rectangular legend boxl_end_point
- x and y values of the ending coordinates of the colored linel_start_point
- x and y values of the starting coordinates of the colored line- In
cv2.rectangle
, editcolor
to set a new color for the legend box - In
cv2.line
, editthickness
to set a new width for the colored line