**Manual Gaze Mapping / Manual Mapping:**

Design: https://www.figma.com/file/rVdulet73OQ65GJAfYdXCL/PC-%3A-Redesign-P2-Development?type=design&node-id=743-108397&mode=design&t=4XkzNvtVjyMTj4qt-4

For the implementation part, few questions, considerations, assumptions are made that need to be validated.

- Confirmation that this is about fixation, not gaze? Because gaze is recorded at 200Hz, while fixations are comparatively less frequent and more manageable. Would the user want to map 200 sampled gaze points onto a reference image?
`Yes`

- For the `auto advance on` mapping, it plots the recording's gaze, scales it as per the size of the reference image, and returns it which is plotted on reference image.

- Since the requirements mandate frequent update operations, Clickhouse does not seem to be a suitable candidate for that, as it's not suitable for small updates but large batch of data. We need something with OLTP. What should be used to store the fixation coordinates mapped onto the reference image and support the update of a single row at a time?

- When copying the recording's fixation data, it will be copied as-is with the enrichment_id added, and no coordinates will be changed. These coordinates will be scaled and displayed on the reference image when `auto advance on` is enabled and will be updated when the gaze circle is repositioned or gaze circle is deleted.

- Since we are dealing with a single coordinate at a time, we must ensure that each coordinate is successfully updated in the backend and sent back the updated coordinates between a duration or between numbers of fixation id to the frontend through WebSocket, or the frontend will make a call to fetch the updated coordinates?

- Also, what if user seeks multiple times in the recording? Will the frontend make a new request every time?

- Confirmation that we are supporting the update and deletion of the fixation coordinates? `Yes`

**Auto Advance On:**
- Recording's fixation coordinates will be scaled as per the reference image and initially shown on the reference image.
- User can select that gaze circle to reposition and save the new coordinates
- The user will hover over the reference image to see the gaze circle and clicking will save the new coordinates
- Right clicking on the selected gaze circle shows option to delete the coordinates

**Auto Advance Off:**
- Initially, no fixations would be shown on the reference image.
- The user will hover over the reference image to see the gaze circle.
- Clicking on the reference image will reposition the gaze circle and update the coordinates in the database.
- Right clicking on the selected gaze circle shows option to delete the coordinates

**Recording Not Found:**
- What does it mean? Do we want to ignore a particular recording for mapping?
- Manual mapping intends to work with a recording and a reference image, and a user will have to select every recording of the project, manually map the fixation on the reference image?

**Deleting Fixation:**
- After right-clicking on a fixation and deleting it, can a user add the same fixation again?

The difference between `auto advance on` and `auto advance off` is that `auto advance on` will show the recording's fixation coordinates on the reference image, which can be further clicked to reposition or delete, while `auto advance off` will not show any coordinates initially. On clicking, it can add new coordinates or delete the added coordinate.

Backend-wise, both `auto advance on` and `auto advance off` will have the recording's fixation coordinates copied for that enrichment, but in frontend `auto advance off` will not show any coordinates until they are added or previously added coordinates are updated, based on a flag in the table that indicates if the value is updated for the first time.

___

Flow of the operations from dev pov:
- when a new manual gaze mapping enrichment is created
- create an entry in `manual_mapper_definition` table
- copy the recording's `fixations.csv` data with the enrichment id to the new `manual_fixation_on_aoi` table
- upload a reference image and update its id in the created entry in `manual_mapper_definition` table
- when `auto advance on`
- show the recording's fixation coordinates on the reference image
- allow option to select the gaze circle or show the new gaze circle on-hover to reposition to save the new position coordinate for that fixation id
- allow option to select the gaze circle, and delete the fixation coordinate for that particular fixation id
- when `auto advance off`
- initially, no fixation coordinates are shown on the reference image
- show gaze circle on hover and click to save the new position coordinate for that fixation id
- allow to select the saved gaze circle to reposition to save the new position coordinate for that fixation id
- allow option to select the gaze circle, and delete the fixation coordinate for that particular fixation id

___

DB:

Table `manually_mapped_fixations`
- use id as primary key
- unique index using BRIN(enrichment_id, recording_id, start, end)

| column_name | column_description | column_type | column_compression_codec |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | --------------------------- |
| id | | UUID | |
| enrichment_id | | UUID | |
| recording_id | | UUID | |
| fixation_id | | Int | |
| x | (fixation x coordinate) | SmallInt | CODEC(Delta(4), ZSTD(1)) |
| y | (fixation y coordinate) | SmallInt | CODEC(Delta(4), ZSTD(1)) |
| start_time | (fixation start time) | bigint | CODEC(DoubleDelta, ZSTD(1)) |
| end_time | (fixation end time recording offset in nanoseconds) ie. 15s into recording = 15000000000 | bigint | CODEC(DoubleDelta, ZSTD(1)) |

