matrice-analytics 0.1.60__py3-none-any.whl

matrice_analytics/post_processing/advanced_tracker/base.py

@@ -0,0 +1,99 @@
+"""
+Base tracking classes for advanced tracker implementation.
+
+This module provides the foundational classes for object tracking,
+including track states and base track functionality.
+"""
+
+from collections import OrderedDict
+from typing import Any
+import numpy as np
+
+
+class TrackState:
+    """
+    Enumeration class representing the possible states of an object being tracked.
+
+    Attributes:
+        New (int): State when the object is newly detected.
+        Tracked (int): State when the object is successfully tracked in subsequent frames.
+        Lost (int): State when the object is no longer tracked.
+        Removed (int): State when the object is removed from tracking.
+    """
+
+    New = 0
+    Tracked = 1
+    Lost = 2
+    Removed = 3
+
+
+class BaseTrack:
+    """
+    Base class for object tracking, providing foundational attributes and methods.
+
+    Attributes:
+        _count (int): Class-level counter for unique track IDs.
+        track_id (int): Unique identifier for the track.
+        is_activated (bool): Flag indicating whether the track is currently active.
+        state (TrackState): Current state of the track.
+        history (OrderedDict): Ordered history of the track's states.
+        features (list): List of features extracted from the object for tracking.
+        curr_feature (Any): The current feature of the object being tracked.
+        score (float): The confidence score of the tracking.
+        start_frame (int): The frame number where tracking started.
+        frame_id (int): The most recent frame ID processed by the track.
+        time_since_update (int): Frames passed since the last update.
+        location (tuple): The location of the object in the context of multi-camera tracking.
+    """
+
+    _count = 0
+
+    def __init__(self):
+        """Initialize a new track with a unique ID and foundational tracking attributes."""
+        self.track_id = 0
+        self.is_activated = False
+        self.state = TrackState.New
+        self.history = OrderedDict()
+        self.features = []
+        self.curr_feature = None
+        self.score = 0
+        self.start_frame = 0
+        self.frame_id = 0
+        self.time_since_update = 0
+        self.location = (np.inf, np.inf)
+
+    @property
+    def end_frame(self) -> int:
+        """Return the ID of the most recent frame where the object was tracked."""
+        return self.frame_id
+
+    @staticmethod
+    def next_id() -> int:
+        """Increment and return the next unique global track ID for object tracking."""
+        BaseTrack._count += 1
+        return BaseTrack._count
+
+    def activate(self, *args: Any) -> None:
+        """Activate the track with provided arguments, initializing necessary attributes for tracking."""
+        raise NotImplementedError
+
+    def predict(self) -> None:
+        """Predict the next state of the track based on the current state and tracking model."""
+        raise NotImplementedError
+
+    def update(self, *args: Any, **kwargs: Any) -> None:
+        """Update the track with new observations and data, modifying its state and attributes accordingly."""
+        raise NotImplementedError
+
+    def mark_lost(self) -> None:
+        """Mark the track as lost by updating its state to TrackState.Lost."""
+        self.state = TrackState.Lost
+
+    def mark_removed(self) -> None:
+        """Mark the track as removed by setting its state to TrackState.Removed."""
+        self.state = TrackState.Removed
+
+    @staticmethod
+    def reset_id() -> None:
+        """Reset the global track ID counter to its initial value."""
+        BaseTrack._count = 0 

matrice_analytics/post_processing/advanced_tracker/config.py

