matrice-analytics 0.1.60__py3-none-any.whl

matrice_analytics/post_processing/utils/smoothing_utils.py

@@ -0,0 +1,358 @@
+"""
+BBox smoothing utilities for post-processing operations.
+
+This module provides generalized smoothing algorithms for bounding box detections
+to reduce noise and false positives in detection results.
+"""
+
+from typing import List, Dict, Any, Optional, Union
+from collections import deque
+from dataclasses import dataclass
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class BBoxSmoothingConfig:
+    """Configuration for bbox smoothing algorithms."""
+    
+    smoothing_algorithm: str = "observability"  # "window" or "observability"
+    window_size: int = 20
+    cooldown_frames: int = 5
+    confidence_threshold: float = 0.5
+    confidence_range_factor: float = 0.5  # For observability algorithm
+    track_by_centroid: bool = True
+    centroid_quantization: int = 10
+    enable_smoothing: bool = True  # Master flag to enable/disable smoothing
+    
+    def __post_init__(self):
+        """Validate configuration parameters."""
+        if self.smoothing_algorithm not in ["window", "observability"]:
+            logging.error(f"Invalid smoothing_algorithm: {self.smoothing_algorithm}. Must be 'window' or 'observability'")
+            self.smoothing_algorithm = "observability"
+        
+        # Convert window_size to int if it's a string
+        if isinstance(self.window_size, str):
+            try:
+                self.window_size = int(self.window_size)
+            except ValueError:
+                logging.error(f"window_size must be a valid integer, got {self.window_size}")
+                self.window_size = 20
+        
+        if self.window_size <= 0:
+            logging.error(f"window_size must be positive, got {self.window_size}")
+            self.window_size = 20
+        # Convert cooldown_frames to int if it's a string
+        if isinstance(self.cooldown_frames, str):
+            try:
+                self.cooldown_frames = int(self.cooldown_frames)
+            except ValueError:
+                logging.error(f"cooldown_frames must be a valid integer, got {self.cooldown_frames}")
+                self.cooldown_frames = 5
+        
+        if self.cooldown_frames < 0:
+            logging.error(f"cooldown_frames must be non-negative, got {self.cooldown_frames}")
+            self.cooldown_frames = 5
+        # Convert confidence_threshold to float if it's a string
+        if isinstance(self.confidence_threshold, str):
+            try:
+                self.confidence_threshold = float(self.confidence_threshold)
+            except ValueError:
+                logging.error(f"confidence_threshold must be a valid number, got {self.confidence_threshold}")
+                self.confidence_threshold = 0.5
+        if not 0.0 <= self.confidence_threshold <= 1.0:
+            logging.error(f"confidence_threshold must be between 0.0 and 1.0, got {self.confidence_threshold}")
+            self.confidence_threshold = 0.5
+        
+        # Convert confidence_range_factor to float if it's a string
+        if isinstance(self.confidence_range_factor, str):
+            try:
+                self.confidence_range_factor = float(self.confidence_range_factor)
+            except ValueError:
+                logging.error(f"confidence_range_factor must be a valid number, got {self.confidence_range_factor}")
+                self.confidence_range_factor = 0.5
+        
+        if not 0.0 <= self.confidence_range_factor <= 1.0:
+            logging.error(f"confidence_range_factor must be between 0.0 and 1.0, got {self.confidence_range_factor}")
+            self.confidence_range_factor = 0.5
+        
+        # Convert centroid_quantization to int if it's a string
+        if isinstance(self.centroid_quantization, str):
+            try:
+                self.centroid_quantization = int(self.centroid_quantization)
+            except ValueError:
+                logging.error(f"centroid_quantization must be a valid integer, got {self.centroid_quantization}")
+                self.centroid_quantization = 10
+
+
+class BBoxSmoothingTracker:
+    """Tracks individual objects for smoothing across frames."""
+    
+    def __init__(self, config: BBoxSmoothingConfig):
+        self.config = config
+        self.object_windows = {}  # {object_id: deque}
+        self.object_cooldowns = {}  # {object_id: cooldown_counter}
+        self.logger = logging.getLogger(f"{__name__}.BBoxSmoothingTracker")
+    
+    def reset(self):
+        """Reset tracker state."""
+        self.object_windows.clear()
+        self.object_cooldowns.clear()
+        self.logger.debug("BBox smoothing tracker reset")
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get tracker statistics."""
+        return {
+            "active_objects": len(self.object_windows),
+            "total_cooldowns": len(self.object_cooldowns),
+            "window_size": self.config.window_size,
+            "cooldown_frames": self.config.cooldown_frames
+        }
+
+
+def _get_object_id(detection: Dict, config: BBoxSmoothingConfig) -> str:
+    """
+    Generate unique object ID from detection using robust hashing.
+    
+    Args:
+        detection: Detection dictionary
+        config: Smoothing configuration
+        
+    Returns:
+        str: Unique object identifier
+    """
+    # Extract bbox coordinates (handle different formats)
+    bbox = detection.get('bounding_box', detection.get('bbox', {}))
+    
+    # Normalize bbox to consistent format
+    if isinstance(bbox, dict):
+        if 'x' in bbox and 'y' in bbox and 'width' in bbox and 'height' in bbox:
+            x, y, w, h = bbox['x'], bbox['y'], bbox['width'], bbox['height']
+        elif 'xmin' in bbox and 'ymin' in bbox and 'xmax' in bbox and 'ymax' in bbox:
+            x, y, w, h = bbox['xmin'], bbox['ymin'], bbox['xmax'] - bbox['xmin'], bbox['ymax'] - bbox['ymin']
+        elif 'x1' in bbox and 'y1' in bbox and 'x2' in bbox and 'y2' in bbox:
+            x, y, w, h = bbox['x1'], bbox['y1'], bbox['x2'] - bbox['x1'], bbox['y2'] - bbox['y1']
+        else:
+            # Fallback: try to extract any numeric values
+            values = [v for v in bbox.values() if isinstance(v, (int, float))]
+            if len(values) >= 4:
+                x, y, w, h = values[0], values[1], values[2], values[3]
+            else:
+                x, y, w, h = 0, 0, 0, 0
+    else:
+        # Handle list/tuple format
+        if isinstance(bbox, (list, tuple)) and len(bbox) >= 4:
+            x, y, w, h = bbox[0], bbox[1], bbox[2], bbox[3]
+        else:
+            x, y, w, h = 0, 0, 0, 0
+    
+    # Quantize coordinates to reduce jitter (similar to centroid approach but more robust)
+    quantized_x = int(x // config.centroid_quantization) if hasattr(config, 'centroid_quantization') else int(x)
+    quantized_y = int(y // config.centroid_quantization) if hasattr(config, 'centroid_quantization') else int(y)
+    quantized_w = int(w // config.centroid_quantization) if hasattr(config, 'centroid_quantization') else int(w)
+    quantized_h = int(h // config.centroid_quantization) if hasattr(config, 'centroid_quantization') else int(h)
+    
+    # Get other attributes (handle missing values)
+    confidence = detection.get('confidence', 0.0)
+    category = detection.get('category', 'unknown')
+    
+    # Create hash string from quantized bbox and attributes (no track_id dependency)
+    hash_string = f"{quantized_x}_{quantized_y}_{quantized_w}_{quantized_h}_{confidence}_{category}"
+    
+    # Generate hash and ensure it's positive
+    detection_hash = abs(hash(hash_string))
+    return f"detection_{detection_hash}"
+
+
+def _apply_window_smoothing(detections: List[Dict], 
+                          config: BBoxSmoothingConfig,
+                          tracker: BBoxSmoothingTracker) -> List[Dict]:
+    """
+    Apply window smoothing without cooldown (frame-accurate).
+    
+    Args:
+        detections: List of detection dictionaries
+        config: Smoothing configuration
+        tracker: Tracker instance for state management
+        
+    Returns:
+        List[Dict]: Smoothed detections (only from current frame)
+    """
+    output = []
+    current_object_ids = set()
+    
+    # Process current detections
+    for det in detections:
+        object_id = _get_object_id(det, config)
+        current_object_ids.add(object_id)
+        
+        # Initialize window if new object
+        if object_id not in tracker.object_windows:
+            tracker.object_windows[object_id] = deque(maxlen=config.window_size)
+        
+        # Add to window
+        tracker.object_windows[object_id].append(det)
+    
+    # Only output detections from current frame
+    for object_id in current_object_ids:
+        if object_id in tracker.object_windows:
+            window = tracker.object_windows[object_id]
+            if window:
+                # Calculate average confidence for smoothing
+                confidences = [d.get('confidence', 0.0) for d in window]
+                avg_confidence = sum(confidences) / len(confidences) if confidences else 0.0
+                
+                # Output if above threshold
+                if avg_confidence >= config.confidence_threshold:
+                    output.append(window[-1])  # Most recent detection
+    
+    # Clean up unused windows (optional memory management)
+    for object_id in list(tracker.object_windows.keys()):
+        if object_id not in current_object_ids:
+            del tracker.object_windows[object_id]
+    
+    return output
+
+
+def _apply_observability_smoothing(detections: List[Dict],
+                                 config: BBoxSmoothingConfig,
+                                 tracker: BBoxSmoothingTracker) -> List[Dict]:
+    """
+    Apply observability/confidence tradeoff smoothing without cooldown (frame-accurate).
+    
+    Args:
+        detections: List of detection dictionaries
+        config: Smoothing configuration
+        tracker: Tracker instance for state management
+        
+    Returns:
+        List[Dict]: Smoothed detections (only from current frame)
+    """
+    output = []
+    current_object_ids = set()
+    
+    # Process current detections
+    for det in detections:
+        object_id = _get_object_id(det, config)
+        current_object_ids.add(object_id)
+        
+        # Initialize window if new object
+        if object_id not in tracker.object_windows:
+            tracker.object_windows[object_id] = deque(maxlen=config.window_size)
+        
+        tracker.object_windows[object_id].append(det)
+    
+    # Only process detections from current frame
+    for object_id in current_object_ids:
+        if object_id in tracker.object_windows:
+            window = tracker.object_windows[object_id]
+            if window:
+                # Calculate observability score
+                observability_score = len(window) / config.window_size
+                
+                # Get current confidence
+                current_confidence = window[-1].get('confidence', 0.0)
+                
+                # Define confidence range
+                conf_range = config.confidence_threshold * config.confidence_range_factor
+                
+                # Decision logic
+                if current_confidence >= config.confidence_threshold:
+                    # High confidence: always keep
+                    output.append(window[-1])
+                elif current_confidence >= (config.confidence_threshold - conf_range):
+                    # Borderline: apply tradeoff
+                    confidence_factor = (config.confidence_threshold - current_confidence) / conf_range
+                    if confidence_factor <= observability_score:
+                        output.append(window[-1])
+                # else: too low confidence, discard
+    
+    # Clean up unused windows (optional memory management)
+    for object_id in list(tracker.object_windows.keys()):
+        if object_id not in current_object_ids:
+            del tracker.object_windows[object_id]
+    
+    return output
+
+
+def bbox_smoothing(detections: Union[List[Dict], Dict[str, List[Dict]]], 
+                  config: BBoxSmoothingConfig,
+                  tracker: Optional[BBoxSmoothingTracker] = None) -> Union[List[Dict], Dict[str, List[Dict]]]:
+    """
+    Apply smoothing algorithm to bbox detections.
+    
+    Args:
+        detections: Either:
+                   - List of detection dictionaries (detection format)
+                   - Dict with frame keys containing lists of detections (tracking format)
+        config: Smoothing configuration
+        tracker: Optional tracker instance for persistent state across frames
+        
+    Returns:
+        Same format as input: List[Dict] or Dict[str, List[Dict]]
+    """
+    # Early return if smoothing is disabled
+    if not config.enable_smoothing:
+        return detections
+    
+    # Early return if no detections
+    if not detections:
+        return detections
+    
+    # Create tracker if not provided
+    if tracker is None:
+        tracker = BBoxSmoothingTracker(config)
+    
+    # Handle tracking format (dict with frame keys)
+    if isinstance(detections, dict):
+        smoothed_tracking_results = {}
+        
+        for frame_id, frame_detections in detections.items():
+            if isinstance(frame_detections, list):
+                # Apply smoothing to this frame's detections
+                if config.smoothing_algorithm == "observability":
+                    smoothed_frame = _apply_observability_smoothing(frame_detections, config, tracker)
+                else:  # "window"
+                    smoothed_frame = _apply_window_smoothing(frame_detections, config, tracker)
+                
+                smoothed_tracking_results[frame_id] = smoothed_frame
+        
+        return smoothed_tracking_results
+    
+    # Handle detection format (list of detections)
+    elif isinstance(detections, list):
+        # Apply selected smoothing algorithm
+        if config.smoothing_algorithm == "observability":
+            return _apply_observability_smoothing(detections, config, tracker)
+        else:  # "window"
+            return _apply_window_smoothing(detections, config, tracker)
+    
+    # Fallback for unknown format
+    return detections
+
+
+def create_bbox_smoothing_tracker(config: BBoxSmoothingConfig) -> BBoxSmoothingTracker:
+    """
+    Create a new bbox smoothing tracker instance.
+    
+    Args:
+        config: Smoothing configuration
+        
+    Returns:
+        BBoxSmoothingTracker: New tracker instance
+    """
+    return BBoxSmoothingTracker(config)
+
+
+def create_default_smoothing_config(**overrides) -> BBoxSmoothingConfig:
+    """
+    Create default smoothing configuration with optional overrides.
+    
+    Args:
+        **overrides: Configuration overrides
+        
+    Returns:
+        BBoxSmoothingConfig: Configuration instance
+    """
+    return BBoxSmoothingConfig(**overrides) 

matrice_analytics/post_processing/utils/tracking_utils.py

@@ -0,0 +1,234 @@
+"""
+Tracking utilities for post-processing operations.
+"""
+
+from typing import List, Dict, Any, Tuple, Optional
+from collections import defaultdict
+
+from .geometry_utils import point_in_polygon, get_bbox_center, line_segments_intersect
+
+
+def track_objects_in_zone(results: Any, zone_polygon: List[List[float]]) -> Dict[str, Any]:
+    """
+    Track objects within a defined zone.
+    
+    Args:
+        results: Detection or tracking results
+        zone_polygon: Zone polygon coordinates [[x1,y1], [x2,y2], ...]
+        
+    Returns:
+        Dict with zone tracking information
+    """
+    zone_tracks = []
+    zone_polygon_tuples = [(p[0], p[1]) for p in zone_polygon]
+    
+    if isinstance(results, list):
+        # Detection format
+        for detection in results:
+            if _is_detection_in_zone(detection, zone_polygon_tuples):
+                bbox = detection.get("bounding_box", detection.get("bbox", {}))
+                center = get_bbox_center(bbox)
+                
+                zone_tracks.append({
+                    **detection,
+                    "in_zone": True,
+                    "zone_center": center
+                })
+    
+    elif isinstance(results, dict):
+        # Frame-based format
+        for frame_id, detections in results.items():
+            if isinstance(detections, list):
+                for detection in detections:
+                    if _is_detection_in_zone(detection, zone_polygon_tuples):
+                        bbox = detection.get("bounding_box", detection.get("bbox", {}))
+                        center = get_bbox_center(bbox)
+                        
+                        zone_tracks.append({
+                            **detection,
+                            "frame_id": frame_id,
+                            "in_zone": True,
+                            "zone_center": center
+                        })
+    
+    return {
+        "zone_tracks": zone_tracks,
+        "count_in_zone": len(zone_tracks)
+    }
+
+
+def detect_line_crossings(results: Dict[str, List[Dict]], line_points: List[List[float]], 
+                         track_history: Optional[Dict] = None) -> Dict[str, Any]:
+    """
+    Detect when tracked objects cross a virtual line.
+    
+    Args:
+        results: Tracking results in frame format
+        line_points: Line coordinates [[x1,y1], [x2,y2]]
+        track_history: Optional track position history
+        
+    Returns:
+        Dict with crossing information
+    """
+    if len(line_points) != 2:
+        return {"crossings": [], "total_crossings": 0}
+    
+    line_start = tuple(line_points[0])
+    line_end = tuple(line_points[1])
+    crossings = []
+    
+    if track_history is None:
+        track_history = {}
+    
+    for frame_id, detections in results.items():
+        if isinstance(detections, list):
+            for detection in detections:
+                track_id = detection.get("track_id")
+                if track_id is None:
+                    continue
+                
+                bbox = detection.get("bounding_box", detection.get("bbox"))
+                if not bbox:
+                    continue
+                
+                center = get_bbox_center(bbox)
+                
+                # Check for line crossing
+                if track_id in track_history:
+                    prev_pos = track_history[track_id][-1] if track_history[track_id] else None
+                    
+                    if prev_pos and line_segments_intersect(prev_pos, center, line_start, line_end):
+                        crossings.append({
+                            "track_id": track_id,
+                            "frame_id": frame_id,
+                            "position": center,
+                            "category": detection.get("category", "unknown"),
+                            "previous_position": prev_pos
+                        })
+                
+                # Update track history
+                if track_id not in track_history:
+                    track_history[track_id] = []
+                
+                track_history[track_id].append(center)
+                
+                # Keep only recent positions (last 10)
+                if len(track_history[track_id]) > 10:
+                    track_history[track_id] = track_history[track_id][-10:]
+    
+    return {
+        "crossings": crossings,
+        "total_crossings": len(crossings),
+        "track_history": track_history
+    }
+
+
+def analyze_track_movements(results: Dict[str, List[Dict]]) -> Dict[str, Any]:
+    """
+    Analyze movement patterns of tracked objects.
+    
+    Args:
+        results: Tracking results in frame format
+        
+    Returns:
+        Dict with movement analysis
+    """
+    track_paths = defaultdict(list)
+    track_stats = {}
+    
+    # Collect track positions
+    for frame_id, detections in results.items():
+        if isinstance(detections, list):
+            for detection in detections:
+                track_id = detection.get("track_id")
+                if track_id is None:
+                    continue
+                
+                bbox = detection.get("bounding_box", detection.get("bbox"))
+                if bbox:
+                    center = get_bbox_center(bbox)
+                    track_paths[track_id].append({
+                        "frame_id": frame_id,
+                        "position": center,
+                        "category": detection.get("category", "unknown")
+                    })
+    
+    # Analyze each track
+    for track_id, positions in track_paths.items():
+        if len(positions) < 2:
+            continue
+        
+        # Calculate total distance traveled
+        total_distance = 0
+        for i in range(1, len(positions)):
+            prev_pos = positions[i-1]["position"]
+            curr_pos = positions[i]["position"]
+            distance = ((curr_pos[0] - prev_pos[0])**2 + (curr_pos[1] - prev_pos[1])**2)**0.5
+            total_distance += distance
+        
+        # Calculate average speed (distance per frame)
+        avg_speed = total_distance / (len(positions) - 1) if len(positions) > 1 else 0
+        
+        track_stats[track_id] = {
+            "total_frames": len(positions),
+            "total_distance": total_distance,
+            "average_speed": avg_speed,
+            "start_position": positions[0]["position"],
+            "end_position": positions[-1]["position"],
+            "category": positions[0]["category"]
+        }
+    
+    return {
+        "track_paths": dict(track_paths),
+        "track_statistics": track_stats,
+        "total_tracks": len(track_paths)
+    }
+
+
+def filter_tracks_by_duration(results: Dict[str, List[Dict]], min_duration: int = 5) -> Dict[str, List[Dict]]:
+    """
+    Filter tracking results to only include tracks that appear for minimum duration.
+    
+    Args:
+        results: Tracking results in frame format
+        min_duration: Minimum number of frames a track must appear
+        
+    Returns:
+        Filtered tracking results
+    """
+    track_counts = defaultdict(int)
+    
+    # Count appearances per track
+    for frame_id, detections in results.items():
+        if isinstance(detections, list):
+            for detection in detections:
+                track_id = detection.get("track_id")
+                if track_id is not None:
+                    track_counts[track_id] += 1
+    
+    # Filter tracks that meet minimum duration
+    valid_tracks = {track_id for track_id, count in track_counts.items() if count >= min_duration}
+    
+    # Filter results
+    filtered_results = {}
+    for frame_id, detections in results.items():
+        filtered_detections = []
+        for detection in detections:
+            track_id = detection.get("track_id")
+            if track_id is None or track_id in valid_tracks:
+                filtered_detections.append(detection)
+        
+        if filtered_detections:
+            filtered_results[frame_id] = filtered_detections
+    
+    return filtered_results
+
+
+def _is_detection_in_zone(detection: Dict[str, Any], zone_polygon: List[Tuple[float, float]]) -> bool:
+    """Check if a detection is within a zone polygon."""
+    bbox = detection.get("bounding_box", detection.get("bbox"))
+    if not bbox:
+        return False
+    
+    center = get_bbox_center(bbox)
+    return point_in_polygon(center, zone_polygon)