Total memory taken by table

total_uncompressed_float32_size = numbers of float32 columns * number of rows * 4       | 2 * num_row  * 4
total_compressed_float32_size = total_uncompressed_float32_size/1.376

total_uncompressed_int64_size = numbers of int64 columns * number of rows * 8           | 2 * num_row  * 8
total_compressed_int64_size = total_uncompressed_int64_size/2.106

total_uncompressed_uint16_size = numbers of uint16 columns * number of rows * 2         | 1 * num_row  * 2
total_compressed_uint16_size = total_uncompressed_uint16_size/17.759

total_uncompressed_uint8_size = numbers of uint8 columns * number of rows * 1           | 1 * num_row  * 1
total_compressed_uint8_size = total_uncompressed_uint8_size/117.418

total_uncompressed_uuid_size = numbers of uuid columns * number of rows * 16            | 2 * num_row  * 16
total_compressed_uuid_size = total_uncompressed_uuid_size/205.168


total_uncompressed_size = total_uncompressed_float32_size + total_uncompressed_int64_size + total_uncompressed_uint16_size + total_uncompressed_uint8_size + total_uncompressed_uuid_size
total_compressed_size = total_compressed_float32_size + total_compressed_int64_size + total_compressed_uint16_size + total_compressed_uint8_size + total_compressed_uuid_size


- 102887 recordings in `recording_gazepoints`
- 600 recordings have 422693 unique fixations
- 704 fixations per recording
- 72482691 fixations in 102887 recordings
- 1% of 72482691 = 724826

- Total uncompressed size = (2 * 724826 * 4) + (2 * 724826 * 8) + (1 * 724826 * 2) + (1 * 724826 * 1) + (2 * 724826 * 16) = 42764734 bytes = 0.042764734 GB
- Total compressed size = (2 * 724826 * 4)/1.376 + (2 * 724826 * 8)/2.106 + (1 * 724826 * 2)/17.759 + (1 * 724826 * 1)/117.418 + (2 * 724826 * 16)/205.168 = 9921708 bytes = 0.009921708 GB

Table `manual_mapper_definition`
- manual_mapper_id
- enrichment_id
- reference_image_id
- trashed_at? (to support delete operation)

___

Endpoints

`/manual_fixation_on_aoi`
- No endpoint is needed for populating fixation as it should be done in backend on enrichment creation
- Endpoint that returns all the mapped fixation coordinates of that enrichment and recording
- Endpoint that returns all the mapped fixation coordinates of that enrichment and recording (between a particular time or between particular fixations or of a particular fixation_id)
- Endpoint that update the fixation coordinate using enrichment_id, recording_id and fixation_id
- Endpoint that delete the fixation coordinate using enrichment_id, recording_id and fixation_id

`/manual_mapper`
- Endpoint to store definition of the enrichment: manual_mapper_id, reference_image_id, enrichment id
- Endpoint to update the reference image id for an enrichment in the `manual_mapper_definition` table

WE HAVE:
`DELETE /projects/proj-1/enrichments/static-353`

NEEDED:
`POST /mappers/static/` => {
"name": "static",
"start_event": "recording.begin",
"stop_event": "recording.end",
"image_id": "file-235"
}
`GET /mappers/static/{static_enrichment_id}`
`PATCH /mappers/static/static-353` => {
"image_id": "image-123"
}
`GET /mappers/static/{static_enrichment_id}/fixations`

LATER:
`GET /projects/proj-1/enrichments/static-353` make args virtual based on static enrichment row
`DELETE /mappers/static/static-353`
`GET /mappers/static/` => [static1]
`GET /mappers:kinds` => ["reference", "static", "marker"]
`GET /mappers/` => [rim1, rim2, static1, marker1]
`POST /mappers/reference/` => {
"name": "rim8",
"start_event": "recording.begin",
"stop_event": "recording.end",
"scanning_recording_id": "rec-235",
"reference_image_id": "file-235"
}
`GET /mappers/static/static-123`
`GET /projects/proj-1/enrichments/static-123`

Supported methods for `/mappers/static/{static_enrichment_id}/fixations`

GET /mappers/static/{static_enrichment_id}/mappings/recid-1/ -> returns mappings for rec1
(retrieves
    x, (null if no mapping exists yet)
    y,
    recording_id,
    fixation_id,
    start,
    end
along with other details)

PUT `/mappers/static/{static_enrichment_id}/mappings/recid-1/fixationid-21`
(updates x, y)
	- x
	- y

DELETE `/mappers/static/{static_enrichment_id}/mappings/recid-1/fixationid-21`

CREATE TABLE static_image_mapper (
  ref_img_id uuid references files(id),
  kind text CHECK (kind = 'static-image-mapper')
) INHERITS (enrichments);