Adds new table Occlusion Mask & creates CRUD related endpoints

[fe51]

Pitch

Occlusion masks allow users to define areas that generate recurring false positives. (occlusion masks are related to a defined position of a camera) -> pyronear/new-pyro-platform#85 or pyronear/new-pyro-platform#103 give an indication of how this look on GUI

Theses masks are regularly retrieved by onsite devices (raspberry pi) in order not to generate alerts in these areas (which would then be distributed but irrelevant)

To date, (due to a lack of time initially) the implementation of occlusion masks management has been done outside of the API.
However, this creates additional dependencies, as the current use of write/read on an S3 from the platform or Raspberry Pi is not optimal in terms of rights management, and this is the kind of information that should be managed in the API.
(you can find more context on how it is done currently at the end of the issue)

Occlusion masks must be managed through pyro-api, and so far, stored in the db :

About the table occlusion_masks

bbox field : For the first iteration, we could keep the current input so an bbox as in detection table

string representation of list of detection localizations, each represented as a tuple of relative coords (max 3 decimals) in order: xmin, ymin, xmax, ymax, conf (see table detections)

Below some guideline about the new table (Description is here for the purpose of the issue but not sure if we include it postgresSQL tables)

Do we include a created_at field ? -> To discuss

Column	Type	Constraints	Description
id	INT	PRIMARY KEY	Unique identifier
pose_id	INT	FOREIGN KEY → poses(id)	Reference to the related pose in poses table
bbox	String	see in detections	a given occlusion bbox for a pose
created_at	TIMESTAMP	DEFAULT CURRENT_TIMESTAMP	Record creation timestamp

What is need to be done

• As a user, I want to update/set occlusion masks of a position of a camera in my organisation
• As a camera (often raspberry pi managing each camera on a site), I want to read occlusion mask of a given position
• As a admin (in case wanting to define the occlusion areas before setting up access to users, or define sky areas or other areas to avoid poor first impressions.), I want to update/set occlusion masks for a given a position of a camera.

Suggestion guidelines

• Add every thing related to the introduction of a the new table occlusion masks in the api
• CRUD for API Occlusion Mask Resource -> To be detailed
• Add migration script
• Update UML at scripts/dbdiagram.txt
• Do not forget to add tests :)

Happy to discuss it ! 😄

---

Context - Technical info about what is done currently (not here in the api)

S3 bucket
Occlusion masks are available via a S3 bucket, hence you need to setup S3

• S3 info : S3_ENDPOINT_URL, S3_ACCESS_KEY_ID, S3_SECRET_KEY, S3_REGION
• bucket_name = "occlusion-masks-json"

About occlusion masks file names and structure
File name
In the bucket, there is one occlusion mask json file per camera position. the file name is structured as follow:
"CAMERA_PREFIX_NAME" + "_" + "CAMERA_POSITION_AZIMUTH"

• CAMERA_PREFIX_NAME is the kind of the "site" name, so the camera name minus camera number (ex if camera name is "nemours-01" : camera prefix name is "nemours"
• CAMERA_POSITION_AZIMUTH: you can find this info in latest sequences info (/see api/v1/sequences/unlabeled/latest) as "azimuth"

ex : for nemours-01 with azimuth of 246 degree : occlusion mask file is nemours_246.json

Content Structure

Example of the content structure

{
  "2025-06-06 12:23:45": [
    0.16090000000000002,
    0.5345000000000001,
    0.1851,
    0.5674999999999999,
    0.507
  ],
  "2025-07-11 13:00:16": [
    0.0226,
    0.5811999999999999,
    0.0314,
    0.5988,
    0.592
  ]
}

It is composed of a list of datetime (when the bbox has to be added to the mask) associated with an array.
The array represent a bbox (object present in detection table : string representing an array with xmin, ymin, xmax, ymax and confidence score (same structure of what you can find in detection attribute bboxes)

coordinate of bbox the rectangle values are normalized

Might be relevant to design a feature allowing to define other type of form, not only rectangles in the future.