Reference for ultralytics/trackers/utils/kalman_filter.py
Note
This file is available at https://github.com/ultralytics/ultralytics/blob/main/ultralytics/trackers/utils/kalman_filter.py. If you spot a problem please help fix it by contributing a Pull Request 🛠️. Thank you 🙏!
ultralytics.trackers.utils.kalman_filter.KalmanFilterXYAH
For bytetrack. 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. The bounding box location (x, y, a, h) is taken as direct observation of the state space (linear observation model).
Source code in ultralytics/trackers/utils/kalman_filter.py
gating_distance
gating_distance(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. A suitable distance threshold can be
obtained from chi2inv95
. If only_position
is False, the chi-square distribution has 4 degrees of freedom,
otherwise 2.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
mean |
ndarray
|
Mean vector over the state distribution (8 dimensional). |
required |
covariance |
ndarray
|
Covariance of the state distribution (8x8 dimensional). |
required |
measurements |
ndarray
|
An Nx4 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. |
required |
only_position |
bool
|
If True, distance computation is done with respect to the bounding box center position only. Defaults to False. |
False
|
metric |
str
|
The metric to use for calculating the distance. Options are 'gaussian' for the squared Euclidean distance and 'maha' for the squared Mahalanobis distance. Defaults to 'maha'. |
'maha'
|
Returns:
Type | Description |
---|---|
ndarray
|
Returns an array of length N, where the i-th element contains the squared distance between
(mean, covariance) and |
Source code in ultralytics/trackers/utils/kalman_filter.py
initiate
Create track from unassociated measurement.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
measurement |
ndarray
|
Bounding box coordinates (x, y, a, h) with center position (x, y), aspect ratio a, and height h. |
required |
Returns:
Type | Description |
---|---|
tuple[ndarray, ndarray]
|
Returns the mean vector (8 dimensional) and covariance matrix (8x8 dimensional) of the new track. Unobserved velocities are initialized to 0 mean. |
Source code in ultralytics/trackers/utils/kalman_filter.py
multi_predict
Run Kalman filter prediction step (Vectorized version).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
mean |
ndarray
|
The Nx8 dimensional mean matrix of the object states at the previous time step. |
required |
covariance |
ndarray
|
The Nx8x8 covariance matrix of the object states at the previous time step. |
required |
Returns:
Type | Description |
---|---|
tuple[ndarray, ndarray]
|
Returns the mean vector and covariance matrix of the predicted state. Unobserved velocities are initialized to 0 mean. |
Source code in ultralytics/trackers/utils/kalman_filter.py
predict
Run Kalman filter prediction step.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
mean |
ndarray
|
The 8 dimensional mean vector of the object state at the previous time step. |
required |
covariance |
ndarray
|
The 8x8 dimensional covariance matrix of the object state at the previous time step. |
required |
Returns:
Type | Description |
---|---|
tuple[ndarray, ndarray]
|
Returns the mean vector and covariance matrix of the predicted state. Unobserved velocities are initialized to 0 mean. |
Source code in ultralytics/trackers/utils/kalman_filter.py
project
Project state distribution to measurement space.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
mean |
ndarray
|
The state's mean vector (8 dimensional array). |
required |
covariance |
ndarray
|
The state's covariance matrix (8x8 dimensional). |
required |
Returns:
Type | Description |
---|---|
tuple[ndarray, ndarray]
|
Returns the projected mean and covariance matrix of the given state estimate. |
Source code in ultralytics/trackers/utils/kalman_filter.py
update
Run Kalman filter correction step.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
mean |
ndarray
|
The predicted state's mean vector (8 dimensional). |
required |
covariance |
ndarray
|
The state's covariance matrix (8x8 dimensional). |
required |
measurement |
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. |
required |
Returns:
Type | Description |
---|---|
tuple[ndarray, ndarray]
|
Returns the measurement-corrected state distribution. |
Source code in ultralytics/trackers/utils/kalman_filter.py
ultralytics.trackers.utils.kalman_filter.KalmanFilterXYWH
Bases: KalmanFilterXYAH
For BoT-SORT. A simple Kalman filter for tracking bounding boxes in image space.
The 8-dimensional state space (x, y, w, h, vx, vy, vw, vh) contains the bounding box center position (x, y), width w, height h, and their respective velocities.
Object motion follows a constant velocity model. The bounding box location (x, y, w, h) is taken as direct observation of the state space (linear observation model).
Source code in ultralytics/trackers/utils/kalman_filter.py
initiate
Create track from unassociated measurement.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
measurement |
ndarray
|
Bounding box coordinates (x, y, w, h) with center position (x, y), width, and height. |
required |
Returns:
Type | Description |
---|---|
tuple[ndarray, ndarray]
|
Returns the mean vector (8 dimensional) and covariance matrix (8x8 dimensional) of the new track. Unobserved velocities are initialized to 0 mean. |
Source code in ultralytics/trackers/utils/kalman_filter.py
multi_predict
Run Kalman filter prediction step (Vectorized version).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
mean |
ndarray
|
The Nx8 dimensional mean matrix of the object states at the previous time step. |
required |
covariance |
ndarray
|
The Nx8x8 covariance matrix of the object states at the previous time step. |
required |
Returns:
Type | Description |
---|---|
tuple[ndarray, ndarray]
|
Returns the mean vector and covariance matrix of the predicted state. Unobserved velocities are initialized to 0 mean. |
Source code in ultralytics/trackers/utils/kalman_filter.py
predict
Run Kalman filter prediction step.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
mean |
ndarray
|
The 8 dimensional mean vector of the object state at the previous time step. |
required |
covariance |
ndarray
|
The 8x8 dimensional covariance matrix of the object state at the previous time step. |
required |
Returns:
Type | Description |
---|---|
tuple[ndarray, ndarray]
|
Returns the mean vector and covariance matrix of the predicted state. Unobserved velocities are initialized to 0 mean. |
Source code in ultralytics/trackers/utils/kalman_filter.py
project
Project state distribution to measurement space.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
mean |
ndarray
|
The state's mean vector (8 dimensional array). |
required |
covariance |
ndarray
|
The state's covariance matrix (8x8 dimensional). |
required |
Returns:
Type | Description |
---|---|
tuple[ndarray, ndarray]
|
Returns the projected mean and covariance matrix of the given state estimate. |
Source code in ultralytics/trackers/utils/kalman_filter.py
update
Run Kalman filter correction step.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
mean |
ndarray
|
The predicted state's mean vector (8 dimensional). |
required |
covariance |
ndarray
|
The state's covariance matrix (8x8 dimensional). |
required |
measurement |
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. |
required |
Returns:
Type | Description |
---|---|
tuple[ndarray, ndarray]
|
Returns the measurement-corrected state distribution. |