Installation instructions


The OpenPTV contains of:

  1. Core library written in C, called liboptv
  2. Python/Cython bindings, shipped together with the liboptv

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 2.7 with PyQt4 GUIs and command line scripts from Yosef Meller called The Particle Bureau of Investigation or pbi
  2. Python 2.7 based GUI (using TraitsUI, Enthought Chaco, etc.) called PyPTV

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.


  1. Both the library liboptv and the Python bindings (either pbi or pyptv or both) need to be installed, separately.

Below are instructions for building it and making it ready for use, either from a source distribution (a tarball with all necessary files) or directly from a Git repository, on various platforms (Linux, Windows, Mac OS X) and using various options such as Virtual Machine or Docker. Note that it is possible to install and run the OpenPTV software in the cloud, e.g. on Google Cloud, AWS, Azure, etc.

Use Docker

Use the instructions on PyPTV Dockerfiles

Basically it requires to install Docker and X Server (for GUI) and works on both Windows (tested on Win 10) and Mac OS X (tested on Mojave 10.14.2).

Build from source on Linux with Canopy Python distribution

  1. Create the directory that will contain everything:

    mkdir ~/openptv && cd ~/openptv
  2. Install Check Unit testing framework:

    sudo apt-get install check
  3. Install Cmake:

    sudo apt-get install cmake
  4. Install missing compilers:

    sudo apt-get install build-essential
  5. Install git:

    sudo apt-get install git
  6. Install Canopy Python distribution (Python 2.7)

  7. Run Canopy (either ~/Canopy/canopy or Applications -> Canopy)

  8. Add scikit-image package through Canopy Package Manager

  9. Open Canopy Terminal through Canopy -> Tools -> Canopy Terminal

  10. Get the GUI, for instance we explain about pyptv here that downloads also the OpenPTV library using –recursive:

    git clone --recursive pyptv
  11. Compile OpenPTV library liboptv it using cmake and test it:

    cd pyptv/openptv/liboptv
    mkdir build && cd build
    cmake ../ -G "Unix Makefiles"
    make verify

see that all tests passed and then:

sudo make install

check that it’s installed under /usr/local/include and /usr/local/lib

  1. Install Python bindings for the library (installs `optv` module):

    cd ~/../../py_bind
    python build_ext --inplace -I/usr/local/include -L/usr/local/lib
    python install
    cd tests

58 tests should be running and passing

  1. Get 3D-PTV test folder and create the res/ folder if missing

    cd ~
    git clone
  2. Run the software using the test_cavity folder, if all works fine, that’s it:

    cd pyptv/pyptv
    python ../../test_cavity

If you encounter the error like this while trying to run the openptv-python:

 python ../../test_cavity

> ImportError: cannot open shared object file: No such file or
> directory

Then it’s suggested to try:

PATH=/usr/local/lib:$PATH python ~/ptv_test_folder/


LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH python ~/ptv_test_folder/

Whichever works, it is then useful to update the local ~/.bashrc file to define this every time one opens a shell.

Building from source on Mac OS X:

Basically follow the Linux instructions, whenever the apt-get package manager is used, one can use MacPorts or Homebrew package managers.

Instead, one can simply download and install from source the a) check b) cmake c) liboptv, d) pyptv and install Anaconda Python distribution using the Mac OS package. For the very detailed set of instructions one can look at our .travis.yml and files in the PyPTV repository.

