Metadata-Version: 2.1
Name: unitrack
Version: 4.7.2
Summary: A multi-stage object tracking framework
Author-email: Kurt Stolle <k.h.w.stolle@gmail.com>
Keywords: perception,computer vision,deep learning,object detection,instance segmentation,semantic segmentation
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.2.2
Requires-Dist: scikit-learn>=1.2.2
Requires-Dist: tensordict>=0.3.2
Requires-Dist: unipercept
Provides-Extra: qa
Requires-Dist: black>=24.3.0; extra == "qa"
Requires-Dist: bandit[toml]; extra == "qa"
Requires-Dist: check-manifest; extra == "qa"
Requires-Dist: flake8>=7.0.0; extra == "qa"
Requires-Dist: flake8-bugbear; extra == "qa"
Requires-Dist: flake8-docstrings; extra == "qa"
Requires-Dist: flake8-formatter_junit_xml; extra == "qa"
Requires-Dist: flake8-import-conventions; extra == "qa"
Requires-Dist: flake8-unused-arguments; extra == "qa"
Requires-Dist: flake8-comprehensions; extra == "qa"
Requires-Dist: flake8-errmsg; extra == "qa"
Requires-Dist: flake8-logging-format; extra == "qa"
Requires-Dist: flake8-pie; extra == "qa"
Requires-Dist: flake8-pyi; extra == "qa"
Requires-Dist: flake8-pytest-style; extra == "qa"
Requires-Dist: flake8-return; extra == "qa"
Requires-Dist: flake8-2020; extra == "qa"
Requires-Dist: flake8-executable; extra == "qa"
Requires-Dist: flake8-simplify; extra == "qa"
Requires-Dist: flake8-black; extra == "qa"
Requires-Dist: flake8-pyproject; extra == "qa"
Requires-Dist: pre-commit; extra == "qa"
Requires-Dist: pygrep; extra == "qa"
Requires-Dist: isort>=5.13.2; extra == "qa"
Requires-Dist: refurb; extra == "qa"
Requires-Dist: pylint>=3.0.3; extra == "qa"
Requires-Dist: pylint_junit; extra == "qa"
Requires-Dist: shellcheck-py; extra == "qa"
Requires-Dist: pylint; extra == "qa"
Requires-Dist: mypy>=1.9.0; extra == "qa"
Requires-Dist: autoflake; extra == "qa"
Requires-Dist: pydocstyle; extra == "qa"
Requires-Dist: pyre-check; extra == "qa"
Requires-Dist: pydocstringformatter; extra == "qa"
Requires-Dist: pyrefact; extra == "qa"
Requires-Dist: pyflakes; extra == "qa"
Requires-Dist: mccabe; extra == "qa"
Provides-Extra: tests
Requires-Dist: hypothesis>=6.100.1; extra == "tests"
Requires-Dist: pytest>=8.1.1; extra == "tests"
Requires-Dist: pytest-sugar; extra == "tests"
Requires-Dist: pytest-xdist; extra == "tests"
Requires-Dist: pytest-benchmark; extra == "tests"
Requires-Dist: pytest-cov; extra == "tests"
Requires-Dist: pytest-mock; extra == "tests"
Requires-Dist: pytest-runner; extra == "tests"
Requires-Dist: pytest-github-actions-annotate-failures; extra == "tests"
Provides-Extra: notebooks
Requires-Dist: jupyterlab; extra == "notebooks"
Requires-Dist: ipywidgets; extra == "notebooks"
Requires-Dist: ipykernel; extra == "notebooks"
Requires-Dist: ipython-autotime; extra == "notebooks"
Requires-Dist: matplotlib>=3.8.4; extra == "notebooks"
Requires-Dist: seaborn>=0.13.2; extra == "notebooks"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: numpydoc; extra == "docs"

# Unified Tracking in PyTorch

This package is a robust object tracking framework for PyTorch. It facilitates multi-stage and cascaded tracking algorithms under various modular configurations and assignment algorithms. This open-source implementation is designed to facilitate research in computer vision and machine learning. 

## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Documentation](#documentation)
- [Contribution](#contribution)
- [Citation](#citation)
- [License](#license)
- [Recommendations](#recommendations)

## Installation

Ensure your environment meets the following requirements:

- `python >= 3.9`
- `torch >= 2.0`

Install via PyPI using the following command:

```bash
pip install unitrack
```

## Usage

The following example demonstrates object tracking across a sequence with detections that have `category` and `position` fields. This script tracks objects, updates internal state buffers for each frame, and prints the assigned IDs.

```python3
import unitrack

# Detections from 10 video frames having fields `category` and `position`.
frames = [
    {
        "category": torch.ones(1 + frame * 2, dtype=torch.long),
        "position": (torch.arange(1 + frame * 2, dtype=dtype)).unsqueeze(1),
    }
    for frame in range(0, 10)
]

# Multi-stage tracker with two value fields that map the detections' data
# to keys `pos_key` and `key_cat`, where the association stage calculates 
# the Euclidean distance of the positions between frames and subsequently 
# performs a Jonker-Volgenant assignment using the resulting cost matrix
tracker = unitrack.MultiStageTracker(
    fields={
        "key_pos": unitrack.fields.Value(key="category"),
        "key_cat": unitrack.fields.Value(key="position"),
    },
    stages=[unitrack.stages.Association(cost=costs.Distance("key_pos"), assignment=unitrack.assignment.Jonker(10))],
)

# Tracking memory that stores the relevant information to compute the
# cost matrix in the module buffers. States are observed at each frame,
# where in this case no state prediction is performed.
memory = unitrack.TrackletMemory(
    states={
        "key_pos": unitrack.states.Value(dtype),
        "key_cat": unitrack.states.Value(dtype=torch.long),
    }
)

# Iterate over frames, performing state observation, tracking and state
# propagation at every step.
for frame, detections in enumerate(frames):
    # Create a context object storing (meta)data about the current
    # frame, i.e. feature maps, instance detections and the frame number.
    ctx = unitrack.Context(None, detections, frame=frame)
    
    # Observe the states in memory. This can be extended to 
    # run a prediction step (e.g. Kalman filter) 
    obs = memory.observe()
    
    # Assign detections in the current frame to observations of
    # the state memory, giving an updated observations object
    # and the remaining unassigned new detections.
    obs, new = tracker(ctx, obs)
    
    # Update the tracking memory. Buffers are updated to match
    # the data in `obs`, and new IDs are generated for detection
    # data that could not be assigned in `new`. The returned tensor
    # contains ordered tracklet IDs for the detections assigned
    # to the frame context `ctx`.
    ids = tracks.update(ctx, obs, new)

    print(f"Assigned tracklet IDs {ids.tolist()} @ frame {frame}")
```

## Documentation

Technical documentation is provided inline with the source code.

## Contribution

Contributions that maintain backwards compatibility are welcome.

## Citation

If you utilize this package in your research, please cite the following paper:

```bib
@article{unifiedperception2023,
    title={Unified Perception: Efficient Depth-Aware Video Panoptic Segmentation with Minimal Annotation Costs},
    author={Kurt Stolle and Gijs Dubbelman},
    journal={arXiv preprint arXiv:2303.01991},
    year={2023}
}
```

Access the full paper [here](https://arxiv.org/abs/2303.01991).

## License

This project is licensed under [MIT License](LICENSE).

## Recommendations

The contents of this repository are designed for research purposes and is not recommended for use in production environments. It has not undergone testing for scalability or stability in a commercial context. Please use this tool within its intended scope.


