eye-cv 1.0.0__py3-none-any.whl

eye/detection/tools/smoother.py

@@ -0,0 +1,123 @@
+import warnings
+from collections import defaultdict, deque
+from copy import deepcopy
+from typing import Optional
+
+import numpy as np
+
+from eye.detection.core import Detections
+from eye.utils.internal import EyeWarnings
+
+
+class DetectionsSmoother:
+    """
+    A utility class for smoothing detections over multiple frames in video tracking.
+    It maintains a history of detections for each track and provides smoothed
+    predictions based on these histories.
+
+    <video controls>
+        <source
+            src="https://media.roboflow.com/eye-detection-smoothing.mp4"
+            type="video/mp4">
+    </video>
+
+    !!! warning
+
+        - `DetectionsSmoother` requires the `tracker_id` for each detection. Refer to
+          Eye Trackers for information on integrating tracking into your inference pipeline.
+        - This class is not compatible with segmentation models.
+
+    Example:
+        ```python
+        import eye as sv
+
+        from ultralytics import YOLO
+
+        video_info = sv.VideoInfo.from_video_path(video_path=<SOURCE_FILE_PATH>)
+        frame_generator = sv.get_video_frames_generator(source_path=<SOURCE_FILE_PATH>)
+
+        model = YOLO(<MODEL_PATH>)
+        tracker = sv.ByteTrack(frame_rate=video_info.fps)
+        smoother = sv.DetectionsSmoother()
+
+        box_annotator = sv.BoxAnnotator()
+
+        with sv.VideoSink(<TARGET_FILE_PATH>, video_info=video_info) as sink:
+            for frame in frame_generator:
+                result = model(frame)[0]
+                detections = sv.Detections.from_ultralytics(result)
+                detections = tracker.update_with_detections(detections)
+                detections = smoother.update_with_detections(detections)
+
+                annotated_frame = box_annotator.annotate(frame.copy(), detections)
+                sink.write_frame(annotated_frame)
+        ```
+    """
+
+    def __init__(self, length: int = 5) -> None:
+        """
+        Args:
+            length (int): The maximum number of frames to consider for smoothing
+                detections. Defaults to 5.
+        """
+        self.tracks = defaultdict(lambda: deque(maxlen=length))
+
+    def update_with_detections(self, detections: Detections) -> Detections:
+        """
+        Updates the smoother with a new set of detections from a frame.
+
+        Args:
+            detections (Detections): The detections to add to the smoother.
+        """
+
+        if detections.tracker_id is None:
+            warnings.warn(
+                "Smoothing skipped. DetectionsSmoother requires tracker_id. Refer to "
+                "Eye trackers are required for smoothing. "
+                "Ensure tracker_id is available.",
+                category=EyeWarnings,
+            )
+            return detections
+
+        for detection_idx in range(len(detections)):
+            tracker_id = detections.tracker_id[detection_idx]
+
+            self.tracks[tracker_id].append(detections[detection_idx])
+
+        for track_id in self.tracks.keys():
+            if track_id not in detections.tracker_id:
+                self.tracks[track_id].append(None)
+
+        for track_id in list(self.tracks.keys()):
+            if all([d is None for d in self.tracks[track_id]]):
+                del self.tracks[track_id]
+
+        return self.get_smoothed_detections()
+
+    def get_track(self, track_id: int) -> Optional[Detections]:
+        track = self.tracks.get(track_id, None)
+        if track is None:
+            return None
+
+        track = [d for d in track if d is not None]
+        if len(track) == 0:
+            return None
+
+        ret = deepcopy(track[0])
+        ret.xyxy = np.mean([d.xyxy for d in track], axis=0)
+        ret.confidence = np.mean([d.confidence for d in track], axis=0)
+
+        return ret
+
+    def get_smoothed_detections(self) -> Detections:
+        tracked_detections = []
+        for track_id in self.tracks:
+            track = self.get_track(track_id)
+            if track is not None:
+                tracked_detections.append(track)
+
+        detections = Detections.merge(tracked_detections)
+        if len(detections) == 0:
+            detections.tracker_id = np.array([], dtype=int)
+
+        return detections

eye/detection/tools/smoothing.py

