PyPTV or otherwise called OpenPTV-Python is the Python GUI for OpenPTV. It is based on traits, traitsui, chaco, enable and pyface from Enthought Inc. and provides an UI interface the OpenPTV library that includes all the core algorithms (correspondence, tracking, calibration, etc.) written in ANSI C and has Python bindings using Cython.
Both PyPTV and the OpenPTV library are in the development phase and continuously refactored. Please follow the development on the community mailing list:
👉 View full documentation at https://alexlib.github.io/pyptv
http://openptv-python.readthedocs.io
This project uses uv for fast dependency management. A local wheel of optv>=0.3.2 is included in the wheels/ directory until it's available on PyPI.
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Create virtual environment and install dependencies
uv sync
# Or to create environment from scratch
rm -rf .venv && uv syncThe uv.toml configuration automatically uses the local wheel from wheels/. The uv.lock file pins all dependencies for reproducible builds.
Short version:
pip install numpy
python -m pip install pyptv --index-url https://pypi.fury.io/pyptv --extra-index-url https://pypi.org/simple
Note: If optv>=0.3.2 is not yet available on PyPI, install it from the local wheel first:
pip install wheels/optv-0.3.2-*.whl
python -m pip install pyptv --index-url https://pypi.fury.io/pyptv --extra-index-url https://pypi.org/simple
Detailed instructions for various platforms are in our documentation: https://openptv-python.readthedocs.io/en/latest/installation_instruction.html
Follow the instructions in our screencasts and tutorials:
-
Tutorial 1: http://youtu.be/S2fY5WFsFwo
-
Tutorial 2: http://www.youtube.com/watch?v=_JxFxwVDSt0
-
Tutorial 3: http://www.youtube.com/watch?v=z1eqFL5JIJc
Ask for help on our mailing list:
Plugins is a system of extensions to PyPTV without the need to change the GUI
- copy the
sequence_plugins.txtandtracking_plugins.txtto the working folder - copy the
plugins/directory to the working folder - modify the code so it performs instead of the default sequence or default tracker
- Open the GUI and Plugins -> Choose , then run the rest: Init -> Sequence
Note, the specific branch plugin_remback requires installation of the pip install rembg[cpu] or pip install rembg[gpu]
Version Management:
- Bump version:
python bump_version.py --patch
Publishing to PyPI:
- See DEPLOYMENT.md for comprehensive deployment instructions using GitHub Actions and trusted publishing
Legacy Manual Publishing:
pip install build
python -m build
pip install dist/pyptv-*.whl # Install the built wheel
pip install twine
python -m twine upload dist/*- Supported NumPy versions: >=2.0.0,<2.7
- NumPy 2.x required for optv 0.3.2+
- Tested with NumPy arrays in both float64 and uint8 formats
- Array operations maintained for image processing and coordinate transformations
- NumPy 2.x support requires chaco>=6.1.0 and enable>=6.1.0
- Compatible with optv 0.3.2+
- optv 0.3.2+ requires NumPy >=2.0.0
- Core functionality tested with latest optv release
- Calibration and tracking functions verified
For development work with latest NumPy:
conda create -n pyptv python=3.11
conda activate pyptv
conda install numpy>=1.23.5 optv>=0.3.0
pip install -e .This repo includes Marimo-based interactive UIs.
Run the Detection UI:
uv pip
7DAE
install marimo
uv run marimo run pyptv/marimo_ui_detection.pyOr use the helper script:
./run_marimo_detection.shRun the Parameters UI:
uv pip install marimo
uv run marimo run pyptv/marimo_ui_parameters.pyOr use the helper script:
./run_marimo_parameters.shThis is a detailed description of the project...