vitocpp/vcp

C++/Python 3 utilities for common vision tasks, e.g. streaming, visualization or image manipulation.

Note: As of 01/2020 this repository is WIP, I'm rewriting my utilities (especially simplifying the streaming module) over the next couple of months.

Current status (12/2020):
cloc --exclude-dir=.venv3,build,cmake,third-party,gen,doc,generated --exclude-lang=make,XML .
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
C++                             64           4305           2306          23566
C/C++ Header                    56           1600           1827           4435
Python                          25            841           1030           3172
CMake                           12            270            248           1179
Markdown                         3             97              0            389
Bourne Shell                     3             41             77            251
-------------------------------------------------------------------------------
SUM:                           163           7154           5488          32992
-------------------------------------------------------------------------------

What is it good for?

Some of vcp's highlights:

Best effort multiple device streaming with the vcp::best module. Useful for quick camera tests and whenever (guaranteed) synchronisation isn't crucial. The goal of this module is to stream from multiple devices simultaneously, without having the ROS overhead. A simple libconfig++-style configuration file allows you to process all streams both in C++ and python. For more details, see the separate BESt.md documentation.
Background subtraction is provided by the vcp::bgm module, for example:
Visualization utilities are provided by the vcp::imvis module, for example:
Pseudocoloring for data visualization/analysis is also provided by the vcp::imvis module. Back when I started working on this library, OpenCV didn't provide pseudocoloring capabilities. The vcp::imvis module allows visualization via common color maps (you might remember these from such frameworks as MATLAB, matplotlib, and whatnot).
Math utilities - besides enabling most of the fancy visualizations within vcp::imvis, you can also do basic geometry tasks with the vcp::math module (e.g. computing tangents of circles, line (segment) intersection, and quite a lot more).
C++ utilities - for basic file/path and string manipulation, sorting, and more (if you want to avoid heavier dependencies, such as Boost).

Repository Contents

./build-scripts - shell scripts to prepare the build system, build the libraries, etc.
./cmake - CMake utilities (incl. custom Find<package>.cmake scripts).
./examples - example usage of these utilities.
./src - source code for all C++ modules and python bindings.
./third-party - third party dependencies (which are not part of default system packages).

Installation

If you want to build the C++ library and Python3 bindings, simply run ./build-scripts/build-ubuntu-18.04.sh, this will:
- Check and ask you to install missing system packages.
- Configure the build (depending on which optional packages you installed, e.g. libk4a to stream from Azure Kinect).
- Build the C++ vcp libraries and corresponding Python3 bindings.
- Build the example applications and prepare the virtual environment for Python demos.

If you prefer to do it on your own, crank up CMake:

$ cd <VCP_ROOT_DIR>
$ mkdir build && cd build
$ cmake -DVCP_BUILD_PYTHON=ON ..
$ make -j install

The default install location (for make install) of vcp is <VCP_ROOT_DIR>/gen.
- Public C++ headers are inside <VCP_ROOT_DIR>/gen/include.
- vcp library files are inside <VCP_ROOT_DIR>/gen/lib.
- The Python3 package is located at <VCP_ROOT_DIR>/gen/vcp.

Tools

This repository comes with a few "tools", i.e. standalone applications that go beyond simple demos/examples. Currently (as of Jan/2020), there are only python applications available, which you can find at <VCP_ROOT_DIR>/examples/python3/tools.

Set up the virtual environment. If you didn't use the ./build-scripts/build-X.sh script to prepare the library, you should run:
```
$ cd <VCP_ROOT_DIR>/examples/python3
$ ./prepare_environment_py3.sh
$ source .venv3/bin/activate
$ cd tools
```
Extrinsic multi-camera calibration. For partially overlapping multi-camera setups, you can use the calibrate-extrinsics.py UI to estimate the camera poses using AprilTags.
For example, calibrating two Azure Kinects via python tools/calibrate-extrinsics.py ../data/data-best/kinects.cfg 225 --max-depth 10000 --max-ir 255 looks like this (depth measurements are visualized as surface normals, reflectivity of the infrared stream is shown as heatmap, TODO explain (?)):
3D image plots. Plot a single image (plot-image.py) or an image sequence (plot-image-sequence.py) by interactively adjusting the camera extrinsics.
Image abstraction: cartoonification, pixelation, etc. can be experimented with via cartoonify.py.

Examples

Besides the more complex tools, there are also simple demos showcasing the library capabilities.

C++

The C++ applications at <VCP_ROOT_DIR>/examples/cpp demonstrate how you can use vcp from your own CMake projects. After building the vcp library, building these examples is as easy as:
```
$ cd <VCP_ROOT_DIR>/examples
$ mkdir build && cd build
$ cmake ..
$ make -j
```
Highly recommended examples (best/well documented, useful functionality):
- best_demo

Python

You can find Python3 examples for all modules at <VCP_ROOT_DIR>/examples/python3.

$ cd <VCP_ROOT_DIR>/examples/python3
# Set up the virtual environment
$ ./prepare_environment_py3.sh
$ source .venv3/bin/activate
$ python imvis_demo.py

Highly recommended examples (best/well documented, useful functionality):
- bgm_demo.py - Usage example of the background subtraction module.
- geometry_demoy.py - Usage example of the math2d and math3d modules.
- imutils_demo.py - Usage example of the imutils (image manipulation) module.
- imvis_demo.py - Usage example for visualization utilities within the imvis module.

Tests

While all of vcp has been tested "in-the-wild", unit tests are rather sparse, unfortunately. Especially for the "best effort streaming" module, tests become quite difficult to automate (threading + the need for the specific hardware connected to the test server).

C++

Testing the C++ core library requires gtest:

$ sudo apt-get install libgtest-dev

# This package does not provide binaries, so look for the installed
# source at /usr/src. It should be (Ubuntu 18.04) at /usr/src/googletest.
$ cd /usr/src/googletest
$ sudo cmake CMakeLists.txt
$ sudo make

# Copy or symlink googlemock/gtest/libgtest.a 
# and googlemock/gtest/libgtest_main.a to your /usr/lib folder
$ sudo cp googlemock/gtest/*.a /usr/lib

Now vcp can be tested:

$ cd <VCP_ROOT_DIR>/build

# Enable tests and link the gtest libraries
$ cmake -DVCP_BUILD_TESTS=ON ..
$ make test 

# Or, if you prefer:
$ ctest -V

Python

You can find the Python3 tests at <VCP_ROOT_DIR>/examples/python3, i.e. all files following the pattern test_*.py.

Testing requires pytest:

$ cd <VCP_ROOT_DIR>/examples/python3
$ source .venv3/bin/activate
$ pip install pytest
$ pytest

snototter/vitocpp

vitocpp/vcp

What is it good for?

Repository Contents

Installation

Tools

Examples

C++

Python

Tests

C++

Python

TODOs