Struct KalmanBBox 

pub struct KalmanBBox { /* private fields */ }

Implementation of Discrete Kalman filter for bounding box tracking. State vector contains: center_x, center_y, width, height, velocity_cx, velocity_cy, velocity_w, velocity_h

Implementations

impl KalmanBBox

pub fn new( dt: f32, u_cx: f32, u_cy: f32, u_w: f32, u_h: f32, std_dev_a: f32, std_dev_m_cx: f32, std_dev_m_cy: f32, std_dev_m_w: f32, std_dev_m_h: f32, ) -> Self

Creates new KalmanBBox

Basic usage:

use kalman_rust::kalman::KalmanBBox;
let dt = 0.04; // Single cycle time (1/25 fps)
let u_cx = 1.0; // Control input for center X
let u_cy = 1.0; // Control input for center Y
let u_w = 0.0; // Control input for width
let u_h = 0.0; // Control input for height
let std_dev_a = 2.0; // Standart deviation of acceleration
let std_dev_m_cx = 0.1; // Standart deviation of measurement for center X
let std_dev_m_cy = 0.1; // Standart deviation of measurement for center Y
let std_dev_m_w = 0.1; // Standart deviation of measurement for width
let std_dev_m_h = 0.1; // Standart deviation of measurement for height
let mut kalman = KalmanBBox::new(dt, u_cx, u_cy, u_w, u_h, std_dev_a, std_dev_m_cx, std_dev_m_cy, std_dev_m_w, std_dev_m_h);

pub fn new_with_state( dt: f32, u_cx: f32, u_cy: f32, u_w: f32, u_h: f32, std_dev_a: f32, std_dev_m_cx: f32, std_dev_m_cy: f32, std_dev_m_w: f32, std_dev_m_h: f32, cx: f32, cy: f32, w: f32, h: f32, ) -> Self

Creates new KalmanBBox with initial state

Why is it needed to set the initial state to the actual first observed bounding box (sometimes)? When the first state vector is initialized with zeros, it assumes that the object is at the origin and the filter needs to estimate the position of the object from scratch, which can result in some initial inaccuracies. On the other hand, initializing the first state vector with the actual observed bounding box can provide a more accurate estimate from the beginning, which can improve the overall tracking performance of the filter

Basic usage:

use kalman_rust::kalman::KalmanBBox;
let dt = 0.04; // Single cycle time (1/25 fps)
let u_cx = 1.0; // Control input for center X
let u_cy = 1.0; // Control input for center Y
let u_w = 0.0; // Control input for width
let u_h = 0.0; // Control input for height
let std_dev_a = 2.0; // Standart deviation of acceleration
let std_dev_m_cx = 0.1; // Standart deviation of measurement for center X
let std_dev_m_cy = 0.1; // Standart deviation of measurement for center Y
let std_dev_m_w = 0.1; // Standart deviation of measurement for width
let std_dev_m_h = 0.1; // Standart deviation of measurement for height
let i_cx = 100.0; // Initial center X
let i_cy = 50.0; // Initial center Y
let i_w = 40.0; // Initial width
let i_h = 80.0; // Initial height
let mut kalman = KalmanBBox::new_with_state(dt, u_cx, u_cy, u_w, u_h, std_dev_a, std_dev_m_cx, std_dev_m_cy, std_dev_m_w, std_dev_m_h, i_cx, i_cy, i_w, i_h);

pub fn predict(&mut self)

Projects the state and the error covariance ahead Mutates the state vector and the error covariance matrix

Basic usage:

use kalman_rust::kalman::KalmanBBox;
let dt = 0.04;
let mut kalman = KalmanBBox::new(dt, 1.0, 1.0, 0.0, 0.0, 2.0, 0.1, 0.1, 0.1, 0.1);
let measurements = vec![(100.0, 50.0, 40.0, 80.0), (102.0, 52.0, 41.0, 81.0)];
for _ in measurements.iter() {
    // get measurement
    kalman.predict();
    // then do update
}

pub fn update( &mut self, _z_cx: f32, _z_cy: f32, _z_w: f32, _z_h: f32, ) -> Result<(), KalmanBBoxError>

Computes the Kalman gain and then updates the state vector and the error covariance matrix Mutates the state vector and the error covariance matrix.

Basic usage:

use kalman_rust::kalman::KalmanBBox;
let dt = 0.04;
let mut kalman = KalmanBBox::new(dt, 1.0, 1.0, 0.0, 0.0, 2.0, 0.1, 0.1, 0.1, 0.1);
let measurements = vec![(100.0, 50.0, 40.0, 80.0), (102.0, 52.0, 41.0, 81.0)];
for (cx, cy, w, h) in measurements.iter() {
    kalman.predict();
    kalman.update(*cx, *cy, *w, *h).unwrap();
}

pub fn get_state(&self) -> (f32, f32, f32, f32)

Returns the current state (only cx, cy, w, h - not velocities)

pub fn get_velocity(&self) -> (f32, f32, f32, f32)

Returns the current velocity (only vx, vy, vw, vh)

pub fn get_predicted_state(&self) -> (f32, f32, f32, f32)

Returns prediction without mutating the state vector and the error covariance matrix

pub fn get_position_uncertainty(&self) -> f32

Returns position uncertainty from P matrix (for center coordinates)

pub fn get_vector_state(&self) -> SVector<f32, 8>

Returns the current state (full 8-element vector)

pub fn mahalanobis_distance_squared( &self, z_cx: f32, z_cy: f32, z_w: f32, z_h: f32, ) -> Result<f32, KalmanBBoxError>

Computes the squared Mahalanobis distance between measurement and predicted state Ref.: Eq.(66)

This is useful for data association in multi-object tracking. A detection passes the gate if mahalanobis_distance_squared < threshold Common threshold for 4 DOF at 95% confidence: 9.488

pub fn mahalanobis_distance( &self, z_cx: f32, z_cy: f32, z_w: f32, z_h: f32, ) -> Result<f32, KalmanBBoxError>

Computes the Mahalanobis distance (square root of squared distance) Ref.: Eq.(67)

pub fn get_innovation_covariance(&self) -> SMatrix<f32, 4, 4>

Returns the innovation covariance matrix S Ref.: Eq.(65)

S = H * P * H^T + R

pub fn gating_check( &self, z_cx: f32, z_cy: f32, z_w: f32, z_h: f32, threshold: f32, ) -> bool

Checks if a measurement passes the gating threshold Ref.: Eq.(70)

Common thresholds for alpha = 0.95:

• 4 DOF (bounding box): 9.488
• 2 DOF (position only): 5.991

Trait Implementations

impl Clone for KalmanBBox

fn clone(&self) -> KalmanBBox

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for KalmanBBox

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.