Installation instructions

Introduction

The OpenPTV contains of these main parts:

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

The Python bindings allow the easy access to the C library. There are two packages that are built around the Python bindings:

  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 with Enthought based GUI (using TraitsUI and Chaco) called PyPTV

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.

One has to install first liboptv and the Python bindings and after that the pbi or pyptv (or both).

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 Linux/Mac OS

  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 Anaconda (read their instructions, shall be straightforward) or Canopy Python distribution (Python 2.7)

    bash canopy_xxx.xxx.sh

  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://github.com/OpenPTV/openptv.git
cd openptv/liboptv
mkdir build && cd build
cmake ../ -G "Unix Makefiles"
make
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 ~/openptv/openptv/py_bind
python setup.py build_ext --inplace -I/usr/local/include -L/usr/local/lib
python setup.py install
cd tests
nosetest

56 tests should be running and passing

  1. Get pbi or pyptv, an example is for pyptv here:

    cd ~/openptv
git clone git://github.com/alexlib/pyptv.git
cd pyptv/pyptv_gui
python setup.py install

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

    git clone https://github.com/OpenPTV/test_cavity.git

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

    python pyptv_gui.py ~/openptv/test_cavity

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

 python pyptv_gui.py ../../test_cavity

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

Then it’s suggested to try:

PATH=/usr/local/lib:$PATH python pyptv_gui.py ~/ptv_test_folder/

or

LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH python pyptv_gui.py ~/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 <http://check.sourceforge.net> and install according to the instructions in the Check package. Typically you would need to run the following commands in a shell:

    ./configure
make
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 <http://cmake.org>.

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

    cmake
make
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 - outdated, see VirtualBox option below

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: <http://www.mingw.org/wiki/MSYS>

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 <http://check.sourceforge.net>

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
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 cmake.org.

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:

cmake ../ -DCMAKE_INSTALL_PREFIX:PATH=/usr -DCMAKE_PREFIX_PATH=/c/MinGW/msys/1.0/

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

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>

Getting started using virtual machine

There are two VirtualBox images: 1) older on Ubuntu 16.04, 6.4Gb image of openptv-python https://github.com/OpenPTV/openptv-python/wiki/No-Installation-with-Virtual-Machine and 2) a newer (but without multiplane calibration yet) Ubuntu 18.04 with pyptv https://github.com/alexlib/pyptv/wiki/Getting-started-using-VirtualBox-Linux-(Ubuntu-18.04)-image