The OpenPTV contains of:
- Core library written in C, called liboptv
- 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:
- Python 2.7 with PyQt4 GUIs and command line scripts from Yosef Meller called The Particle Bureau of Investigation or pbi
- 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:
To build your program you also link it with
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
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.
- Both the library
liboptvand 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 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¶
Create the directory that will contain everything:
mkdir ~/openptv && cd ~/openptv
Install Check Unit testing framework:
sudo apt-get install check
sudo apt-get install cmake
Install missing compilers:
sudo apt-get install build-essential
sudo apt-get install git
Install Canopy Python distribution (Python 2.7)
Run Canopy (either ~/Canopy/canopy or Applications -> Canopy)
Add scikit-image package through Canopy Package Manager
Open Canopy Terminal through Canopy -> Tools -> Canopy Terminal
Get the GUI, for instance we explain about pyptv here that downloads also the OpenPTV library using –recursive:
git clone --recursive http://github.com/alexlib/pyptv.git pyptv
Compile OpenPTV library liboptv it using cmake and test it:
cd pyptv/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
Install Python bindings for the library (installs
cd ~/../../py_bind python setup.py build_ext --inplace -I/usr/local/include -L/usr/local/lib python setup.py install cd tests nosetest
58 tests should be running and passing
Get 3D-PTV test folder and create the res/ folder if missing
cd ~ git clone https://github.com/OpenPTV/test_cavity.git
Run the software using the test_cavity folder, if all works fine, that’s it:
cd pyptv/pyptv python pyptv_gui.py ../../test_cavity
If you encounter the error like this while trying to run the
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/
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 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 install_macosx.sh 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.
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
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
liboptvis a simple matter of running the following commands in the
cmake make make verify make install
The install process will put the header files and libraries in default system
paths (on linux,
/usr/local/lib respectively), so that
you can use the
optv library in your code without further modifications. You
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: <https://groups.google.com/forum/#!forum/openptv>
Getting started using Virtual Machine appliances¶
Ubuntu 18.04 with pyptv, see here: https://github.com/alexlib/pyptv/wiki/Getting-started-using-VirtualBox-Linux-(Ubuntu-18.04)-image
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: <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.
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
C:\MinGW\msys\1.0\include or a similar
path. Make sure to verify this.
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
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
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