Metadata-Version: 2.4
Name: tracking-markers
Version: 0.12.0
Summary: A humble image tracking code
Keywords: image-tracking,opencv
Author: Giovanni Bordiga
Author-email: Giovanni Bordiga <gbordiga@seas.harvard.edu>
License-Expression: MIT
License-File: LICENSE
Requires-Dist: numpy>=1.26.1,<2
Requires-Dist: opencv-python>=4.8.1.78,<5
Requires-Dist: tqdm>=4.67.1,<5
Requires-Python: >=3.10, <3.13
Project-URL: Homepage, https://github.com/bertoldi-collab/tracking-markers
Project-URL: Repository, https://github.com/bertoldi-collab/tracking-markers
Description-Content-Type: text/markdown

# A humble image tracking code

![Made with Python](https://img.shields.io/badge/Made%20with-Python-blue?logo=python&logoColor=ecf0f1&labelColor=34495e)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/tracking-markers?labelColor=34495e)
[![PyPI](https://img.shields.io/pypi/v/tracking-markers?labelColor=34495e)](https://pypi.org/project/tracking-markers "Go to PyPI")
![PyPI - Wheel](https://img.shields.io/pypi/wheel/tracking-markers?labelColor=34495e)
[![Pepy Total Downloads](https://img.shields.io/pepy/dt/tracking-markers?labelColor=34495e)](https://pepy.tech/projects/tracking-markers)
[![GitHub license](https://img.shields.io/github/license/bertoldi-collab/tracking-markers?labelColor=34495e)](https://github.com/bertoldi-collab/tracking-markers/blob/main/LICENSE)
![Badge](https://hitscounter.dev/api/hit?url=https%3A%2F%2Fgithub.com%2Fbertoldi-collab%2Ftracking-markers&label=Visits&icon=heart-fill&color=%232ecc71&message=&style=flat&tz=UTC)

This is a humble image tracking code.
It is humble because it does what it can.

<p align="center">
  <img width="460" height="300" src="examples/spaceman.gif">
</p>

## Why

Unlike [typical tracking software](https://docs.opencv.org/4.x/d5/dae/tutorial_aruco_detection.html), this code does _not_ require any _physical_ markers to be placed in the scene.
It can track arbitrary high-contrast points in the video.
The points to be tracked act as virtual markers that are manually selected by the user or loaded from a file.
This makes it suitable for tracking points in videos where placing physical markers is not possible or practical.

## Installation

Intall latest version directly from PyPI with

```bash
pip install tracking-markers
```

Or install from this repository (assuming your ssh keys are set up in your GitHub account) with

```bash
pip install git+ssh://git@github.com/bertoldi-collab/tracking-markers.git@main
```

Or clone the repository and install with

```bash
git clone git@github.com:bertoldi-collab/tracking-markers.git
cd tracking-markers
pip install -e .
```

## How to use

### CLI

Run in a terminal

```bash
tracking-markers path/to/video.mp4
```

See `tracking-markers --help` for more info on all the options.

### Python

The main module is [`tracking_points.py`](tracking_markers/tracking_points.py) defining the `track_points(...)` function that actually does the tracking of a given video and the function `select_markers(...)` that allows for the manual selection of markers.
These functions can be used independently.
The file [`tracking_points.py`](tracking_markers/tracking_points.py) can also be used as a script.

## Additional info

- It is based on the [OpenCV](https://opencv.org/) library.
- Allows for markers to be manually selected or an `np.ndarray` of markers can be loaded from a file.
- Works best on high-contrast videos.

## Development

This project uses [uv](https://docs.astral.sh/uv/) for dependency management and builds.

```bash
uv sync            # create the virtual environment and install dependencies
uv run pytest      # run the test suite
uv build           # build the sdist and wheel into dist/
uv publish         # publish to PyPI
```

## Citation

If you use this code in your research or any other work, please cite it as follows:

```bibtex
@misc{bordiga2023humble,
    title        = {A humble image tracking code},
    author       = {Bordiga, Giovanni},
    year         = {2023},
    howpublished = {\url{https://github.com/bertoldi-collab/tracking-markers}},
    note         = {Bertoldi Group}
}
```
