matrice-analytics 0.1.97__py3-none-any.whl → 0.1.106__py3-none-any.whl

matrice_analytics/post_processing/advanced_tracker/config.py

@@ -1,6 +1,5 @@
 """
 Configuration classes for advanced tracker.
-
 This module provides configuration classes for the advanced tracker,
 including parameters for tracking algorithms and thresholds.
 """
@@ -8,7 +7,6 @@ including parameters for tracking algorithms and thresholds.
 from dataclasses import dataclass, field
 from typing import Optional
 
-
 @dataclass
 class TrackerConfig:
     """
@@ -46,6 +44,10 @@ class TrackerConfig:
     smoothing_window_size: int = 20
     smoothing_cooldown_frames: int = 5
     
+    # Class aggregation settings
+    enable_class_aggregation: bool = False
+    class_aggregation_window_size: int = 30
+    
     def __post_init__(self):
         """Validate configuration parameters."""
         if not 0.0 <= self.track_high_thresh <= 1.0:
@@ -72,6 +74,8 @@ class TrackerConfig:
         if self.output_format not in ["tracking", "detection"]:
             raise ValueError(f"Invalid output_format: {self.output_format}")
         
-        # Calculate max_time_lost if not explicitly set
         if self.max_time_lost == 30:  # Default value
-            self.max_time_lost = int(self.frame_rate / 30.0 * self.track_buffer) 
+            self.max_time_lost = int(self.frame_rate / 30.0 * self.track_buffer)
+        
+        if self.class_aggregation_window_size <= 0:
+            raise ValueError(f"class_aggregation_window_size must be positive, got {self.class_aggregation_window_size}")

matrice_analytics/post_processing/advanced_tracker/track_class_aggregator.py

@@ -0,0 +1,128 @@
+"""
+Track class aggregation for object tracking.
+
+This module provides a sliding-window-based mechanism to aggregate class labels
+across frames, reducing label flickering in tracking outputs through temporal voting.
+"""
+
+from typing import Any, Dict
+from collections import deque, Counter
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class TrackClassAggregator:
+    """
+    Maintains per-track sliding windows of class labels and returns the most frequent.
+    
+    This aggregator reduces class label flickering in tracking results by applying
+    temporal voting based on historical observations within a sliding window.
+    
+    Attributes:
+        window_size (int): Maximum number of frames to keep in the sliding window.
+        track_windows (Dict[int, deque]): Per-track sliding windows of class labels.
+    """
+    
+    def __init__(self, window_size: int = 30):
+        """
+        Initialize the TrackClassAggregator.
+        
+        Args:
+            window_size (int): Number of recent frames to consider for aggregation.
+                Must be positive. Larger windows provide more stability but slower
+                adaptation to genuine class changes.
+        """
+        if window_size <= 0:
+            raise ValueError(f"window_size must be positive, got {window_size}")
+        
+        self.window_size = window_size
+        self.track_windows: Dict[int, deque] = {}
+    
+    def update_and_aggregate(self, track_id: int, observed_class: Any) -> Any:
+        """
+        Update the sliding window for a track and return the aggregated class label.
+        
+        This method:
+        1. Adds the new observation to the track's window
+        2. Maintains window size by removing oldest entries if needed
+        3. Returns the most frequent class in the window
+        
+        Args:
+            track_id (int): Unique identifier for the track.
+            observed_class (Any): The class label observed in the current frame.
+        
+        Returns:
+            Any: The aggregated class label (most frequent in the window).
+                If there's a tie, returns the most recent among tied classes.
+        """
+        # Initialize window for new tracks
+        if track_id not in self.track_windows:
+            self.track_windows[track_id] = deque(maxlen=self.window_size)
+        
+        # Add current observation
+        window = self.track_windows[track_id]
+        window.append(observed_class)
+        
+        # Return most frequent class
+        if len(window) == 0:
+            return observed_class
+        
+        # Count frequencies and return most common
+        class_counts = Counter(window)
+        most_common = class_counts.most_common(1)[0][0]
+        
+        return most_common
+    
+    def get_aggregated_class(self, track_id: int, fallback_class: Any) -> Any:
+        """
+        Get the aggregated class for a track without updating the window.
+        
+        Args:
+            track_id (int): Unique identifier for the track.
+            fallback_class (Any): Class to return if track has no history.
+        
+        Returns:
+            Any: The aggregated class label, or fallback_class if no history exists.
+        """
+        if track_id not in self.track_windows:
+            return fallback_class
+        
+        window = self.track_windows[track_id]
+        if len(window) == 0:
+            return fallback_class
+        
+        class_counts = Counter(window)
+        return class_counts.most_common(1)[0][0]
+    
+    def remove_track(self, track_id: int) -> None:
+        """
+        Remove a track's window from memory.
+        
+        Args:
+            track_id (int): Unique identifier for the track to remove.
+        """
+        if track_id in self.track_windows:
+            del self.track_windows[track_id]
+    
+    def remove_tracks(self, track_ids: list) -> None:
+        """
+        Remove multiple tracks' windows from memory (batch operation).
+        
+        Args:
+            track_ids (list): List of track IDs to remove.
+        """
+        for track_id in track_ids:
+            self.remove_track(track_id)
+    
+    def reset(self) -> None:
+        """Clear all track windows."""
+        self.track_windows.clear()
+    
+    def get_active_track_count(self) -> int:
+        """Get the number of tracks currently being aggregated."""
+        return len(self.track_windows)
+    
+    def __repr__(self) -> str:
+        """String representation for debugging."""
+        return f"TrackClassAggregator(window_size={self.window_size}, active_tracks={len(self.track_windows)})"

matrice_analytics/post_processing/advanced_tracker/tracker.py

@@ -34,6 +34,7 @@ class AdvancedTracker:
         config (TrackerConfig): Tracker configuration.
         max_time_lost (int): The maximum frames for a track to be considered as 'lost'.
         kalman_filter (KalmanFilterXYAH): Kalman Filter object.
+        class_smoother (Optional[ClassSmoother]): Optional class smoother for class label smoothing over flicker.
     """
 
     def __init__(self, config: TrackerConfig):
