A humble image tracking code

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

Why

Unlike typical tracking software, 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

pip install tracking-markers

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

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

Or clone the repository and install with

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

How to use

CLI

Run in a terminal

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 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 can also be used as a script.

Additional info

• It is based on the OpenCV 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 for dependency management and builds.

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:

@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}
}