@@ -0,0 +1,179 @@
+"""Advanced jitter reduction and smoothing for tracking."""
+
+import numpy as np
+from filterpy.kalman import KalmanFilter
+from typing import Dict, Optional
+
+
+class KalmanSmoothing:
+    """Kalman filter for smooth tracking (jitter reduction).
+    
+    Use for: Smooth camera movement, reduce box jitter with predictive modeling.
+    """
+    
+    def __init__(
+        self,
+        process_noise: float = 0.01,
+        measurement_noise: float = 0.1
+    ):
+        """
+        Args:
+            process_noise: How much the object can move between frames (lower = smoother)
+            measurement_noise: Trust in measurements (lower = trust more)
+        """
+        self.process_noise = process_noise
+        self.measurement_noise = measurement_noise
+        self.filters: Dict[int, KalmanFilter] = {}
+    
+    def update(self, tracker_id: int, box: np.ndarray) -> np.ndarray:
+        """Smooth box using Kalman filter.
+        
+        Args:
+            tracker_id: Object ID
+            box: [x1, y1, x2, y2]
+        
+        Returns:
+            Smoothed box
+        """
+        if tracker_id not in self.filters:
+            self._init_filter(tracker_id, box)
+        
+        kf = self.filters[tracker_id]
+        
+        # Measurement: [x_center, y_center, width, height]
+        cx = (box[0] + box[2]) / 2
+        cy = (box[1] + box[3]) / 2
+        w = box[2] - box[0]
+        h = box[3] - box[1]
+        measurement = np.array([cx, cy, w, h])
+        
+        # Predict and update
+        kf.predict()
+        kf.update(measurement)
+        
+        # Get smoothed state
+        state = kf.x.flatten()
+        smoothed_cx, smoothed_cy, smoothed_w, smoothed_h = state[:4]
+        
+        # Convert back to xyxy
+        return np.array([
+            smoothed_cx - smoothed_w / 2,
+            smoothed_cy - smoothed_h / 2,
+            smoothed_cx + smoothed_w / 2,
+            smoothed_cy + smoothed_h / 2
+        ])
+    
+    def _init_filter(self, tracker_id: int, box: np.ndarray):
+        """Initialize Kalman filter for new track."""
+        kf = KalmanFilter(dim_x=8, dim_z=4)
+        
+        # State: [cx, cy, w, h, vcx, vcy, vw, vh]
+        cx = (box[0] + box[2]) / 2
+        cy = (box[1] + box[3]) / 2
+        w = box[2] - box[0]
+        h = box[3] - box[1]
+        kf.x = np.array([cx, cy, w, h, 0, 0, 0, 0]).reshape(8, 1)
+        
+        # State transition matrix
+        kf.F = np.eye(8)
+        kf.F[:4, 4:] = np.eye(4)
+        
+        # Measurement matrix
+        kf.H = np.zeros((4, 8))
+        kf.H[:4, :4] = np.eye(4)
+        
+        # Covariance matrices
+        kf.P *= 10
+        kf.R *= self.measurement_noise
+        kf.Q[4:, 4:] *= self.process_noise
+        
+        self.filters[tracker_id] = kf
+    
+    def reset(self, tracker_id: int = None):
+        """Reset filter(s)."""
+        if tracker_id is None:
+            self.filters.clear()
+        elif tracker_id in self.filters:
+            del self.filters[tracker_id]
+
+
+class ExponentialSmoothing:
+    """Exponential moving average for simple smoothing.
+    
+    Use for: Quick smoothing, less computational overhead than Kalman.
+    """
+    
+    def __init__(self, alpha: float = 0.3):
+        """
+        Args:
+            alpha: Smoothing factor (0-1)
+                   Lower = smoother but slower response
+                   Higher = faster response but less smooth
+        """
+        self.alpha = alpha
+        self.previous: Dict[int, np.ndarray] = {}
+    
+    def update(self, tracker_id: int, box: np.ndarray) -> np.ndarray:
+        """Smooth box using exponential moving average.
+        
+        Args:
+            tracker_id: Object ID
+            box: [x1, y1, x2, y2]
+        
+        Returns:
+            Smoothed box
+        """
+        if tracker_id not in self.previous:
+            self.previous[tracker_id] = box
+            return box
+        
+        # EMA: smoothed = alpha * new + (1 - alpha) * previous
+        smoothed = self.alpha * box + (1 - self.alpha) * self.previous[tracker_id]
+        self.previous[tracker_id] = smoothed
+        
+        return smoothed
+    
+    def reset(self, tracker_id: int = None):
+        """Reset smoothing history."""
+        if tracker_id is None:
+            self.previous.clear()
+        elif tracker_id in self.previous:
+            del self.previous[tracker_id]
+
+
+def smooth_detections(
+    detections,
+    smoother,
+    inplace: bool = False
+):
+    """Apply smoothing to all detections.
+    
+    Args:
+        detections: Detections object
+        smoother: KalmanSmoothing or ExponentialSmoothing instance
+        inplace: Modify in place (faster) or return new
+    
+    Returns:
+        Smoothed detections
+    """
+    if detections.tracker_id is None or len(detections) == 0:
+        return detections
+    
+    smoothed_boxes = np.empty_like(detections.xyxy)
+    
+    for i in range(len(detections)):
+        tid = detections.tracker_id[i]
+        smoothed_boxes[i] = smoother.update(tid, detections.xyxy[i])
+    
+    if inplace:
+        object.__setattr__(detections, 'xyxy', smoothed_boxes)
+        return detections
+    else:
+        from eye.detection.core import Detections
+        return Detections(
+            xyxy=smoothed_boxes,
+            confidence=detections.confidence,
+            class_id=detections.class_id,
+            tracker_id=detections.tracker_id,
+            data=detections.data
+        )

