Struct ConstantVelocityXYAHModel2 

pub struct ConstantVelocityXYAHModel2<R>
where
    R: RealField,
    DefaultAllocator: Allocator<U8, U8> + Allocator<U8>,
{
    pub mean: SVector<R, 8>,
    pub std_weight_position: R,
    pub std_weight_velocity: R,
    pub update_factor: R,
    pub covariance: OMatrix<R, U8, U8>,
    /* private fields */
}

Constant-velocity Kalman filter for tracking a bounding box in XYAH space.

The state vector is [x, y, a, h, ẋ, ẏ, ȧ, ḣ] (8 dimensions):

Component	Meaning
x	Centre x coordinate
y	Centre y coordinate
a	Aspect ratio (width / height), kept > 0 by a small epsilon floor
h	Height
ẋ, ẏ, ȧ, ḣ	First derivatives of the position components

Measurements arriving via update are in 4-dimensional XYAH space (no velocity), projected from the 8-D state by the observation matrix H. The filter uses a scale-adaptive process-noise covariance: noise magnitude scales proportionally with the box height h, so fast-moving large objects tolerate wider uncertainty than small static ones.

This is the same Kalman filter parameterisation used in the original ByteTrack paper (Zhang et al., 2022).

Fields

mean: SVector<R, 8>

Current state estimate: [x, y, a, h, ẋ, ẏ, ȧ, ḣ].

std_weight_position: R

Scale factor for position noise (1/20 by default). Process noise for position components is std_weight_position * h.

std_weight_velocity: R

Scale factor for velocity noise (1/160 by default). Process noise for velocity components is std_weight_velocity * h.

update_factor: R

Measurement-to-innovation scaling applied in update. Set via ByteTrackBuilder::track_update. Values in (0, 1]; lower → smoother (trusts prediction more).

covariance: OMatrix<R, U8, U8>

Current state covariance matrix P (8×8). Grows on each predict and shrinks on each update.

Implementations

impl<R> ConstantVelocityXYAHModel2<R>

where R: RealField + Copy,

pub fn new(measurement: &[R; 4], update_factor: R) -> Self

Initialise the filter from the first observation.

measurement is [x, y, a, h] in XYAH space. Velocity components are initialised to zero. The initial covariance is set proportionally to the box height so larger boxes start with wider uncertainty.

update_factor is stored and applied as a measurement gain in update.

pub fn predict(&mut self)

Advance the filter by one time step with no measurement.

Applies the constant-velocity motion model (mean' = F * mean, cov' = F * cov * Fᵀ + Q) using a scale-adaptive process-noise covariance Q proportional to the current box height. Called once per frame for every active tracklet before the assignment step.

pub fn project(&self) -> (OMatrix<R, U4, U1>, OMatrix<R, U4, U4>)

Project the 8-D state into 4-D measurement space.

Returns (projected_mean, projected_covariance) — the expected measurement and its uncertainty under the current state estimate. Used by update and by gating_distance.

pub fn update(&mut self, measurement: &[R; 4])

Correct the state estimate with a new measurement.

measurement is [x, y, a, h] in XYAH space, as produced by xyxy_to_xyah in the ByteTrack update loop.

The Kalman gain is computed via Cholesky decomposition of the projected covariance. If the decomposition fails (degenerate covariance) the update is silently skipped and the prior state is preserved.

The innovation is scaled by self.update_factor before being applied, which effectively attenuates the correction — lower values produce smoother trajectories at the cost of slower response to abrupt motion.

pub fn gating_distance( &self, measurements: &OMatrix<R, Dyn, U4>, only_position: bool, metric: GatingDistanceMetric, ) -> DVector<R>

Compute per-measurement gating distances from the current state.

Returns a vector of one scalar per row in measurements. Each scalar is either the squared Euclidean distance (GatingDistanceMetric::Gaussian) or the Mahalanobis distance (GatingDistanceMetric::Mahalanobis) from the projected state mean to that measurement.

only_position restricts the comparison to the first two components (x, y), ignoring aspect and height.

Not used by the current ByteTrack integration (which gates via IoU); exposed for future association strategies.

Trait Implementations

impl<R> Clone for ConstantVelocityXYAHModel2<R>

where R: RealField + Clone, DefaultAllocator: Allocator<U8, U8> + Allocator<U8>,

fn clone(&self) -> ConstantVelocityXYAHModel2<R>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<R> Debug for ConstantVelocityXYAHModel2<R>

where R: RealField + Debug, DefaultAllocator: Allocator<U8, U8> + Allocator<U8>,

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

Formats the value using the given formatter.