Installing directly from the source tree in Git is fast and simple, using CMake. Before installation first we need to make sure that the dependencies are installed. A bit more detailed instructions for Ubuntu users are given below.

  1. The tests of liboptv depend on the Check framework. You can either get it from your package manager (e.g. on Ubuntu `sudo apt-get install check’), or get the source package from <> and install according to the instructions in the Check package. Typically you would need to run the following commands in a shell:

    make install
  2. The build instructions for liboptv are processed with CMake. Again, this is available either from your package manager on Linux, or from <>.

    After installing CMake, installing liboptv is a simple matter of running the following commands in the liboptv/ directory:

    make verify
    make install

The install process will put the header files and libraries in default system paths (on linux, /usr/local/include and /usr/local/lib respectively), so that you can use the optv library in your code without further modifications. You can run cmake with parameters that would change the install locations (see below on the Windows install process). If you do so, remmember to make sure that your compiler knows the path to the installed location.

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: <!forum/openptv>

Getting started using Virtual Machine appliances

Ubuntu 18.04 with pyptv, see here:

Installing on Windows 7, 8.1 - OUTDATED, use Docker or Virtual Machine

Unlike Linux and MacOS, which both implement POSIX standards (the Unix standards base) and contain a default C build environment, Windows has no such environment. Choices range from the bare-bones Windows SDK, whose compiler is based on an outdated verion of C, to Visual Studio, a commercial product with its own IDE and build toolchain. Aside from being costly and proprietary, building with these compilers introduces compatibility problems with other programs. For example, building Python modules with VC 2010 from the Windows SDK fails because Python was build with VC 2008.

All this setup is here to justify the fact that build instructions here are for the MingW compiler and the MSYS package of Unix tools for Windows. After a hard process of trial and error this was found to be the easiest, most compatible solution.

The MSYS package provides the GCC compiler (MinGW), a Bash command-line shell and Unix build tools for Windows. It can be found here: <>

Use the mingw-get-setup method of instalation. During the installation you will be asked to choose subpackages. If you don’t know what you’re doing, choose everything.

After installing MSYS MinGW according to the instructions on the MSYS site, you will have a MinGW shell or MSYS shell in your start menu. Future instructions assume that this shell is used. the installation instructions on the MSYS page given above list some more steps you can and should do, so follow that page carefully. In particular, don’t forget to create the fstab file as instructed there.

Installing Check

The tests of liboptv depend on the Check framework. You can get it from <>

Some versions have problems with Windows. Version 0.9.8 is known to work. You can get version 0.9.14 to work by editing lib/libcompat.h and commenting out or removing lines 147-151.

Installing Check is done roughly in the same way as on Linux, in the MSYS shell:

./configure --prefix /usr
make install

However, it is important to note where the install actually lands so that we can help CMake find it. The Check library would be installed under the MSYS tree which was set up when installing MSYS. The above installation is in what MSYS refers to as /usr. If your MSYS is installed on C:MinGW, then Check would then be in C:\MinGW\msys\1.0\lib\ and C:\MinGW\msys\1.0\include or a similar path. Make sure to verify this.

Installing liboptv

Now that Check is installed, installing liboptv is relatively straightforward. Since you are reading this file, you already have that package. enter the liboptv/ subdirectory, create a directory under it called build/, and change into it.

For processing of build instructions, install CMake, from

Now, in the Build directory, initialize cmake with the following command:

cmake ../ -G "Unix Makefiles" -i

CMake will then ask you some questions about your system (accepting the defaults is usually ok). Now and at any future step, you can erase the contents of the build/ directory and start over. You can also regenerate makefiles with a simple cmake ../ in a working build directory, since CMake caches values you set before.

Now that CMake is initialized, a command to generate Makefiles with all paths told in advance, would be:


Note the path where Check was installed is specified, and be sure to adjust it if it is a different path in your system.

Now to build and install liboptv, type:

make install

This would install liboptv in what MSYS refers to as /usr, which is C:\MinGW\msys\1.0\ on my system. Any further program that is built using MSYS looks for this path by default so no further adjustment is necessary for using liboptv in your program, other than adding the include and link directives specified above.

However, on run time it appears that the pyd file we just installed looks for the accompanying DLL that was installed alongside it. Windows wants this DLL to be in the PATH it searches for executables. So the last step of installing on Windows is to modify the PATH environment variable so that it lists the place where the liboptv DLL is installed (in our example, this would be C:\MinGW\msys\1.0\lib). This can be done by right-clicking Computer on the start menu, choosing Properties -> Advanced system settings -> click Environment Variables -> edit the PATH variable on the bottom list and add the DLL’s location, separated by a semicolon (;) charachter from the directories already listed.

Installing Python environment

We recommend using Enthought Canopy Distribution or Anaconda to get all the necessary packages. The main ones are:

* Numpy
* Scipy
* Cython
* ETS from Enthought (including Traits, Chaco and Pyface - most difficult to build yourself)
* PyQt

For Windows 7 (8.1) there is an additional option to use pre-compiled binaries as explained here: Installation on Windows 7 using MinGW