ICL is a novel C++ computer-vision library developed in the neuroinformatics group of the University of Bielefeld. It unifies both performance and user friendliness. ICL provides a large set of simple-to-use classes and functions to facilitate development of complex computer vision applications. A simple application for image acquisition and visualization can be written in less than 15 lines of C++ code.
During the design and development process, the following main goals took center stage:
ICL can optionally be linked against the Intel IPP-Library in order to enhance it's processing speed significantly. Most functions are implemented as Intel IPP wrappers internally but we also provide fallback implementations for data-types that are not supported by Intel IPP or for the case where Intel IPP is not available. ICL images can be used as shallow wrappers around existing data structures and their raw-data can be accessed directly. By this means, image processing applications can be implemented without any overhead for data-conversion or copying.
Object-orientated programming (OOP) in C++ provides both high performance due to processor-close programming, as well as a high abstraction level, due to the inherent features of object orientation. In particular, inheritance, data/function encapsulation, as well as function- and class-templating are used for ICL's implementation.
All external software dependencies are purely optional. Therefore, ICL's image structures and a large set of its functions and classes can be used without installing any 3rd-party libraries. By this means, you can develop your image processing algorithms with a slim version of ICL and link your code against a full featured ICL afterwards, i.e., when you need to use a certain camera type.
ICL is written in C++ without using compiler dependent statements like #pragma. Furthermore, we use the GNU-Autotools for it's building, which allows us to compile ICL on linux/unix based systems directly. ICL has already been compiled successfully under Linux and MacOS-X and we plan to provide a Windows build as well.
In contrast to the OpenCV library, we did not only concentrate on providing image-processing-related functions and tools. ICL also provides a large set of ready-to-use and well suited utility-classes and functions, e.g., for program-argument evaluation, or for object-oriented vector and matrix algebra. In particular, the ICLQt-package provides a powerful GUI-creation and image visualization and annotation framework.
Ubuntu packages can be obtained from the Releases page or by using the ICL PPA:
sudo add-apt-repository ppa:iclcv/icl
sudo apt-get update
sudo apt-get install icl-toolsThe ICL build is divided into four packages:
icl-core- Image Component Libraryicl-dev- ICL headers and project creation toolsicl-doc- ICL sphinx manual and api documentationicl-tools- ICL Applications
The packages are built with PCL features enabled.
Users of trusty need to add a third party PPA to their system as described here:
sudo add-apt-repository ppa:v-launchpad-jochen-sprickerhof-de/pcl
sudo apt-get update
# installing icl-core will automatically pull this dependency
sudo apt-get install libpcl-allWe provide Homebrew recipes which can be used to install ICL in three different flavours:
# has to be done just once
$ brew tap iclcv/homebrew-formulas
# enables features of OpenCV, Qt, OpenGL, ImageMagick, LibAV, LibDC and LibEigen
$ brew install icl
# base features plus additional functionality based on rsb, protobuf, freenect, pcl and bullet
$ brew install icl --with-extra
# extra features plus libusb, zmq and openni support
brew install icl --with-full
Windows MSI installers for Win32 or Win64 can be downloaded from the AppVeyor CI-Servers (see below). Users to have to install 3rd-party dependencies (pthreads-win32, Qt5, Visual Studio Redistributables) to work with the contained binaries.
Prebuilt packages can be obtained/installed from the following channels:
| OS | Channel | Target |
|---|---|---|
| Ubuntu | Launchpad | most recent: disco |
| OSX | Homebrew | |
| Windows | MSI (Win64/Win32) | Visual Studio 2017 |
These distributions have been built with the following features enabled:
| Feature | Ubuntu | OSX | Windows |
|---|---|---|---|
| APPS | ✓ | ✓ | ✓ |
| DEMOS | ✓ | ✓ | ✓ |
| EXAMPLES | ✓ | ✓ | ✓ |
| IPP/MKL | ✗ | ✗ | ✗ |
| QT | ✓ | ✓ | ✓ |
| OpenCV | ✓ | ✓ | ✓ (64bit) |
| OpenGL | ✓ | ✓ | ✗ |
| ImageMagick | ✓ | ✓ | ✗ |
| LibAV | ✓ | ✓ | ✗ |
| LibDC | ✓ | ✓ | ✗ |
| Eigen3 | ✓ | ✓ | ✗ |
| PCL | ✓ | ✓* | ✗ |
| Bullet3 | ✓ | ✓* | ✗ |
| Freenect | ✓ | ✓* | ✗ |
| OpenNI | ✓ | ✓** | ✗ |
| ZMQ | ✓ | ✓** | ✗ |
| LibUSB | ✓ | ✓** | ✗ |
| Video4Linux | ✓ | ✗ | ✗ |
| OpenCL | ✓ | ✗ | ✗ |
| RSB | ✗ | ✓** | ✗ |
| RSC | ✗ | ✓** | ✗ |
| PROTOBUF | ✗ | ✓** | ✗ |
- Remark for Homebrew installations:
*require the install flag--with-extraand**requires the install flag--with-full.
To build the minimal version of ICL, the following packages are mandatory:
cmakelibjpeg-devlibpng-dev
With a Debian-based operating system, these requirements can be installed using
apt:
$ sudo apt-get install cmake libjpeg-dev libpng-dev
Clone this repository to your workspace, cd into the project folder and build the
libraries with cmake
$ cd /path/to/workspace
$ git clone https://github.com/iclcv/icl.git
$ mkdir icl/build # create build folder
$ cd icl/build
$ cmake ..
$ make # optionally with -j for parallel jobs
$ make install # install ICL
However, the strength of ICL lies in its rich set of features which can be tailored according to your need. The instruction below will install dependencies and configure the build tool in a way to makes use of 3rd party libraries such as Qt, OpenCV, Point Cloud Library (PCL) and many more. It will also build ICL applications for fast computer vision prototyping as well as demo code and documentation examples.
$ sudo apt-get install cmake libpng-dev libjpeg-dev qtmultimedia5-dev \
libqt5opengl5-dev libglew-dev libopencv-dev ocl-icd-opencl-dev \
opencl-headers libeigen3-dev libmagick++-dev libfreenect-dev libxine2-dev \
libpcl-dev
# clone and create build folder
$ cmake .. -DBUILD_WITH_EIGEN3=TRUE -DBUILD_WITH_V4L=TRUE \
-DBUILD_WITH_LIBFREENECT=TRUE -DBUILD_WITH_MESASR=TRUE \
-DBUILD_WITH_QT=TRUE -DBUILD_WITH_OPENCL=TRUE \
-DBUILD_WITH_LIBDC=TRUE -DBUILD_WITH_IMAGEMAGICK=TRUE \
-DBUILD_EXAMPLES=ON -DBUILD_DEMOS=ON \
-DBUILD_WITH_OPENCV=TRUE -DBUILD_APPS=ON \
-DBUILD_WITH_PCL=TRUE
$ make # build icl
Let's dig bit deeper to get to know the meanings behind those flags, shall we?
Below you will find a list of features and the cmake flags required to build these features as well as the required Ubuntu packages.
The well known Qt Library is used for ICL’s rapid GUI creation toolkit. Actually Qt is also a prerequisite for most ICL applications and for the whole ICLQt module. We strongly recommend to have at least Qt support when building ICL.
- flag:
-DBUILD_WITH_QT=TRUE - dependencies:
qtmultimedia5-dev libqt5opengl5-dev libglew-dev
We use OpenCV mainly in order to provide a compatibility interface that converts OpenCV’s common image data type cv::Mat into ICL’s images types and vice versa.
- flag:
-DBUILD_WITH_OPENCV=TRUE - dependencies:
libopencv-dev
OpenCL is used to significantly speed up a set of processing units using the computing units of graphics cards or other OpenCL platforms. We mainly use it for point cloud processing units located in the ICLGeom module.
- flag:
-DBUILD_WITH_OPENCL=TRUE - dependencies:
ocl-icd-opencl-dev opencl-headers
Improves calculation speed.
- flag:
-DBUILD_WITH_EIGEN3=TRUE - dependencies:
libeigen3-dev
ImageMagick is used to provide a large set of support image types. Most types are supported in both reading and writing.
- flag:
-DBUILD_WITH_IMAGEMAGICK=TRUE - dependencies:
libmagick++-dev
For most usb-based cameras/Webcams on linux, V4L2 can be used. While v4l2 used to be a part of the kernel-Headers in older linux version, nowerdays, it is shipped as an additional library that can usually be installed conveniently using a package manager.
- flag:
-DBUILD_WITH_V4L=TRUE
The libfreenect provides a lightweight interface for grabbing images from Microsoft Kinect cameras. The library allows to grab color, depth and IR-images and to set some internal camera properties.
- flag:
-DBUILD_WITH_LIBFREENECT=TRUE - dependencies:
libfreenect-dev
- flag:
-DBUILD_WITH_LIBDC=TRUE
Build with ICL tools
- flag:
-DBUILD_APPS=ON
Build demos
- flag:
-DBUILD_DEMOS=ON
Build doc examples
- flag:
-DBUILD_EXAMPLES=ON
We strongly recommend to have at least Qt support when building ICL. But there is more! Please refer to the documentation of optional features for a complete list which includes Xine, Kinect 2, SwissRanger and more.
To run tests, ICL needs to be configured with -DBUILD_TESTS=ON.
This will create new test targets for each ICL module an automatically execute them after they have been built with make.
Test build and execution can also be triggered manually.
The individual test targets will be build with make tests.
To run the tests make test has to be executed.
$ make tests # build ICL and test targets
[ 10%] Built target ICLUtils
[...]
[100%] Built target tests_iclcore
[100%] Built target tests_iclfilter
[100%] Built target tests_iclio
$ make test # run the tests
Running tests...
Test project /.../build
Start 1: tests_iclutils
1/17 Test #1: tests_iclutils .......................... Passed 0.04 sec
[...]
Start 17: tests_iclmarkers
17/17 Test #17: tests_iclmarkers ........................ Passed 0.33 sec
100% tests passed, 0 tests failed out of 17
Total Test time (real) = 2.01 sec
Tests can also be run individually:
$ build/ICLMath/tests_iclmath
[==========] Running 8 tests from 1 test case.
[----------] Global test environment set-up.
[----------] 8 tests from DynMatrixTest
[ RUN ] DynMatrixTest.EmptyConstructor
[ OK ] DynMatrixTest.EmptyConstructor (0 ms)
[ .... ]
[ RUN ] DynMatrixTest.ColumnOp
[ OK ] DynMatrixTest.ColumnOp (0 ms)
[----------] 8 tests from DynMatrixTest (3 ms total)
[----------] Global test environment tear-down
[==========] 8 tests from 1 test case ran. (3 ms total)
[ PASSED ] 8 tests.
Coverage targets can be build individually or for the whole library:
$ make coverage_iclmath # basic pattern is coverage_<icl_module_name>
$ make coverage # builds all coverage targets but will take some time
Note that coverage results may be inaccurate due to tracking obstacles related to macros and inline functions.
For bug reports and other issues, please open an issue on GitHub.