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/occlusionMasks.ts

@@ -1,6 +1,5 @@
 import type { DetectionType } from '../services/alerts';
-
-export type OcclusionMask = Record<string, number[]>; // [xmin, ymin, xmax, ymax, confidence]
+import type { OcclusionMaskApiType } from '../services/occlusionMasks';
 
 export interface BboxType {
   xmin: number;
@@ -10,28 +9,28 @@ export interface BboxType {
   confidence: number;
 }
 
-/**
- * Get the camera prefix name from the camera name
- * Example: "nemours-01" -> "nemours"
- */
-export const getCameraPrefixName = (cameraName: string): string => {
-  const lastDashIndex = cameraName.lastIndexOf('-');
-  if (lastDashIndex === -1) {
-    return cameraName;
-  }
-  return cameraName.substring(0, lastDashIndex);
+export const parseApiMask = (mask: string): BboxType | null => {
+  const match = /^\(([^)]+)\)$/.exec(mask);
+  if (!match) return null;
+
+  const values = match[1].split(',').map((v) => parseFloat(v.trim()));
+  if (values.length !== 4 || values.some(isNaN)) return null;
+
+  return {
+    xmin: values[0],
+    ymin: values[1],
+    xmax: values[2],
+    ymax: values[3],
+    confidence: 0,
+  };
 };
 
 /**
- * Generate the occlusion mask file key for localStorage
- * Format: "CAMERA_PREFIX_NAME" + "_" + "CAMERA_ANGLE_OF_VIEW"
+ * API validates with a regex that only allows 3 decimals
  */
-export const getOcclusionMaskKey = (
-  cameraName: string,
-  angleOfView: number
-): string => {
-  const prefixName = getCameraPrefixName(cameraName);
-  return `${prefixName}_${angleOfView}`;
+export const formatBboxToApiMask = (bbox: BboxType): string => {
+  const round = (v: number) => parseFloat(v.toFixed(3));
+  return `(${round(bbox.xmin)},${round(bbox.ymin)},${round(bbox.xmax)},${round(bbox.ymax)})`;
 };
 
 /**
@@ -153,25 +152,19 @@ export const doBboxesOverlap = (bbox1: BboxType, bbox2: BboxType): boolean => {
   );
 };
 
-/**
- * Get non-overlapping occlusion masks (most recent takes precedence)
- */
-export const getNonOverlappingMasks = (masks: OcclusionMask): BboxType[] => {
-  const maskEntries = Object.entries(masks).sort(
-    ([timestampA], [timestampB]) =>
-      new Date(timestampB).getTime() - new Date(timestampA).getTime()
+export const getNonOverlappingMasks = (
+  masks: OcclusionMaskApiType[]
+): BboxType[] => {
+  const sorted = [...masks].sort(
+    (a, b) =>
+      new Date(b.created_at).getTime() - new Date(a.created_at).getTime()
   );
 
   const result: BboxType[] = [];
 
-  maskEntries.forEach(([, bboxArray]) => {
-    const bbox: BboxType = {
-      xmin: bboxArray[0],
-      ymin: bboxArray[1],
-      xmax: bboxArray[2],
-      ymax: bboxArray[3],
-      confidence: bboxArray[4],
-    };
+  sorted.forEach((apiMask) => {
+    const bbox = parseApiMask(apiMask.mask);
+    if (!bbox) return;
 
     const overlaps = result.some((existingBbox) =>
       doBboxesOverlap(bbox, existingBbox)