eye/detection/tools/smoothing_config.py

@@ -0,0 +1,202 @@
+"""Easy smoothing configuration with presets and recommendations."""
+
+from typing import Optional, Dict, Any
+from enum import Enum
+
+
+class SmoothingPreset(Enum):
+    """Predefined smoothing presets for common scenarios."""
+    NONE = "none"
+    LIGHT = "light"
+    MEDIUM = "medium"
+    HEAVY = "heavy"
+    ULTRA = "ultra"
+
+
+class SmoothingConfig:
+    """Easy-to-configure smoothing settings.
+    
+    Just pick a preset or customize!
+    
+    Example:
+        ```python
+        import eye as eye
+        
+        # Use preset
+        config = eye.SmoothingConfig(eye.SmoothingPreset.HEAVY)
+        
+        # Get recommendation
+        config = eye.SmoothingConfig.get_recommendation("highway")
+        
+        # Custom alpha
+        config = eye.SmoothingConfig(eye.SmoothingPreset.MEDIUM, custom_alpha=0.25)
+        
+        # Use with ExponentialSmoothing
+        smoother = eye.ExponentialSmoothing(alpha=config.alpha)
+        ```
+    """
+    
+    PRESETS = {
+        SmoothingPreset.NONE: {
+            'enabled': False,
+            'alpha': 1.0,
+            'description': 'No smoothing (raw detections)'
+        },
+        SmoothingPreset.LIGHT: {
+            'enabled': True,
+            'alpha': 0.5,
+            'description': 'Light smoothing (fast response, minimal jitter reduction)'
+        },
+        SmoothingPreset.MEDIUM: {
+            'enabled': True,
+            'alpha': 0.3,
+            'description': 'Medium smoothing (balanced - RECOMMENDED)'
+        },
+        SmoothingPreset.HEAVY: {
+            'enabled': True,
+            'alpha': 0.15,
+            'description': 'Heavy smoothing (slow response, max jitter reduction)'
+        },
+        SmoothingPreset.ULTRA: {
+            'enabled': True,
+            'alpha': 0.05,
+            'description': 'Ultra smooth (very slow response, cinematic look)'
+        }
+    }
+    
+    def __init__(
+        self,
+        preset: SmoothingPreset = SmoothingPreset.MEDIUM,
+        custom_alpha: Optional[float] = None
+    ):
+        """
+        Args:
+            preset: Preset smoothing level
+            custom_alpha: Override alpha (0-1, lower = smoother)
+        """
+        self.preset = preset
+        self.config = self.PRESETS[preset].copy()
+        
+        if custom_alpha is not None:
+            self.config['alpha'] = custom_alpha
+            self.config['enabled'] = True
+    
+    @property
+    def enabled(self) -> bool:
+        """Is smoothing enabled?"""
+        return self.config['enabled']
+    
+    @property
+    def alpha(self) -> float:
+        """Smoothing alpha value."""
+        return self.config['alpha']
+    
+    @property
+    def description(self) -> str:
+        """Description of current settings."""
+        return self.config['description']
+    
+    @classmethod
+    def get_recommendation(cls, use_case: str) -> 'SmoothingConfig':
+        """Get recommended smoothing for use case.
+        
+        Args:
+            use_case: Scenario name (highway, city, sports, surveillance, etc.)
+        
+        Returns:
+            SmoothingConfig with recommended preset
+        
+        Example:
+            >>> # For Dakar racing (fast vehicles)
+            >>> config = SmoothingConfig.get_recommendation("highway")
+            >>> smoother = eye.ExponentialSmoothing(alpha=config.alpha)
+        """
+        recommendations = {
+            # Traffic scenarios
+            'highway': SmoothingPreset.LIGHT,  # Fast vehicles (Dakar!)
+            'racing': SmoothingPreset.LIGHT,  # Racing vehicles
+            'dakar': SmoothingPreset.LIGHT,  # Dakar racing
+            'city': SmoothingPreset.MEDIUM,  # Mixed speeds
+            'parking': SmoothingPreset.HEAVY,  # Slow, stable
+            
+            # People scenarios
+            'pedestrians': SmoothingPreset.MEDIUM,  # Walking
+            'crowd': SmoothingPreset.HEAVY,  # Dense, slow
+            'running': SmoothingPreset.LIGHT,  # Fast motion
+            
+            # Sports
+            'sports': SmoothingPreset.LIGHT,  # Fast, dynamic
+            'soccer': SmoothingPreset.LIGHT,
+            'basketball': SmoothingPreset.LIGHT,
+            
+            # Surveillance
+            'surveillance': SmoothingPreset.HEAVY,  # Stable, professional
+            'security': SmoothingPreset.HEAVY,
+            
+            # Drones/aerial
+            'drone': SmoothingPreset.ULTRA,  # Camera shake
+            'aerial': SmoothingPreset.ULTRA,
+            
+            # Warehouse/retail
+            'warehouse': SmoothingPreset.MEDIUM,
+            'retail': SmoothingPreset.MEDIUM,
+            
+            # Default
+            'default': SmoothingPreset.MEDIUM
+        }
+        
+        preset = recommendations.get(use_case.lower(), SmoothingPreset.MEDIUM)
+        return cls(preset)
+    
+    def __repr__(self) -> str:
+        return f"SmoothingConfig(preset={self.preset.value}, alpha={self.alpha}, enabled={self.enabled})"
+
+
+def get_smoothing_guide() -> Dict[str, Any]:
+    """Get complete smoothing configuration guide.
+    
+    Returns:
+        Dictionary with presets, parameters, and tips
+    
+    Example:
+        >>> guide = eye.get_smoothing_guide()
+        >>> print(guide['tips'])
+    """
+    return {
+        'presets': {
+            preset.value: {
+                'alpha': config['alpha'],
+                'description': config['description'],
+                'use_for': _get_use_cases_for_preset(preset)
+            }
+            for preset, config in SmoothingConfig.PRESETS.items()
+        },
+        'parameters': {
+            'alpha': {
+                'range': '0.0 - 1.0',
+                'low': 'Very smooth, slow response (0.05-0.15)',
+                'medium': 'Balanced (0.2-0.4)',
+                'high': 'Fast response, less smooth (0.5-0.8)'
+            }
+        },
+        'tips': [
+            'Start with MEDIUM preset (alpha=0.3)',
+            'Lower alpha for more smoothing but slower tracking',
+            'Higher alpha for faster response but more jitter',
+            'Use ULTRA for drone/handheld footage',
+            'Use LIGHT for fast-moving objects (Dakar, sports)',
+            'Use HEAVY for surveillance/security cameras'
+        ]
+    }
+
+
+def _get_use_cases_for_preset(preset: SmoothingPreset) -> list:
+    """Get use cases for a preset."""
+    mapping = {
+        SmoothingPreset.NONE: ['Debugging', 'Raw data analysis'],
+        SmoothingPreset.LIGHT: ['Fast vehicles', 'Sports', 'Running', 'Highway', 'Dakar racing'],
+        SmoothingPreset.MEDIUM: ['City traffic', 'Pedestrians', 'Warehouse', 'General use'],
+        SmoothingPreset.HEAVY: ['Surveillance', 'Parking lots', 'Crowds', 'Security'],
+        SmoothingPreset.ULTRA: ['Drones', 'Handheld cameras', 'Cinematic footage']
+    }
+    return mapping.get(preset, [])