Installation instructions

TL;DR

With the modern Python 3.11 and enable 6.0.0 installation is quite simple:

conda create -n openptv python=3.11
conda activate openptv
pip install pyptv
git clone https://github.com/openptv/test_cavity
pyptv test_cavity

Introduction

The OpenPTV contains of:

  1. Core library written in C, called liboptv

  2. Python/Cython bindings, shipped together with the liboptv, inside py_bind directory

The Python bindings allow the easy access to the C library. There are two Python GUI packages that are built around the Python bindings to allow the end-user to use it in a more intuitive way:

  1. Python 3 with PyQt GUIs and command line scripts from Yosef Meller called The Particle Bureau of Investigation or pbi

  2. Python 3 based GUI (using TraitsUI, Enthought Chaco, etc.) called PyPTV

The overview

  1. if you plan to use C/C++/Fortran/etc. - compile the liboptv from source using cmake and testing it using libcheck library (see below instructions for Linux and Mac OS X).

  2. if you plan to use it only from Python (either through pbi command line approach or using pyptv GUI) then you can save time on installing liboptv by pip (see below) or compiling through Python bindings and testing it from Python.

liboptv - a library of the OpenPTV algorithms

This is a library - you can build it and link to it in your own project, e.g. calling functions from your own GUI or command-line software. When the package is installed correctly, you can reference it in your code by including files from the optv directory under the standard include path. For example:

#include <optv/tracking_frame_buf.h>

To build your program you also link it with liboptv. On gcc, one adds the flag -loptv to the command line. Other compilers and IDEs have their own instructions for adding libraries; consult your IDE/compiler manual for the details.

The library is using Check framework for the unit tests and Cmake project for the build. We recommend installing both software packages, however it is not obligatory, you may skip the relevant parts if you’re not going to develop or test the library.

Installation of PyPTV GUI including liboptv

On the new Apple Macbook M1 machines, it is recommended that Enthought Python Distribution (edm) be used and not Anaconda Python Distribution. It runs Python 3.8 but has all the necessary libraries like enable, chaco, pyface, in binary precompiled format.

Run the following lines in the EDM console

edm install numpy
edm shell
edm install pip
python -m pip install pyptv --index-url https://pypi.fury.io/pyptv --extra-index-url https://pypi.org/simple

Then run pyptv from the edm shell

On Linux, Windows, and older Apple machines install Python 3.11, we typically use Miniconda or similar:

conda create -n pyptv python=3.11 --yes
conda activate pyptv
pip install pyptv

if the last command fails, try: pip install pyptv –index-url https://pypi.fury.io/pyptv –extra-index-url https://pypi.org/simple

Building from source

Note that if you build from source, you will need a C compiler, on Mac OS X and Linux, it’s included as gcc or clang, but on Windows, you might want to install on https://wiki.python.org/moin/WindowsCompilers

  • note that sometimes your platform and your Python version does not match the packages we prepared upfront in the binary form (that does not require compilation), e.g. we have for Windows 10, Python 3.9 but not Python 3.11, or we might have one for Linux, but not for all distros.

  • if you experienced the error that relates to pyface.color.qt4, you might want to manually to the pyptv_gui.py file these two lines:

    from traits.etsconfig.api import ETSConfig ETSConfig.toolkit = ‘qt4’

Use our test case folder to see PyPTV in action like in video tutorials

Download and run the test case:

git clone --depth 1 -b master --single-branch https://github.com/OpenPTV/test_cavity.git
pyptv test_cavity

If you want to try the software but not really to get a development version, you can use our docker image:

Try Docker

Install Docker on Linux or Docker Desktop on Mac OS X and Windows. You can pull the ready image or build locally the docker image. This installation works on any platform through the noVNC browser. It already contains the test folder. Follow the instructions here:

OpenPTV + PyPTV Dockerfiles

Building development version and installation

If you want your own copy of the software, compiled and tested on your platform, then you first need to install Python 3. Note that we work on the Python 3 version but it is not ready yet.

If nothing works, where I can get help?

Send your build logs, description of the problem, and details of the operating system, Python version, etc., to our Google group or forum: <https://groups.google.com/forum/#!forum/openptv>