# Kinematic Tracker

<img src="https://kovalp.github.io/kinematic-tracker-docs/logo-kinematic-tracker.png" width="96" alt="logo">
<img src="https://kovalp.github.io/kinematic-tracker-docs/logo-vicomtech.svg" width="192" alt="logo">


📖 Live docs: https://kovalp.github.io/kinematic-tracker-docs/

This tracker is based on kinematic Kalman filters. The system state can consist of multiple parts,
each defined by its *kinematic order* and *dimensionality*. For example, to track cuboids
aligned with Cartesian axes, we might decide for a constant-acceleration motion model
for Cartesian coordinates and a constant-position motion model for the sizes of the cuboids.
This choice encoded by `orders = [3, 1]`. The dimensionality of both parts (coordinates and sizes)
is `3`. Therefore `dimensions = [3, 3]` in our example.

The state of the cuboids aligned with Cartesian axis will have 12 variables.
Internally, a block-diagonal states are used, i.e.

```state = p_x, v_x, a_x, p_y, v_y, a_y, p_z, v_z, a_z, s_x, s_y, s_z```

To simplify the input/output processing, one might find attractive a derivative-sorted order

```state = p_x, p_y, p_z, s_x, s_y, s_z, v_x, v_y, v_z, a_x, a_y, a_z```

This package provides utility classes for such conversion (block-diagonal ↔ derivative sorted).

## Process noise models

The tracker supports various process noise models, including a custom adaptive process noise model
based on a white-noise assumption.

## Association metrics

A number of association metrics are implemented. Some of the metrics are experimental.

  - Mahalanobis with a process-measurement noise sum covariance (HPH + R) -- **default**.
  - 3D axes-aligned GIoU (volumetric GIoU for cuboids).
  - 3D yaw-only GIoU (volumetric GIoU for cuboids oriented by yaw).
  - Mahalanobis with size-modulated covariance (experimental)

## Installation

If you plan to use OpenCV with HighGUI, then

```shell
pip install kinematic-tracker[gui]
```

If you do not plan to use OpenCV's GUI, then

```shell
pip install kinematic-tracker[headless]
```

In any case, you choose one extra: `gui` or `headless`.

## Usage

Simple examples are available in the `test/tutorials` folder.
The `test` folder is available in the source package 

```shell
pip download kinematic-tracker --no-binary :all: --no-deps
```

## Use the kinematic-tracker as dependency

```shell
uv add kinematic-tracker --extra headless
```

If you happen to need GUI-enabled version of OpenCV, then 

```shell
uv add kinematic-tracker --extra gui
```

