Installation instructions


The OpenPTV contains of two main parts:

  1. Core library written in C, called liboptv
  2. Python 2, Enthought ETS based frontend GUI and control entitled openptv-python (note that we support so far Python 2.x, Python 3 is not yet tested)

The C library liboptv 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.

The Python GUI is based on the great packages of NumPy, SciPy, Enthought TraitsUI, Cython (for linking to the liboptv) and these have to be installed prior to installing openptv-python. NOTE THAT WE ARE STILL USING PYTHON 2.X

You need to install first liboptv and then it Python bindings and after that the openptv-python part to make OpenPTV working and accessible through GUI. It is possible, however, to use pre-compiled binaries for the liboptv. We explain all the possibilities in this document.

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.

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.

Installing on Ubuntu or Mac OS X:

  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 (2 or higher), download from - Python 2.7 version, follow their instructions, on (some version of Canopy 2.1 or higher)

  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 OpenPTV library liboptv, compile it using cmake and test it:

    cd ~/openptv
    git clone git://
    cd openptv/liboptv
    mkdir build && cd build
    cmake ../ -G "Unix Makefiles"
    make verify
    sudo make install
  11. Install Python bindings for the library (installs `optv` module):

    cd ~/openptv/openptv/py_bind
    python build_ext --inplace -I/usr/local/include -L/usr/local/lib
    python install
    cd tests
  12. Get OpenPTV-Python:

    cd ~/openptv
    git clone git://
    cd openptv-python/pyptv_gui
    python build_ext --inplace -I/usr/local/include -L/usr/local/lib
  13. Get 3D-PTV test folder and create the res/ folder if missing

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

    python ~/openptv/test_cavity

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

     python ../../test_cavity

> Wrong experimental directory /home/hristo/ptv_test_folder
    > src_path= /home/hristo/openptv-python/src_c
    > Traceback (most recent call last):
    > File "", line 60, in <module>
    > import ptv1 as ptv
    > 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/Installing 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) openptv-python and install Anaconda using the Mac OS package.

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.

Installing on Windows

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 Canopy 2+ (from Enthought) 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

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>

If I do not want to build or test the software, can I use pre-compiled binaries?

Mac OS X users can use the pre-compiled try-before-installing instructions

For Linux and Windows it is possible to download the appropriate pre-compiled library files: liboptv installers

The include folder content should be copied/installed to something like /usr/local/include and the lib content into /usr/local/lib. Otherwise add the location of the liboptv files in the next step, e.g.:

$ python install -I /usr/local/include -L /usr/local/lib

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

Can I use a virtual machine?

Yes, follow these instructions

If I do not want to use package managers but to get all the Python packages at once?

You can get one of the Python development environments for your platform. Some had good experiences with WinPython, PythonXY, Canopy and later Anaconda. NOTE THAT WE HAVE NOT TESTED PYTHON 3 AND WE ARE USING AND SUPPORTING PYTHON 2.X.