@@ -0,0 +1,77 @@
+"""
+Configuration classes for advanced tracker.
+
+This module provides configuration classes for the advanced tracker,
+including parameters for tracking algorithms and thresholds.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class TrackerConfig:
+    """
+    Configuration for advanced tracker.
+    
+    This class contains all the parameters needed to configure the tracking algorithm,
+    including thresholds, buffer sizes, and algorithm-specific settings.
+    """
+    
+    # Tracking thresholds
+    track_high_thresh: float = 0.7
+    track_low_thresh: float = 0.1
+    new_track_thresh: float = 0.7
+    match_thresh: float = 0.8
+    
+    # Buffer settings
+    track_buffer: int = 600
+    max_time_lost: int = 600
+    
+    # Algorithm settings
+    fuse_score: bool = True
+    enable_gmc: bool = True
+    gmc_method: str = "sparseOptFlow"  # "orb", "sift", "ecc", "sparseOptFlow", "none"
+    gmc_downscale: int = 2
+    
+    # Frame rate (used for max_time_lost calculation)
+    frame_rate: int = 30
+    
+    # Output format settings
+    output_format: str = "tracking"  # "tracking" or "detection"
+    
+    # Additional settings
+    enable_smoothing: bool = True
+    smoothing_algorithm: str = "observability"  # "window" or "observability"
+    smoothing_window_size: int = 20
+    smoothing_cooldown_frames: int = 5
+    
+    def __post_init__(self):
+        """Validate configuration parameters."""
+        if not 0.0 <= self.track_high_thresh <= 1.0:
+            raise ValueError(f"track_high_thresh must be between 0.0 and 1.0, got {self.track_high_thresh}")
+        
+        if not 0.0 <= self.track_low_thresh <= 1.0:
+            raise ValueError(f"track_low_thresh must be between 0.0 and 1.0, got {self.track_low_thresh}")
+        
+        if not 0.0 <= self.new_track_thresh <= 1.0:
+            raise ValueError(f"new_track_thresh must be between 0.0 and 1.0, got {self.new_track_thresh}")
+        
+        if not 0.0 <= self.match_thresh <= 1.0:
+            raise ValueError(f"match_thresh must be between 0.0 and 1.0, got {self.match_thresh}")
+        
+        if self.track_buffer <= 0:
+            raise ValueError(f"track_buffer must be positive, got {self.track_buffer}")
+        
+        if self.frame_rate <= 0:
+            raise ValueError(f"frame_rate must be positive, got {self.frame_rate}")
+        
+        if self.gmc_method not in ["orb", "sift", "ecc", "sparseOptFlow", "none"]:
+            raise ValueError(f"Invalid gmc_method: {self.gmc_method}")
+        
+        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) 

matrice_analytics/post_processing/advanced_tracker/kalman_filter.py

@@ -0,0 +1,370 @@
+"""
+Kalman filter implementation for advanced tracker.
+
+This module provides Kalman filter implementations for tracking bounding boxes,
+including both XYAH and XYWH formats.
+"""
+
+import numpy as np
+import scipy.linalg
+
+
+class KalmanFilterXYAH:
+    """
+    A KalmanFilterXYAH class for tracking bounding boxes in image space using a Kalman filter.
+
+    Implements a simple Kalman filter for tracking bounding boxes in image space. The 8-dimensional state space
+    (x, y, a, h, vx, vy, va, vh) contains the bounding box center position (x, y), aspect ratio a, height h, and their
+    respective velocities. Object motion follows a constant velocity model, and bounding box location (x, y, a, h) is
+    taken as a direct observation of the state space (linear observation model).
+    """
+
+    def __init__(self):
+        """
+        Initialize Kalman filter model matrices with motion and observation uncertainty weights.
+
+        The Kalman filter is initialized with an 8-dimensional state space (x, y, a, h, vx, vy, va, vh), where (x, y)
+        represents the bounding box center position, 'a' is the aspect ratio, 'h' is the height, and their respective
+        velocities are (vx, vy, va, vh). The filter uses a constant velocity model for object motion and a linear
+        observation model for bounding box location.
+        """
+        ndim, dt = 4, 1.0
+
+        # Create Kalman filter model matrices
+        self._motion_mat = np.eye(2 * ndim, 2 * ndim)
+        for i in range(ndim):
+            self._motion_mat[i, ndim + i] = dt
+        self._update_mat = np.eye(ndim, 2 * ndim)
+
+        # Motion and observation uncertainty are chosen relative to the current state estimate
+        self._std_weight_position = 1.0 / 20
+        self._std_weight_velocity = 1.0 / 160
+
+    def initiate(self, measurement: np.ndarray):
+        """
+        Create a track from an unassociated measurement.
+
+        Args:
+            measurement (np.ndarray): Bounding box coordinates (x, y, a, h) with center position (x, y), aspect ratio a,
+                and height h.
+
+        Returns:
+            mean (np.ndarray): Mean vector (8-dimensional) of the new track. Unobserved velocities are initialized to 0 mean.
+            covariance (np.ndarray): Covariance matrix (8x8 dimensional) of the new track.
+        """
+        mean_pos = measurement
+        mean_vel = np.zeros_like(mean_pos)
+        mean = np.r_[mean_pos, mean_vel]
+
+        std = [
+            2 * self._std_weight_position * measurement[3],
+            2 * self._std_weight_position * measurement[3],
+            1e-2,
+            2 * self._std_weight_position * measurement[3],
+            10 * self._std_weight_velocity * measurement[3],
+            10 * self._std_weight_velocity * measurement[3],
+            1e-5,
+            10 * self._std_weight_velocity * measurement[3],
+        ]
+        covariance = np.diag(np.square(std))
+        return mean, covariance
+
+    def predict(self, mean: np.ndarray, covariance: np.ndarray):
+        """
+        Run Kalman filter prediction step.
+
+        Args:
+            mean (np.ndarray): The 8-dimensional mean vector of the object state at the previous time step.
+            covariance (np.ndarray): The 8x8-dimensional covariance matrix of the object state at the previous time step.
+
+        Returns:
+            mean (np.ndarray): Mean vector of the predicted state. Unobserved velocities are initialized to 0 mean.
+            covariance (np.ndarray): Covariance matrix of the predicted state.
+        """
+        std_pos = [
+            self._std_weight_position * mean[3],
+            self._std_weight_position * mean[3],
+            1e-2,
+            self._std_weight_position * mean[3],
+        ]
+        std_vel = [
+            self._std_weight_velocity * mean[3],
+            self._std_weight_velocity * mean[3],
+            1e-5,
+            self._std_weight_velocity * mean[3],
+        ]
+        motion_cov = np.diag(np.square(np.r_[std_pos, std_vel]))
+
+        mean = np.dot(mean, self._motion_mat.T)
+        covariance = np.linalg.multi_dot((self._motion_mat, covariance, self._motion_mat.T)) + motion_cov
+
+        return mean, covariance
+
+    def project(self, mean: np.ndarray, covariance: np.ndarray):
+        """
+        Project state distribution to measurement space.
+
+        Args:
+            mean (np.ndarray): The state's mean vector (8 dimensional array).
+            covariance (np.ndarray): The state's covariance matrix (8x8 dimensional).
+
+        Returns:
+            mean (np.ndarray): Projected mean of the given state estimate.
+            covariance (np.ndarray): Projected covariance matrix of the given state estimate.
+        """
+        std = [
+            self._std_weight_position * mean[3],
+            self._std_weight_position * mean[3],
+            1e-1,
+            self._std_weight_position * mean[3],
+        ]
+        innovation_cov = np.diag(np.square(std))
+
+        mean = np.dot(self._update_mat, mean)
+        covariance = np.linalg.multi_dot((self._update_mat, covariance, self._update_mat.T))
+        return mean, covariance + innovation_cov
+
+    def multi_predict(self, mean: np.ndarray, covariance: np.ndarray):
+        """
+        Run Kalman filter prediction step for multiple object states (Vectorized version).
+
+        Args:
+            mean (np.ndarray): The Nx8 dimensional mean matrix of the object states at the previous time step.
+            covariance (np.ndarray): The Nx8x8 covariance matrix of the object states at the previous time step.
+
+        Returns:
+            mean (np.ndarray): Mean matrix of the predicted states with shape (N, 8).
+            covariance (np.ndarray): Covariance matrix of the predicted states with shape (N, 8, 8).
+        """
+        std_pos = [
+            self._std_weight_position * mean[:, 3],
+            self._std_weight_position * mean[:, 3],
+            1e-2 * np.ones_like(mean[:, 3]),
+            self._std_weight_position * mean[:, 3],
+        ]
+        std_vel = [
+            self._std_weight_velocity * mean[:, 3],
+            self._std_weight_velocity * mean[:, 3],
+            1e-5 * np.ones_like(mean[:, 3]),
+            self._std_weight_velocity * mean[:, 3],
+        ]
+        sqr = np.square(np.r_[std_pos, std_vel]).T
+
+        motion_cov = [np.diag(sqr[i]) for i in range(len(mean))]
+        motion_cov = np.asarray(motion_cov)
+
+        mean = np.dot(mean, self._motion_mat.T)
+        left = np.dot(self._motion_mat, covariance).transpose((1, 0, 2))
+        covariance = np.dot(left, self._motion_mat.T) + motion_cov
+
+        return mean, covariance
+
+    def update(self, mean: np.ndarray, covariance: np.ndarray, measurement: np.ndarray):
+        """
+        Run Kalman filter correction step.
+
+        Args:
+            mean (np.ndarray): The predicted state's mean vector (8 dimensional).
+            covariance (np.ndarray): The state's covariance matrix (8x8 dimensional).
+            measurement (np.ndarray): The 4 dimensional measurement vector (x, y, a, h), where (x, y) is the center
+                position, a the aspect ratio, and h the height of the bounding box.
+
+        Returns:
+            new_mean (np.ndarray): Measurement-corrected state mean.
+            new_covariance (np.ndarray): Measurement-corrected state covariance.
+        """
+        projected_mean, projected_cov = self.project(mean, covariance)
+
+        chol_factor, lower = scipy.linalg.cho_factor(projected_cov, lower=True, check_finite=False)
+        kalman_gain = scipy.linalg.cho_solve(
+            (chol_factor, lower), np.dot(covariance, self._update_mat.T).T, check_finite=False
+        ).T
+        innovation = measurement - projected_mean
+
+        new_mean = mean + np.dot(innovation, kalman_gain.T)
+        new_covariance = covariance - np.linalg.multi_dot((kalman_gain, projected_cov, kalman_gain.T))
+        return new_mean, new_covariance
+
+    def gating_distance(
+        self,
+        mean: np.ndarray,
+        covariance: np.ndarray,
+        measurements: np.ndarray,
+        only_position: bool = False,
+        metric: str = "maha",
+    ) -> np.ndarray:
+        """
+        Compute gating distance between state distribution and measurements.
+
+        Args:
+            mean (np.ndarray): Mean vector over the state distribution (8 dimensional).
+            covariance (np.ndarray): Covariance of the state distribution (8x8 dimensional).
+            measurements (np.ndarray): An (N, 4) matrix of N measurements, each in format (x, y, a, h) where (x, y) is the
+                bounding box center position, a the aspect ratio, and h the height.
+            only_position (bool, optional): If True, distance computation is done with respect to box center position only.
+            metric (str, optional): The metric to use for calculating the distance. Options are 'gaussian' for the squared
+                Euclidean distance and 'maha' for the squared Mahalanobis distance.
+
+        Returns:
+            (np.ndarray): Returns an array of length N, where the i-th element contains the squared distance between
+                (mean, covariance) and `measurements[i]`.
+        """
+        mean, covariance = self.project(mean, covariance)
+        if only_position:
+            mean, covariance = mean[:2], covariance[:2, :2]
+            measurements = measurements[:, :2]
+
+        d = measurements - mean
+        if metric == "gaussian":
+            return np.sum(d * d, axis=1)
+        elif metric == "maha":
+            cholesky_factor = np.linalg.cholesky(covariance)
+            z = scipy.linalg.solve_triangular(cholesky_factor, d.T, lower=True, check_finite=False, overwrite_b=True)
+            return np.sum(z * z, axis=0)  # square maha
+        else:
+            raise ValueError("Invalid distance metric")
+
+
+class KalmanFilterXYWH(KalmanFilterXYAH):
+    """
+    A KalmanFilterXYWH class for tracking bounding boxes in image space using a Kalman filter.
+
+    Implements a Kalman filter for tracking bounding boxes with state space (x, y, w, h, vx, vy, vw, vh), where
+    (x, y) is the center position, w is the width, h is the height, and vx, vy, vw, vh are their respective velocities.
+    The object motion follows a constant velocity model, and the bounding box location (x, y, w, h) is taken as a direct
+    observation of the state space (linear observation model).
+    """
+
+    def initiate(self, measurement: np.ndarray):
+        """
+        Create track from unassociated measurement.
+
+        Args:
+            measurement (np.ndarray): Bounding box coordinates (x, y, w, h) with center position (x, y), width, and height.
+
+        Returns:
+            mean (np.ndarray): Mean vector (8 dimensional) of the new track. Unobserved velocities are initialized to 0 mean.
+            covariance (np.ndarray): Covariance matrix (8x8 dimensional) of the new track.
+        """
+        mean_pos = measurement
+        mean_vel = np.zeros_like(mean_pos)
+        mean = np.r_[mean_pos, mean_vel]
+
+        std = [
+            2 * self._std_weight_position * measurement[2],
+            2 * self._std_weight_position * measurement[3],
+            2 * self._std_weight_position * measurement[2],
+            2 * self._std_weight_position * measurement[3],
+            10 * self._std_weight_velocity * measurement[2],
+            10 * self._std_weight_velocity * measurement[3],
+            10 * self._std_weight_velocity * measurement[2],
+            10 * self._std_weight_velocity * measurement[3],
+        ]
+        covariance = np.diag(np.square(std))
+        return mean, covariance
+
+    def predict(self, mean: np.ndarray, covariance: np.ndarray):
+        """
+        Run Kalman filter prediction step.
+
+        Args:
+            mean (np.ndarray): The 8-dimensional mean vector of the object state at the previous time step.
+            covariance (np.ndarray): The 8x8-dimensional covariance matrix of the object state at the previous time step.
+
+        Returns:
+            mean (np.ndarray): Mean vector of the predicted state. Unobserved velocities are initialized to 0 mean.
+            covariance (np.ndarray): Covariance matrix of the predicted state.
+        """
+        std_pos = [
+            self._std_weight_position * mean[2],
+            self._std_weight_position * mean[3],
+            self._std_weight_position * mean[2],
+            self._std_weight_position * mean[3],
+        ]
+        std_vel = [
+            self._std_weight_velocity * mean[2],
+            self._std_weight_velocity * mean[3],
+            self._std_weight_velocity * mean[2],
+            self._std_weight_velocity * mean[3],
+        ]
+        motion_cov = np.diag(np.square(np.r_[std_pos, std_vel]))
+
+        mean = np.dot(mean, self._motion_mat.T)
+        covariance = np.linalg.multi_dot((self._motion_mat, covariance, self._motion_mat.T)) + motion_cov
+
+        return mean, covariance
+
+    def project(self, mean: np.ndarray, covariance: np.ndarray):
+        """
+        Project state distribution to measurement space.
+
+        Args:
+            mean (np.ndarray): The state's mean vector (8 dimensional array).
+            covariance (np.ndarray): The state's covariance matrix (8x8 dimensional).
+
+        Returns:
+            mean (np.ndarray): Projected mean of the given state estimate.
+            covariance (np.ndarray): Projected covariance matrix of the given state estimate.
+        """
+        std = [
+            self._std_weight_position * mean[2],
+            self._std_weight_position * mean[3],
+            self._std_weight_position * mean[2],
+            self._std_weight_position * mean[3],
+        ]
+        innovation_cov = np.diag(np.square(std))
+
+        mean = np.dot(self._update_mat, mean)
+        covariance = np.linalg.multi_dot((self._update_mat, covariance, self._update_mat.T))
+        return mean, covariance + innovation_cov
+
+    def multi_predict(self, mean: np.ndarray, covariance: np.ndarray):
+        """
+        Run Kalman filter prediction step (Vectorized version).
+
+        Args:
+            mean (np.ndarray): The Nx8 dimensional mean matrix of the object states at the previous time step.
+            covariance (np.ndarray): The Nx8x8 covariance matrix of the object states at the previous time step.
+
+        Returns:
+            mean (np.ndarray): Mean matrix of the predicted states with shape (N, 8).
+            covariance (np.ndarray): Covariance matrix of the predicted states with shape (N, 8, 8).
+        """
+        std_pos = [
+            self._std_weight_position * mean[:, 2],
+            self._std_weight_position * mean[:, 3],
+            self._std_weight_position * mean[:, 2],
+            self._std_weight_position * mean[:, 3],
+        ]
+        std_vel = [
+            self._std_weight_velocity * mean[:, 2],
+            self._std_weight_velocity * mean[:, 3],
+            self._std_weight_velocity * mean[:, 2],
+            self._std_weight_velocity * mean[:, 3],
+        ]
+        sqr = np.square(np.r_[std_pos, std_vel]).T
+
+        motion_cov = [np.diag(sqr[i]) for i in range(len(mean))]
+        motion_cov = np.asarray(motion_cov)
+
+        mean = np.dot(mean, self._motion_mat.T)
+        left = np.dot(self._motion_mat, covariance).transpose((1, 0, 2))
+        covariance = np.dot(left, self._motion_mat.T) + motion_cov
+
+        return mean, covariance
+
+    def update(self, mean: np.ndarray, covariance: np.ndarray, measurement: np.ndarray):
+        """
+        Run Kalman filter correction step.
+
+        Args:
+            mean (np.ndarray): The predicted state's mean vector (8 dimensional).
+            covariance (np.ndarray): The state's covariance matrix (8x8 dimensional).
+            measurement (np.ndarray): The 4 dimensional measurement vector (x, y, w, h), where (x, y) is the center
+                position, w the width, and h the height of the bounding box.
+
+        Returns:
+            new_mean (np.ndarray): Measurement-corrected state mean.
+            new_covariance (np.ndarray): Measurement-corrected state covariance.
+        """
+        return super().update(mean, covariance, measurement)