Metadata-Version: 2.4
Name: kinematic-tracker
Version: 20.5.0
Summary: Tracker using kinematic Kalman filters.
Project-URL: ChangeLog, https://kovalp.github.io/kinematic-tracker-docs/CHANGELOG
Project-URL: Docs, https://kovalp.github.io/kinematic-tracker-docs/
Author-email: Peter Koval <pkoval@vicomtech.org>
License-Expression: MIT
Requires-Python: >=3.11
Requires-Dist: association-quality-clavia>=0.1.0
Requires-Dist: binary-classification-ratios>=0.3.0
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.15.3
Requires-Dist: shapely>=2.1.2
Provides-Extra: gui
Requires-Dist: opencv-python>=4.11.0.86; extra == 'gui'
Provides-Extra: headless
Requires-Dist: opencv-python-headless>=4.11.0.86; extra == 'headless'
Description-Content-Type: text/markdown

# 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)
  - IoU-like two-yaw (experimental): based on Mahalanobis distance with diagonal covariance.

## 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
```

