kinematic-tracker 15.0.0__tar.gz

kinematic_tracker-15.0.0/.bumpversion.toml

@@ -0,0 +1,32 @@
+[tool.bumpversion]
+current_version = "15.0.0"
+parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
+serialize = ["{major}.{minor}.{patch}"]
+search = "{current_version}"
+replace = "{new_version}"
+regex = false
+ignore_missing_version = false
+ignore_missing_files = false
+tag = false
+sign_tags = false
+tag_name = "{new_version}"
+tag_message = "Bump version: {current_version} → {new_version}"
+allow_dirty = false
+commit = true
+message = "Bump version: {current_version} → {new_version}"
+moveable_tags = []
+commit_args = "--no-verify"
+setup_hooks = []
+pre_commit_hooks = ["uv lock --native-tls", "git add uv.lock"]
+post_commit_hooks = []
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = "version = \"{current_version}\""
+replace = "version = \"{new_version}\""
+
+[[tool.bumpversion.files]]
+filename = "src/kinematic_tracker/__init__.py"
+search = "__version__ = '{current_version}'"
+replace = "__version__ = '{new_version}'"
+

kinematic_tracker-15.0.0/.coveragerc

@@ -0,0 +1,13 @@
+[run]
+omit = test/*
+source = src/
+
+[report]
+show_missing = true
+skip_empty = true
+skip_covered = true
+sort = Miss
+
+
+ignore_errors = True
+

kinematic_tracker-15.0.0/.gitignore

@@ -0,0 +1,12 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.coverage
+.python-version
+# Virtual environments
+.venv
+.idea

kinematic_tracker-15.0.0/.gitlab-ci.yml

@@ -0,0 +1,34 @@
+# GitLab configuration script to run two jobs: unit test and lint check
+# for projects using *opencv-python* and managed by *uv* package manager.
+
+default:
+  image: python:3.10
+
+
+stages:          # List of stages for jobs, and their order of execution
+  - test
+
+unit-test-job:   # This job runs in the test stage.
+  stage: test    # It only starts when the job in the build stage completes successfully.
+  script:
+    - apt update
+    - apt install -y libgl1 xvfb
+    - pip install uv
+    - export UV_INDEX_GITLAB_USERNAME=gitlab-ci-token
+    - export UV_INDEX_GITLAB_PASSWORD=${CI_JOB_TOKEN}
+    - uv sync
+    - uv pip install -e .
+    - uv run pytest -s test --cov --junitxml=report.xml
+  artifacts:
+    when: always
+    reports:
+      junit: report.xml
+  coverage: '/(?i)total.*? (100(?:\.0+)?\%|[1-9]?\d(?:\.\d+)?\%)$/'
+
+
+lint-test-job:   # This job also runs in the test stage.
+  stage: test    # It can run at the same time as unit-test-job (in parallel).
+  script:
+    - pip install ruff
+    - ruff check
+

kinematic_tracker-15.0.0/CHANGELOG.md

@@ -0,0 +1,111 @@
+# 14.2.0
+
+  - Using the package `binary-classification-ratios`.
+
+# 14.1.2
+
+  - Compatibility with nuScenes @ `evaluation-against-nuscenes` (Python >=3.10 & NumPy >=1.26.4).
+
+# 14.1.0
+
+  - Added an association-threshold setter in `NdKkfTracker`.
+
+# 14.0.1
+
+  - Corrected the example of tracking with yaw angle affected by the version 14.
+  - Made the example of tracking association quality more robust.
+
+# 14.0.0
+    
+This version bump is major because it breaks a silent convention on the distribution 
+of variables in the measurement vector. In previous versions, the measurement vector
+has been distributed as follows:
+
+     $$z^T = (p_x, p_y, p_z, s_x, s_y, s_z, ...)$$
+
+In this version, the distribution of variables in the measurement vector is as follows:
+
+     $$z^T = (p_x, p_y, p_z, ..., s_x, s_y, s_z)$$
+
+where the position variables are listed first, followed by the size variables.
+This change makes the tracker more convenient to use with ASAM OpenLabel frames.
+
+  - Possibility to adjust the distribution of variables in the measurement vector.
+  - Added setter `NdKkfTracker.set_ind_pos_size`.
+
+# 13.0.1
+    
+  - Proofread the README file.
+  - Renamed `gen_z` --> `gen_xz` in tracker.
+
+# 12.1.0
+
+  - Remove the unfinished `GIoUWithYaw` class.
+  - Add all non-trivial docstrings.
+  - Eliminate the flip in Greedy matching.
+  - Eliminate unused buffer in the Mahalanobis metric driver.
+  - Remove the obsolete method `NdKkfTrack.get_det_cov()`. 
+
+# 12.0.0
+
+  - All dependencies are public from PyPI.
+
+# 11.1.2
+
+  - Add docstrings in `nd` modules
+  - Use documented version of the kinematic-matrix package (viulib-kinematic-matrices>=0.3.0)
+
+
+# 11.1.0
+
+  - Allow both `int` and `np.int64` to be used as time stamps in the `Tracker.advance` method.
+  - Add three tutorial examples:
+    - tracking of cuboids aligned with Cartesian axes
+    - tracking of cuboids with yaw angle
+    - tracking and classifying the association quality
+
+# 11.0.0
+
+  - Introduced the (bipartite) matching drivers:
+    - Maximal shape of the metric is rectangular
+    - The returned match is in fixed-size numpy arrays which stay the same across time stamps
+    - Auxiliary buffers are used instead of temporary (scrap) RAM
+  - Remove the calculation of threshold from the association probability 
+
+# 10.4.0
+
+  - Added nuScenes example
+  - Refactored the metric drivers:
+    - Maximal shape of the metric is rectangular
+    - Metric is computed in a chunk of memory at the beginning of the rectangular buffer
+    - The returned matrix is rectangular, local and shares memory with the buffer
+    - Removed O(N) buffers for $Hx$ and $HPH^T$
+    - The order of indices is (reports, targets) resulting in wide matrices most of the time
+    - Auxiliary buffers are used instead of temporary (scrap) RAM 
+
+# 10.3.0
+
+ - Add ClassificationRatios helper class
+ - Add fusion-lab example of two almost colliding cuboids
+ - Add padding to the Hungarian matching
+ - Association-quality- and Cartesian-quality helper classes in unit tests
+
+# 10.2.0
+
+ - Add AssociationQuality classifier
+ - Change default association threshold from 0.9 --> 0.25
+ - Fix finite-diff adaptive noise to multiply with the variance factor
+ - Add setter NdKkfTracker.set_measurement_std_dev(...)
+
+# 10.0.0
+
+ - Removed GatherAtStart in favor of DerivativeSorted
+
+# 2.0.2
+
+ - Started GIoU with yaw
+
+# 1.1.2
+  
+ - Initial release
+

kinematic_tracker-15.0.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: kinematic-tracker
+Version: 15.0.0
+Summary: Tracker using kinematic Kalman filters.
+Author-email: Peter Koval <pkoval@vicomtech.org>
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: association-quality-clavia>=0.1.0
+Requires-Dist: binary-classification-ratios>=0.3.0
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: opencv-python>=4.11.0.86
+Requires-Dist: scipy>=1.15.3
+Description-Content-Type: text/markdown
+
+# Kinematic Tracker
+
+This tracker is based on kinematic Kalman filters. The system state can consist of multiple components,
+each defined by its kinematic order and dimensionality. The tracker supports various process noise models,
+including a custom adaptive process noise model based on a white-noise assumption.
+
+## Tutorial Examples
+
+Simple, reusable examples are available in the `test/tutorials` folder.
+
+## Installation
+
+After installing the `uv` package manager, run:
+
+```shell
+uv sync --no-dev
+```
+
+## Development Installation
+
+For development setup instructions, please refer to the maintainers' README.

kinematic_tracker-15.0.0/README.md

@@ -0,0 +1,21 @@
+# Kinematic Tracker
+
+This tracker is based on kinematic Kalman filters. The system state can consist of multiple components,
+each defined by its kinematic order and dimensionality. The tracker supports various process noise models,
+including a custom adaptive process noise model based on a white-noise assumption.
+
+## Tutorial Examples
+
+Simple, reusable examples are available in the `test/tutorials` folder.
+
+## Installation
+
+After installing the `uv` package manager, run:
+
+```shell
+uv sync --no-dev
+```
+
+## Development Installation
+
+For development setup instructions, please refer to the maintainers' README.

kinematic_tracker-15.0.0/assets/reshot-icon-tracking-services-TWK37ZBV68.svg

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Creator: CorelDRAW -->
+<svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" width="2048px" height="2048px" style="shape-rendering:geometricPrecision; text-rendering:geometricPrecision; image-rendering:optimizeQuality; fill-rule:evenodd; clip-rule:evenodd"
+viewBox="0 0 2048 2048"
+ xmlns:xlink="http://www.w3.org/1999/xlink">
+ <defs>
+  <style type="text/css">
+   <![CDATA[
+    .fil2 {fill:none}
+    .fil0 {fill:#424242}
+    .fil1 {fill:#424242;fill-rule:nonzero}
+   ]]>
+  </style>
+ </defs>
+ <g id="Layer_x0020_1">
+  <metadata id="CorelCorpID_0Corel-Layer"/>
+  <g id="_324608240">
+   <g>
+    <path id="_324608792" class="fil0" d="M1094.26 1026.38l132.912 132.912c18.7394,18.7382 18.7394,49.1374 0,67.8756 -18.7382,18.7394 -49.1374,18.7394 -67.8756,0l-132.912 -132.912c-18.7394,-18.7382 -18.7394,-49.1374 0,-67.8756 18.7382,-18.7394 49.1374,-18.7394 67.8756,0z"/>
+    <path id="_324608168" class="fil1" d="M1130.76 1210.45l82.6619 -82.6619c14.1662,-14.1638 32.8004,-21.248 51.4087,-21.248 18.6095,0 37.2425,7.08426 51.4063,21.248l454.513 454.513c14.1638,14.1638 21.248,32.7992 21.248,51.4075 0,18.6071 -7.08426,37.2425 -21.248,51.4063l-85.6394 85.6394c-14.165,14.165 -32.7992,21.248 -51.4063,21.248 -18.6083,0 -37.2437,-7.08426 -51.4075,-21.248l-451.537 -451.536c-14.9823,-14.9847 -22.4752,-34.6973 -22.4752,-54.3851 0,-19.6866 7.49292,-39.4016 22.4752,-54.3839z"/>
+    <path id="_324608552" class="fil0" d="M740.304 255.999c267.475,0 484.304,216.829 484.304,484.304 0,267.475 -216.829,484.304 -484.304,484.304 -267.475,0 -484.304,-216.829 -484.304,-484.304 0,-267.475 216.829,-484.304 484.304,-484.304zm0 96.0001c214.455,0 388.304,173.849 388.304,388.304 0,214.455 -173.849,388.304 -388.304,388.304 -214.455,0 -388.304,-173.849 -388.304,-388.304 0,-214.455 173.849,-388.304 388.304,-388.304z"/>
+   </g>
+   <g>
+    <path id="_324608672" class="fil1" d="M613.621 465.793l253.856 0c13.2543,0 24,10.7457 24,24 0,2.98701 -0.548032,5.84646 -1.54488,8.48386l-22.4516 67.8225 -22.7811 -7.50001 22.7835 7.54253c-3.38859,10.2366 -13.0075,16.6595 -23.2512,16.4575l-208.322 0c-10.9795,0 -20.2382,-7.37363 -23.0918,-17.439l-22.454 -67.8296 -0.0153543 0.00472441c-4.16457,-12.5835 2.65866,-26.1626 15.2421,-30.3272 2.66575,-0.882284 5.3752,-1.26969 8.03032,-1.21536z"/>
+    <path id="_324608600" class="fil1" d="M897.845 815.115l-314.668 0c-1.89803,0.0318898 -3.82796,-0.161811 -5.76024,-0.603544 -12.9213,-2.95276 -21.0012,-15.8232 -18.0484,-28.7445l23.3965 5.34804 -23.3433 -5.34331 52.78 -230.916c1.79882,-11.4756 11.7284,-20.2559 23.7083,-20.2559l208.384 0c11.1142,-0.198425 21.2268,7.38662 23.8016,18.652l-0.0519685 0.011811 52.7776 230.902c0.66378,2.2004 1.02402,4.53307 1.02402,6.94961 0,13.2543 -10.7457,24 -24,24z"/>
+    <path id="_324608288" class="fil1" d="M771.393 798.194c0,-17.1697 -13.9205,-31.0902 -31.0902,-31.0902 -17.1709,0 -31.0902,13.9205 -31.0902,31.0902l31.0902 289.805 31.0902 -289.805z"/>
+   </g>
+  </g>
+ </g>
+ <rect class="fil2" width="2048" height="2048"/>
+</svg>

kinematic_tracker-15.0.0/maintainers/README.md

@@ -0,0 +1,38 @@
+# Development install
+
+```shell
+uv sync
+```
+
+## Add dependencies
+
+Regular or development dependencies are added as following
+```shell
+uv add numpy
+uv add pytest --dev
+```
+
+## Run tests
+
+```shell
+uv run pytest
+```
+
+## Formatting and checking 
+
+```shell
+ruff format
+ruff check --fix
+```
+
+## Bump version number 
+
+```shell
+bump-my-version bump patch
+```
+
+## Upgrading the dependencies
+
+```shell
+uv lock -U
+```

kinematic_tracker-15.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "kinematic-tracker"
+version = "15.0.0"
+description = "Tracker using kinematic Kalman filters."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "association-quality-clavia>=0.1.0",
+    "binary-classification-ratios>=0.3.0",
+    "numpy>=1.26.4", # important for compatibility with nuScenes (!)
+    "opencv-python>=4.11.0.86",
+    "scipy>=1.15.3",
+]
+license = 'MIT'
+authors = [{name = 'Peter Koval', email = 'pkoval@vicomtech.org'}]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.1",
+    "pytest-cov>=6.2.1",
+    "pytest-mock>=3.14.1",
+    "ruff>=0.12.8",
+    "bump-my-version>=1.2.1",
+]
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+

kinematic_tracker-15.0.0/ruff.toml

@@ -0,0 +1,89 @@
+# Exclude a variety of commonly ignored directories.
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".ipynb_checkpoints",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pyenv",
+    ".pytest_cache",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    ".vscode",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "site-packages",
+    "venv",
+]
+
+# Same as Black.
+line-length = 100
+indent-width = 4
+
+target-version = "py313"
+
+[lint]
+# Enable Pyflakes (`F`) and a subset of the pycodestyle (`E`)  codes by default.
+# Unlike Flake8, Ruff doesn't enable pycodestyle warnings (`W`) or
+# McCabe complexity (`C901`) by default.
+select = ["E4", "E7", "E9", "F", "I"]
+ignore = []
+
+# Allow fix for all enabled rules (when `--fix`) is provided.
+fixable = ["ALL"]
+unfixable = []
+
+# Allow unused variables when underscore-prefixed.
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[lint.isort]
+default-section = "third-party"
+lines-after-imports = 2
+split-on-trailing-comma=false
+lines-between-types = 1  # This adds 1 empty line between import sections
+
+[lint.flake8-quotes]
+inline-quotes = "single"
+
+[format]
+# Like Black, use double quotes for strings.
+quote-style = "single"
+
+# Like Black, indent with spaces, rather than tabs.
+indent-style = "space"
+
+# Like Black, respect magic trailing commas.
+skip-magic-trailing-comma = true
+
+# Like Black, automatically detect the appropriate line ending.
+line-ending = "auto"
+
+# Enable auto-formatting of code examples in docstrings. Markdown,
+# reStructuredText code/literal blocks and doctests are all supported.
+#
+# This is currently disabled by default, but it is planned for this
+# to be opt-out in the future.
+docstring-code-format = false
+
+# Set the line length limit used when formatting code snippets in
+# docstrings.
+#
+# This only has an effect when the `docstring-code-format` setting is
+# enabled.
+docstring-code-line-length = "dynamic"
+
+[lint.pydocstyle]
+convention = "google"
+

kinematic_tracker-15.0.0/src/kinematic_tracker/__init__.py

@@ -0,0 +1,3 @@
+"""."""
+
+__version__ = '15.0.0'

kinematic_tracker-15.0.0/src/kinematic_tracker/association/association.py

@@ -0,0 +1,124 @@
+"""
+This module defines the `Association` class. The `Association` class holds
+parameters to for computing an association metric (scores) and for computing
+the bipartite matching between (detection) reports and (tracked) targets.
+Apart from the parameter storage, the class provides methods to generate
+the metric and match drivers based on the selected types of metric and
+matching method.
+"""
+
+from typing import Sequence
+
+from .association_method import AssociationMethod
+from .association_metric import AssociationMetric
+from .match_greedy import MatchDriverGreedy
+from .match_hungarian import MatchDriverHungarian
+from .metric_giou_aligned import MetricGIoUAligned
+from .metric_mahalanobis import MetricMahalanobis
+
+
+class Association:
+    """
+    Represents an association mechanism for matching reports and targets
+    using configurable metrics and methods. Generates metric and match drivers.
+    """
+
+    def __init__(
+        self, num_x: int, num_z: int, ind_pos_size: Sequence[int] = (0, 1, 2, -3, -2, -1)
+    ) -> None:
+        """
+        Initializes the `Association` object with default parameters.
+
+        Args:
+            num_x: Number of variables in the state vector.
+            num_z: Number of variables in the measurement vector.
+            ind_pos_size: indices to get positions and sizes of cuboids for GIoU.
+                          By default, the indices will be 0,1,2,-3,-2,-1, i.e.
+                          the center of the cuboid is taken as first three variables
+                          of the measurement vector and sizes (dimensions) of the
+                          cuboids are taken from the last three variables.
+        """
+        self.threshold = 0.25  # Threshold for association
+        self.mah_pre_factor = 1.0  # Pre-factor for Mahalanobis distance
+        self.method = AssociationMethod.HUNGARIAN  # Default matching method
+        self.metric = AssociationMetric.GIOU  # Default metric
+        self.num_reports_max = 100  # Maximum number of reports
+        self.num_targets_max = 500  # Maximum number of targets
+        self.num_x = num_x  # State vector dimensionality
+        self.num_z = num_z  # Measurement vector dimensionality
+        self.ind_pos_size = ind_pos_size  # Distribution of variables in the measurement vector.
+
+    def __repr__(self) -> str:
+        """
+        Returns a string representation of the `Association` object.
+
+        Returns:
+            str: A string describing the association configuration.
+        """
+        return (
+            f'Association({self.method.value} '
+            f'{self.metric.value} '
+            f'threshold {self.threshold} '
+            f'mah_pre_factor {self.mah_pre_factor})'
+        )
+
+    def set_ind_pos_size(self, ind_pos_size: Sequence[int]) -> None:
+        """Set the location of positions and sizes of the cuboids relevant for GIoU metric.
+
+        The length of the `ind_pos_size` should be 6. The entries of the array points to
+        the locations in the measurement vector extracting the variables to form
+        a vector (pos_x, pos_y, pos_z, size_x, size_y, size_z). This vector will be
+        input for the GIoU aligned with Cartesian axes.
+
+        Note:
+            If we set this parameter, then we generally need another metric driver.
+
+        Args:
+            ind_pos_size: the permutation pointer array.
+        """
+        if len(ind_pos_size) != 6:
+            raise ValueError(f'Expect 6 elements in ind_pos_size, but got {len(ind_pos_size)}.')
+        self.ind_pos_size = ind_pos_size
+
+    def get_metric_driver(self) -> MetricMahalanobis | MetricGIoUAligned:
+        """
+        Initializes and returns the metric driver based on the selected metric type.
+
+        Returns:
+            MetricMahalanobis | MetricGIoUAligned: The metric driver instance.
+
+        Raises:
+            ValueError: If the metric is not supported.
+        """
+        if self.metric == AssociationMetric.MAHALANOBIS:
+            return MetricMahalanobis(
+                self.num_reports_max,
+                self.num_targets_max,
+                self.mah_pre_factor,
+                self.num_x,
+                self.num_z,
+            )
+        elif self.metric == AssociationMetric.GIOU:
+            return MetricGIoUAligned(
+                self.num_reports_max, self.num_targets_max, self.num_z, self.ind_pos_size
+            )
+        else:
+            raise ValueError('Unsupported metric.')
+
+    def get_match_driver(self) -> MatchDriverGreedy | MatchDriverHungarian:
+        """
+        Initializes and returns the match driver based on the selected matching method.
+
+        Returns:
+            MatchDriverGreedy | MatchDriverHungarian: The match driver instance.
+
+        Raises:
+            ValueError: If the method is not supported.
+        """
+        method = self.method
+        if method == AssociationMethod.GREEDY:
+            return MatchDriverGreedy(self.num_reports_max, self.num_targets_max)
+        elif method == AssociationMethod.HUNGARIAN:
+            return MatchDriverHungarian(self.num_reports_max, self.num_targets_max)
+        else:
+            raise ValueError('Unsupported matching method.')

kinematic_tracker-15.0.0/src/kinematic_tracker/association/association_method.py

@@ -0,0 +1,11 @@
+"""."""
+
+from enum import Enum
+
+
+class AssociationMethod(Enum):
+    """."""
+
+    GREEDY = 'greedy'
+    HUNGARIAN = 'hungarian'
+    UNKNOWN_METHOD = 'unknown-method'

kinematic_tracker-15.0.0/src/kinematic_tracker/association/association_metric.py

@@ -0,0 +1,11 @@
+"""Types of association metrics (matching scores)."""
+
+from enum import Enum
+
+
+class AssociationMetric(Enum):
+    """."""
+
+    GIOU = 'giou'
+    MAHALANOBIS = 'mahalanobis'
+    UNKNOWN_METRIC = 'unknown-metric'