Merge pull request #678 from pupil-labs/update_docs_nkp

AOI Editor docs and pupillometry update

neon/data-collection/data-format/index.md

@@ -115,7 +115,8 @@ This file contains [3D eye states](/data-collection/data-streams/#_3d-eye-states
 | **section id**            | Unique identifier of the corresponding section.     |
 | **recording id**          | Unique identifier of the recording this sample belongs to.     |
 | **timestamp [ns]**        | UTC timestamp in nanoseconds of the sample. Equal to the timestamp of the eye video frame this sample was generated with. |
-| **pupil diameter [mm]**   | Physical diameter of the pupils of the left and right eye. |
+| **pupil diameter left [mm]**   | Physical diameter of the pupil of the left eye. |
+| **pupil diameter right [mm]**   | Physical diameter of the pupil of the right eye. |
 | **eye&nbsp;ball&nbsp;center&nbsp;left&nbsp;x&nbsp;[mm]**<br /> **eye ball center left y [mm]**<br /> **eye ball center left z [mm]**<br /> **eye&nbsp;ball&nbsp;center&nbsp;right&nbsp;x&nbsp;[mm]**<br /> **eye&nbsp;ball&nbsp;center&nbsp;right&nbsp;y&nbsp;[mm]**<br /> **eye ball center right z [mm]** | Location of left and right eye ball centers in millimeters in relation to the scene camera of the Neon module. For details on the coordinate systems see [here](/data-collection/data-streams/#_3d-eye-states). |
 | **optical axis left x**<br /> **optical axis left y**<br /> **optical axis left z**<br /> **optical axis right x**<br /> **optical axis right y**<br /> **optical axis right z** | Directional vector describing the optical axis of the left and right eye, i.e. the vector pointing from eye ball center to pupil center of the resepective eye. For details on the coordinate systems see [here](/data-collection/data-streams/#_3d-eye-states). |
 

neon/data-collection/data-streams/index.md

@@ -49,7 +49,7 @@ You can specify the inter-eye distance (IED) of a wearer in the wearer profile b
 ## Pupil Diameters
 
 <Badge>Pupil Cloud</Badge>
-After uploading a recording to Pupil Cloud, pupil diameters are computed automatically at 200 Hz. The computed pupil diameters correspond to the physical pupil size in mm, rather than the apparent pupil size in pixels as observed in the eye videos. The algorithm does not provide independent measurements per eye but reports a single value for both eyes.
+After uploading a recording to Pupil Cloud, pupil diameters are computed automatically at 200 Hz, separately for the left and right eye. The computed pupil diameters correspond to the physical pupil size in mm, rather than the apparent pupil size in pixels as observed in the eye videos. 
 
 Similar to the 3D eye states, the accuracy of the pupil diameter measurements improves when supplying the wearer's IED in the wearer profile before making a recording.
 

neon/pupil-cloud/visualizations/areas-of-interest/index.md

@@ -1,2 +1,64 @@
 # Areas of Interest (AOIs)
-Coming soon!
+
+The AOI Editor allows you to draw areas of interest (AOIs) on top of the reference image or surface. You can draw anything from simple polygons to multiple disconnected shapes. This tool is available for use after a [Reference Image Mapper](https://docs.pupil-labs.com/neon/pupil-cloud/enrichments/reference-image-mapper/) or a [Marker Mapper](https://docs.pupil-labs.com/neon/pupil-cloud/enrichments/marker-mapper/) enrichment is completed.
+
+## Setup
+
+### AOI Editing and Drawing
+
+Upon completion of the Reference Image Mapper or Marker Mapper enrichment, access the main view of the enrichment by navigating to the **`Enrichments`** tab and selecting **`Edit AOIs`** under the section **`Tools`**.
+
+![Edit AOIs](./AOI_enrichment_view.png)
+
+From there, you will enter the AOI editing view and you are ready to start drawing AOIs on your reference image or surface.
+
+<Youtube src="7-9m3Mq-fio"/>
+
+### AOI Heatmap and Metrics
+
+To visualize your AOI heatmap:
+
+- Navigate to the **`Visualizations`** tab.
+- Click on **`Create Visualization`**.
+- Select **`AOI heatmap`** and the enrichment to which it should be applied.
+
+![View AOI heatmap](./View_AOI_heatmap.png)
+
+Within the AOI Heatmap view, users can specify the recordings to be included, the metric to be displayed, and which AOIs should be incorporated into the visualization.
+
+<Youtube src="Rrb6OKmTCOs"/>
+
+## Export Format
+
+Through the **`Visualizations`** tab, in the AOI Heatmap view, you can download the final visualization displaying the metric of your interest in **`.png`** format. 
+
+Through the **`Downloads`** tab, you can download the AOI-related files as part of the enrichment folder. Note, that the following CSV files will be empty if no AOIs are defined for a specific enrichment.
+
+### aoi_fixations.csv
+
+This file contains fixation events mapped on each area of interest.
+
+| Field                                    | Description                                                                                                                                                            |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **aoi id**                           | Unique identifier of the corresponding area of interest.                                               |
+| **section id**                       | Unique identifier of the corresponding section.                                                        |
+| **recording id**                     | Unique identifier of the recording this sample belongs to.                                             |
+| **fixation id**                      | Identifier of fixation within the section. The counter starts at the beginning of the recording.       |
+| **fixation&nbsp;duration&nbsp;[ms]**           | Duration of the fixation in milliseconds.                                                              |
+
+### aoi_metrics.csv
+
+This file contains standard fixation and gaze metrics on AOIs.
+
+| Field                                    | Description                                                                                                                                                            |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **aoi id**                           | Unique identifier of the corresponding area of interest.                           |
+| **recording id**                     | Unique identifier of the recording this sample belongs to.                         |
+| **recording name**                   | Name of the recording this sample belongs to.                                      |
+| **aoi name**                         | Name of the corresponding area of interest.                                        |
+| **average&nbsp;fixation&nbsp;duration&nbsp;[ms]**   | Average fixation duration for the corresponding area of interest in milliseconds.  |
+| **total fixations**                  | Total number of fixations for the corresponding area of interest in milliseconds.  |
+| **time&nbsp;to&nbsp;first&nbsp;fixation&nbsp;[ms]**      | Average time in milliseconds until the corresponding area of interest gets fixated on for the first time in a recording.                                                                                             |
+| **time&nbsp;to&nbsp;first&nbsp;gaze&nbsp;[ms]**      | Average time in milliseconds until the corresponding area of interest gets gazed at for the first time in a recording.                                                               |
+| **total&nbsp;fixation&nbsp;duration&nbsp;[ms]**     | Total fixation duration for the corresponding area of interest in milliseconds.   |
+| **total&nbsp;gaze&nbsp;duration&nbsp;[ms]**         | Total fixation duration for the corresponding area of interest in milliseconds.   |