feat: migrate occlusion masks to backend API (#184)

* feat: add poseId to SequenceWithCameraInfoType

Needed for the occlusion mask API migration which uses pose_id
to fetch and create masks.

* feat: migrate occlusion masks from localStorage to backend API

Replace localStorage-based occlusion masks with backend API calls:
- GET/POST/DELETE via /api/v1/poses/{id}/occlusion_masks
- New parseApiMask/formatBboxToApiMask utils for API mask format
- Round coordinates to 3 decimal places (API validation constraint)
- OcclusionMaskModal now uses poseId instead of camera name/angle

Author: ThbltLmr

src/components/Alerts/OcclusionMaskModal/OcclusionMaskModal.tsx

@@ -13,14 +13,15 @@ import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 
 import { getDetectionsBySequence } from '@/services/alerts';
 import {
-  addOcclusionMask,
-  clearOcclusionMasks,
-  getOcclusionMasks,
+  createOcclusionMask,
+  deleteAllOcclusionMasksByPose,
+  getOcclusionMasksByPose,
 } from '@/services/occlusionMasks';
 import type { SequenceWithCameraInfoType } from '@/utils/alerts';
 import {
   type BboxType,
   enlargeBbox,
+  formatBboxToApiMask,
   getHighestConfidenceBbox,
   getHighestConfidenceDetection,
   getNonOverlappingMasks,
@@ -81,72 +82,34 @@ export const OcclusionMaskModal = ({
 
   // Query for existing occlusion masks
   const { data: existingMasks = [], isLoading: isLoadingMasks } = useQuery({
-    queryKey: [
-      'occlusionMasks',
-      sequence.camera?.name,
-      sequence.camera?.angle_of_view,
-    ],
-    queryFn: () => {
-      if (!sequence.camera?.name || sequence.camera.angle_of_view === null) {
-        return [];
-      }
-      const masks = getOcclusionMasks(
-        sequence.camera.name,
-        sequence.camera.angle_of_view
-      );
+    queryKey: ['occlusionMasks', sequence.poseId],
+    queryFn: async () => {
+      if (!sequence.poseId) return [];
+      const masks = await getOcclusionMasksByPose(sequence.poseId);
       return getNonOverlappingMasks(masks);
     },
-    enabled:
-      open && !!sequence.camera?.name && sequence.camera.angle_of_view !== null,
+    enabled: open && !!sequence.poseId,
   });
 
   // Mutation for adding occlusion mask
   const addMaskMutation = useMutation({
-    mutationFn: ({
-      cameraName,
-      angleOfView,
-      bbox,
-    }: {
-      cameraName: string;
-      angleOfView: number;
-      bbox: BboxType;
-    }) => {
-      addOcclusionMask(cameraName, angleOfView, bbox);
-      return Promise.resolve();
-    },
+    mutationFn: ({ poseId, bbox }: { poseId: number; bbox: BboxType }) =>
+      createOcclusionMask(poseId, formatBboxToApiMask(bbox)),
     onSuccess: () => {
-      // Invalidate and refetch occlusion masks
       void queryClient.invalidateQueries({
-        queryKey: [
-          'occlusionMasks',
-          sequence.camera?.name,
-          sequence.camera?.angle_of_view,
-        ],
+        queryKey: ['occlusionMasks', sequence.poseId],
       });
       onClose();
     },
   });
 
   // Mutation for clearing all masks
   const clearMasksMutation = useMutation({
-    mutationFn: ({
-      cameraName,
-      angleOfView,
-    }: {
-      cameraName: string;
-      angleOfView: number;
-    }) => {
-      clearOcclusionMasks(cameraName, angleOfView);
-      return Promise.resolve();
-    },
+    mutationFn: ({ poseId }: { poseId: number }) =>
+      deleteAllOcclusionMasksByPose(poseId),
     onSuccess: () => {
-      // Invalidate and refetch occlusion masks
       void queryClient.invalidateQueries({
-        queryKey: [
-          'occlusionMasks',
-          sequence.camera?.name,
-          sequence.camera?.angle_of_view,
-        ],
+        queryKey: ['occlusionMasks', sequence.poseId],
       });
     },
   });
@@ -161,29 +124,19 @@ export const OcclusionMaskModal = ({
     : null;
 
   const handleConfirmSelection = () => {
-    if (
-      !proposedBbox ||
-      !sequence.camera?.name ||
-      sequence.camera.angle_of_view === null
-    ) {
-      return;
-    }
+    if (!proposedBbox || !sequence.poseId) return;
 
     addMaskMutation.mutate({
-      cameraName: sequence.camera.name,
-      angleOfView: sequence.camera.angle_of_view,
+      poseId: sequence.poseId,
       bbox: proposedBbox,
     });
   };
 
   const handleDeleteAll = () => {
-    if (!sequence.camera?.name || sequence.camera.angle_of_view === null) {
-      return;
-    }
+    if (!sequence.poseId) return;
 
     clearMasksMutation.mutate({
-      cameraName: sequence.camera.name,
-      angleOfView: sequence.camera.angle_of_view,
+      poseId: sequence.poseId,
     });
   };
 

src/services/occlusionMasks.ts

@@ -1,87 +1,66 @@
-import type { BboxType, OcclusionMask } from '../utils/occlusionMasks';
-import { getOcclusionMaskKey } from '../utils/occlusionMasks';
+import type { AxiosResponse } from 'axios';
+import * as z from 'zod/v4';
 
-/**
- * Get occlusion masks from localStorage for a specific camera and angle of view
- */
-export const getOcclusionMasks = (
-  cameraName: string,
-  angleOfView: number
-): OcclusionMask => {
-  const key = getOcclusionMaskKey(cameraName, angleOfView);
-  const stored = localStorage.getItem(`occlusion_mask_${key}`);
+import { apiInstance } from './axios';
 
-  if (!stored) {
-    return {};
-  }
+const occlusionMaskReadSchema = z.object({
+  id: z.number(),
+  pose_id: z.number(),
+  mask: z.string(),
+  created_at: z.iso.datetime({ local: true }),
+});
 
-  try {
-    const masks = JSON.parse(stored) as OcclusionMask;
+export type OcclusionMaskApiType = z.infer<typeof occlusionMaskReadSchema>;
 
-    // Filter out masks older than 120 days
-    const cutoffDate = new Date();
-    cutoffDate.setDate(cutoffDate.getDate() - 120);
+const occlusionMaskListResponseSchema = z.array(occlusionMaskReadSchema);
 
-    const filteredMasks: OcclusionMask = {};
-    Object.entries(masks).forEach(([timestamp, bbox]) => {
-      const maskDate = new Date(timestamp);
-      if (maskDate >= cutoffDate) {
-        filteredMasks[timestamp] = bbox;
-      }
+export const getOcclusionMasksByPose = async (
+  poseId: number
+): Promise<OcclusionMaskApiType[]> => {
+  return apiInstance
+    .get(`/api/v1/poses/${poseId.toString()}/occlusion_masks`)
+    .then((response: AxiosResponse) => {
+      const result = occlusionMaskListResponseSchema.safeParse(response.data);
+      return result.data ?? [];
+    })
+    .catch((err: unknown) => {
+      console.error(err);
+      throw err;
     });
-
-    return filteredMasks;
-  } catch (error) {
-    console.error('Error parsing occlusion masks from localStorage:', error);
-    return {};
-  }
 };
 
-/**
- * Save occlusion masks to localStorage for a specific camera and angle of view
- */
-export const saveOcclusionMasks = (
-  cameraName: string,
-  angleOfView: number,
-  masks: OcclusionMask
-): void => {
-  const key = getOcclusionMaskKey(cameraName, angleOfView);
-
-  try {
-    localStorage.setItem(`occlusion_mask_${key}`, JSON.stringify(masks));
-  } catch (error) {
-    console.error('Error saving occlusion masks to localStorage:', error);
-  }
+export const createOcclusionMask = async (
+  poseId: number,
+  mask: string
+): Promise<OcclusionMaskApiType> => {
+  return apiInstance
+    .post('/api/v1/occlusion_masks/', { pose_id: poseId, mask })
+    .then((response: AxiosResponse) => {
+      const result = occlusionMaskReadSchema.safeParse(response.data);
+      if (!result.success) {
+        throw new Error('INVALID_API_RESPONSE');
+      }
+      return result.data;
+    })
+    .catch((err: unknown) => {
+      console.error(err);
+      throw err;
+    });
 };
 
-/**
- * Add a new occlusion mask
- */
-export const addOcclusionMask = (
-  cameraName: string,
-  angleOfView: number,
-  bbox: BboxType
-): void => {
-  const currentMasks = getOcclusionMasks(cameraName, angleOfView);
-  const timestamp = new Date().toISOString().replace('T', ' ').substring(0, 19);
-
-  currentMasks[timestamp] = [
-    bbox.xmin,
-    bbox.ymin,
-    bbox.xmax,
-    bbox.ymax,
-    bbox.confidence,
-  ];
-
-  saveOcclusionMasks(cameraName, angleOfView, currentMasks);
+export const deleteOcclusionMask = async (maskId: number): Promise<void> => {
+  return apiInstance
+    .delete(`/api/v1/occlusion_masks/${maskId.toString()}`)
+    .then(() => undefined)
+    .catch((err: unknown) => {
+      console.error(err);
+      throw err;
+    });
 };
 
-/**
- * Clear all occlusion masks for a specific camera and angle of view
- */
-export const clearOcclusionMasks = (
-  cameraName: string,
-  angleOfView: number
-): void => {
-  saveOcclusionMasks(cameraName, angleOfView, {});
+export const deleteAllOcclusionMasksByPose = async (
+  poseId: number
+): Promise<void> => {
+  const masks = await getOcclusionMasksByPose(poseId);
+  await Promise.all(masks.map((mask) => deleteOcclusionMask(mask.id)));
 };

src/utils/alerts.test.ts

@@ -84,16 +84,17 @@ describe('extractCameraListFromAlert', () => {
       sequences: [
         {
           id: 1,
+          poseId: null,
           camera: camera1,
           lastSeenAt: null,
           azimuth: 0,
-
           coneAngle: 0,
           labelWildfire: null,
           startedAt: null,
         },
         {
           id: 2,
+          poseId: null,
           camera: camera2,
           lastSeenAt: null,
           azimuth: 0,
@@ -144,7 +145,6 @@ describe('hasNewSequenceSince', () => {
       [
         {
           id: 1,
-
           started_at: '2025-02-25T05:37:03',
           sequences: [],
           organization_id: 0,

src/utils/alerts.ts

@@ -19,6 +19,7 @@ export type LabelWildfireValues =
 
 export interface SequenceWithCameraInfoType {
   id: number;
+  poseId: number | null;
   camera: CameraType | null;
   startedAt: string | null;
   lastSeenAt: string | null;
@@ -46,6 +47,7 @@ export const mapAlertTypeApiToAlertType = (
         .sort((s1, s2) => (getDateOrNowNb(s1) > getDateOrNowNb(s2) ? 1 : -1))
         .map((sequence) => ({
           id: sequence.id,
+          poseId: sequence.pose_id,
           camera:
             camerasList.find((camera) => camera.id == sequence.camera_id) ??
             null,

src/utils/live.test.ts

@@ -90,6 +90,7 @@ describe('getMoveToAzimuthFromAlert', () => {
           startedAt: null,
           lastSeenAt: null,
           azimuth: 0,
+          poseId: null,
           coneAngle: 0,
           labelWildfire: null,
         },
@@ -113,6 +114,7 @@ describe('getMoveToAzimuthFromAlert', () => {
           startedAt: null,
           lastSeenAt: null,
           azimuth: 5,
+          poseId: null,
           coneAngle: 0,
           labelWildfire: null,
         },