sportslabkit.motion_model#

Subpackages#

Overview#

Classes#

BaseMotionModel

Abstract base class for motion models.

ExponentialMovingAverage

Exponential Moving Average (EMA) motion model for object tracking.

KalmanFilter

Abstract base class for motion models.
Function#

tune_motion_model(motion_model_class, detections, ground_truth_positions, n_trials, hparam_search_space, metric, verbose, return_study)

-

Classes#

class sportslabkit.motion_model.BaseMotionModel(is_multi_target=False)[source]#

Bases: abc.ABC

Abstract base class for motion models.

This class defines a common interface for all motion models. Derived classes should implement the update, and predict methods. MotionModels are procedural and stateless. The state of tracklet is managed by the Tracklet class. The tracklet must have the required observations and states for the motion model to work. If the tracklet doesn’t have the required observations or states, the motion model will raise an error and tell the user which observations or states are missing.

Overview

Methods#

predict(observations, states)

abc Compute the next internal state and prediction based on the current observation and internal state.

from_config(config)

class Initialize a motion model instance from a configuration dictionary.

Members

hparam_search_space :dict[str, type]#
required_observation_types :list[str]#
required_state_types :list[str]#
abstract predict(observations: float | np.ndarray, states: float | np.ndarray | None) → tuple[float | np.ndarray | None, float | np.ndarray]#

Compute the next internal state and prediction based on the current observation and internal state.

Parameters:

  • observation (Union[float, np.ndarray]) – The current observation.

  • states (Union[float, np.ndarray, None]) – The current internal state of the motion model.

Returns:

The next internal state and the prediction.

Return type:

Tuple[Union[float, np.ndarray, None], Union[float, np.ndarray]]

classmethod from_config(config: dict) → BaseMotionModel#

Initialize a motion model instance from a configuration dictionary.

Parameters:

config (Dict) – The configuration dictionary containing the motion model’s parameters.

Returns:

A new instance of the motion model initialized with the given configuration.

Return type:

MotionModel

class sportslabkit.motion_model.ExponentialMovingAverage(gamma: float = 0.5)#

Bases: sportslabkit.motion_model.base.BaseMotionModel

Exponential Moving Average (EMA) motion model for object tracking.

This class implements an EMA-based motion model for object tracking. It can be used both in a stateful and a procedural manner.

gamma#

The weight for the exponential moving average calculation.

Type:

float

_value#

The internal state of the motion model.

Type:

Union[float, np.ndarray, None]

Overview

Methods#

predict(observations, states)

Compute the next internal state and prediction based on the current observation and internal state.

Members

hparam_search_space :dict[str, dict[str, object]]#
required_observation_types = ['box']#
required_state_types = ['EMA_t']#
predict(observations: dict[str, Any], states: dict[str, float | np.ndarray[Any, Any]] = ...) → tuple[numpy.ndarray[Any, Any], dict[str, float | np.ndarray[Any, Any]]]#

Compute the next internal state and prediction based on the current observation and internal state.

Parameters:

  • observation (Union[float, np.ndarray]) – The current observation.

  • states (Union[float, np.ndarray, None]) – The current internal state of the motion model.

Returns:

The next internal state and the prediction.

Return type:

Tuple[Union[float, np.ndarray, None], Union[float, np.ndarray]]

class sportslabkit.motion_model.KalmanFilter(dt: float = 1 / 30, process_noise: float = 0.001, measurement_noise: float = 0.001, confidence_scaler: float = 1.0)#

Bases: sportslabkit.motion_model.base.BaseMotionModel

Abstract base class for motion models.

This class defines a common interface for all motion models. Derived classes should implement the update, and predict methods. MotionModels are procedural and stateless. The state of tracklet is managed by the Tracklet class. The tracklet must have the required observations and states for the motion model to work. If the tracklet doesn’t have the required observations or states, the motion model will raise an error and tell the user which observations or states are missing.

Overview

Methods#

get_initial_kalman_filter_states(box)

-

predict(observations, states)

Compute the next internal state and prediction based on the current observation and internal state.

Members

hparam_search_space :dict[str, dict[str, Any]]#
required_observation_types :list[str] = ['box', 'score']#
required_state_types :list[str] = ['x', 'P', 'F', 'H', 'R', 'Q']#
get_initial_kalman_filter_states(box: numpy.ndarray) → dict[str, numpy.ndarray]#
predict(observations: dict[str, [float | ndarray]], states: dict[str, float | ndarray] = None) → tuple[numpy.ndarray, dict[str, float | ndarray]]#

Compute the next internal state and prediction based on the current observation and internal state.

Parameters:

  • observation (Union[float, np.ndarray]) – The current observation.

  • states (Union[float, np.ndarray, None]) – The current internal state of the motion model.

Returns:

The next internal state and the prediction.

Return type:

Tuple[Union[float, np.ndarray, None], Union[float, np.ndarray]]

Functions#

sportslabkit.motion_model.tune_motion_model(motion_model_class, detections, ground_truth_positions, n_trials=100, hparam_search_space=None, metric=iou_score, verbose=False, return_study=False)[source]#