@@ -53,6 +54,11 @@ class AdvancedTracker:
         self.kalman_filter = self.get_kalmanfilter()
         self.reset_id()
 
+        self.class_aggregator = None
+        if config.enable_class_aggregation:
+            from .track_class_aggregator import TrackClassAggregator
+            self.class_aggregator = TrackClassAggregator(window_size=config.class_aggregation_window_size)
+
     def update(self, detections: Union[List[Dict], Dict[str, List[Dict]]], 
                img: Optional[np.ndarray] = None) -> Union[List[Dict], Dict[str, List[Dict]]]:
         """
@@ -186,7 +192,15 @@ class AdvancedTracker:
                     }
                 
                 detections.append(detection)
-        
+
+        if self.class_aggregator is not None:
+            for detection in detections:
+                aggregated_class = self.class_aggregator.update_and_aggregate(
+                    track_id=detection['track_id'],
+                    observed_class=detection['category']
+                )
+                detection['category'] = aggregated_class
+            
         return detections
 
     def _perform_tracking_update(self, detections: List[STrack], 
@@ -296,6 +310,10 @@ class AdvancedTracker:
         
         if len(self.removed_stracks) > 1000:
             self.removed_stracks = self.removed_stracks[-999:]
+        
+        # Clean up aggregator windows for removed tracks
+        if self.class_aggregator is not None and removed_stracks:
+            self.class_aggregator.remove_tracks([t.track_id for t in removed_stracks])
 
         return [x for x in self.tracked_stracks if x.is_activated]
 
@@ -327,6 +345,9 @@ class AdvancedTracker:
         self.frame_id = 0
         self.kalman_filter = self.get_kalmanfilter()
         self.reset_id()
+    
+        if self.class_aggregator is not None:
+            self.class_aggregator.reset()
 
     @staticmethod
     def joint_stracks(tlista: List[STrack], tlistb: List[STrack]) -> List[STrack]:

matrice_analytics/post_processing/config.py

@@ -66,8 +66,8 @@ APP_NAME_TO_USECASE = {
     "suspicious_activity_detection": "suspicious_activity_detection",
     "natural_disaster_detection": "natural_disaster_detection",
     "Foot Fall": "footfall",
-    "vehicle_monitoring_parking_lot": "vehicle_monitoring_parking_lot",
-    "vehicle_monitoring_drone_view": "vehicle_monitoring_drone_view",
+    "Parking Lot Vehicle Monitoring": "vehicle_monitoring_parking_lot",
+    "Drone view vehicle monitoring": "vehicle_monitoring_drone_view",
 }
 
 APP_NAME_TO_CATEGORY = {
@@ -139,8 +139,8 @@ APP_NAME_TO_CATEGORY = {
     "suspicious_activity_detection": "security",
     "natural_disaster_detection": "environmental",
     "Foot Fall": "retail",
-    "vehicle_monitoring_parking_lot": "traffic",
-    "vehicle_monitoring_drone_view": "traffic",
+    "Parking Lot Vehicle Monitoring": "traffic",
+    "Drone view vehicle monitoring": "traffic",
 }
 
 def get_usecase_from_app_name(app_name: str) -> str: