+ 
+
+
+
+ 
+
+
+
+ 
+
+
+ 
| 
|
-| ------------------------------------------------------ | -------------------------------------------- |
-| 
| 
|
-| 
| |
+- Multiple reference images of the environment
+- Single or multiple scanning recordings. The choice of whether to use single or multiple scanning recordings depends on the dimensions of the space to be explored. Further details on this in ‘Steps’
+- An eye tracking recording taken as the participant(s) move freely within the environment, combined with custom user-inputted [events](/neon/basic-concepts/events) to segment the recording into [sections](/enrichments/#enrichment-sections) based on the specific areas the person was looking at
-## Scanning recordings
+## Steps
+1. **Capture Reference Images:** Take pictures of the areas or objects within the environment you wish to investigate. Here are some example pictures of different areas and pieces of furniture in the living room:
-In this guide, we want to map gaze onto different parts of a living room, for this reason, we recorded **two** scanning videos. We chose to use more than one scanning recording because the environment is a bit too big to be effectively scanned just by a single one.
+
+
+
+ 
+ 
+ 
+ | 
|
-| ------------------------------------------------------ | --------------------------------------------------------- |
-| | 
|
-| | 
|
-| | 
|
-| | 
|
+Once the enrichments are completed, heatmaps are automatically generated illustrating the areas which attracted more gaze. Additionally, you'll have the option to download gaze and fixation data mapped within the bounds of the pictures, enabling you to conduct further in-depth analyses.
-That's it. We look forward to seeing your own mapped environments!
+
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+ 
-
-## What you'll need:
-- A Reference Image Mapper export download
-- Python 3.7 or higher
-- [This](https://gist.github.com/elepl94/9f669c4d81e455cf2095957831219664) 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. - -```python -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: +## Unlocking visual exploration with scanpaths +A scanpath is a graphical representation of an individual's gaze. It shows the sequence of fixations (pauses in gaze), and rapid eye movements made between fixations (saccades). Scanpaths offer a glimpse into how the observer has focused their attention on different aspects of the scene, which is a valuable tool for understanding a person's visual attention and perception. -``` python -def color_generator(): - colors = {} - colors['Subject1'] = (0, 0, 255) - colors['Subject2'] = (255, 0, 0) - colors['Subject3'] = (0, 255, 0) - - return colors -``` -
+In this guide, we will show you how to generate both static and dynamic scanpath visualisations using your Reference Image Mapper exported data, like in the video above. -### 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. -``` python -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: - -1. `draw_name_legend()`: This function creates a legend box that displays only the name of the wearer on their individual scanpath video and image. -2. `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: +::: tip +Before continuing, ensure you are familiar with the [Reference Image Mapper](/enrichments/reference-image-mapper) +enrichment. Check out [this explainer video](https://www.youtube.com/watch?v=ygqzQEzUIS4&t=56s) for reference. +::: -- `r_end_point` - x and y values of the ending coordinates of the rectangular legend box -- `r_start_point` - x and y values of the starting coordinates of the rectangular legend box -- `l_end_point` - x and y values of the ending coordinates of the colored line -- `l_start_point` - x and y values of the starting coordinates of the colored line -- In `cv2.rectangle`, edit `color` to set a new color for the legend box -- In `cv2.line`, edit `thickness` to set a new width for the colored line +## Building the visualisations in an offline context +The [Reference Image Mapper](/enrichments/reference-image-mapper) 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. Since scanpaths provide a useful characterization of *where*, *when*, and *how long* attention was focused on various elements, we developed a script that enables you to generate both static and dynamic scanpaths using your Reference Image Mapper data exported from Pupil Cloud. + +## Steps +1. Run a [Reference Image Mapper](https://docs.pupil-labs.com/enrichments/reference-image-mapper/) enrichment and download the results +2. Download [this](https://gist.github.com/elepl94/9f669c4d81e455cf2095957831219664) gist and follow the instructions in the [readme](https://gist.github.com/elepl94/9f669c4d81e455cf2095957831219664#file-readme-md) + +## Final results +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, along with a video that illustrates gaze behavior on the reference image, featuring a dynamic scanpath overlay. Furthermore, an aggregated visualization, combining all participants' scanpaths, will be at your disposal, providing the opportunity for more comprehensive and in-depth analyses. + +
+ 
+