/******************************************************************** ** Image Component Library (ICL) ** ** ** ** Copyright (C) 2006-2013 CITEC, University of Bielefeld ** ** Neuroinformatics Group ** ** Website: www.iclcv.org and ** ** http://opensource.cit-ec.de/projects/icl ** ** ** ** File : ICLCore/src/ICLCore/Core.h ** ** Module : ICLCore ** ** Authors: Christof Elbrechter ** ** ** ** ** ** GNU LESSER GENERAL PUBLIC LICENSE ** ** This file may be used under the terms of the GNU Lesser General ** ** Public License version 3.0 as published by the ** ** ** ** Free Software Foundation and appearing in the file LICENSE.LGPL ** ** included in the packaging of this file. Please review the ** ** following information to ensure the license requirements will ** ** be met: http://www.gnu.org/licenses/lgpl-3.0.txt ** ** ** ** The development of this software was supported by the ** ** Excellence Cluster EXC 277 Cognitive Interaction Technology. ** ** The Excellence Cluster EXC 277 is a grant of the Deutsche ** ** Forschungsgemeinschaft (DFG) in the context of the German ** ** Excellence Initiative. ** ** ** ********************************************************************/ #pragma once #include #include #include #include #include #include /** \defgroup TYPES Common Data Type Definitions \defgroup GENERAL General Utility and Support Functions \defgroup IMAGE Image Classes and Support Functions ICL is a C++ image processing library, developed in the Neuroinformatics Group at the University of Bielefeld in Germany. ICL provides a large set of features for image acquisition, image processing and image visualization. During the design and development process, the following main goals took center stage: - Optimal Performace (ensured by internal use of Intel IPP, see \ref IPP_MKL) - Simple and easy to use C++-interface (see \ref EXAMPLE) - Platform-Independence (currently linux and MacOS-X are supported) - No compulsory software dependencies (see \ref EXTERNAL_DEPS) ICL provides all necessary building blocks for the development of complex computer-vision applications. \section EXAMPLE Simple Viewer Application for Arbitrary Camera Sources
\code #include GUI gui; GenericGrabber grabber; void init(){ grabber.init(pa("-i")); gui << Image().handle("image") << Show(); } void run(){ gui["image"] = grabber.grab(); } int main(int n, char **args){ return ICLApp(n,args,"-input|-i(2)",init,run).exec(); } \endcode \image html viewer.jpg
- Save this file as viewer.cpp - Setup your PKG_CONFIG_PATH variable - Compile with CXXFLAGS=`pkg-config --libs --cflags icl` make viewer - Plug in a camera - Run your application e.g. with ./viewer -input unicap '*' More examples for using ICL are given in the online ICL-tutorial on \section THE_IMAGE The Image Classes
We use inheritance and class templates for ICL's image representation: The ImgBase class defines an abstract interface, that manages all image information except image pixel data. These abstract image features are: - size (in pixels) - channel count (see channel concept) - type of pixels (see data types) - color format (see color formats) - raw image data access - Region of Interest (see Region of Interests \ref ROI (ROI)) - a time stamp The ImgBase interface is implemented by the template class Img which implements all abstract ImgBase-functions and aggregates a vector of planar image channel data pointers. Internally, these channel data pointers use reference counting to allow shallow image copies. \n Img's copy-constructor and assignment operator use shallow copy on default! The Img template also adds functions for type-safe data access: - access to channel data pointers (using getData(channel) or begin(channel)) - extraction of single image channels (using operator [](int)) - extraction of single image pixels (using operator()(x,y,channel-index) for single values or operator()(x,y) to obtain a pixel vector) - iterator based access to data of a given channel (using begin(channel) and end(channel)) - iterator based access to the ROI-pixels of a given channel (using beginROI(channel) and endROI(channel)) \image html image-sketch.png "A sketch of ICL's image type Img"
\section SEC_DATA_ORIGN Data Origin As most common image formats image processing use the upper left image corner as data origen, ICL follows this convention as well. Howerver, many image operation like filtering or thresholding works without regarding the image contents at all. Nonetheless, we suggest to use this standard, as it is particularly important for I/O-routines or image visualization and - not at least - whenever discussing about ICL images. \section Channel-Concept The Img treats images as a stack of image slices -- channels. Channels can be shared by multiple Img instances, which is especially important for fast shallow images copies. Actually, it is possible to freely compose existing channels (within several "parent images") to another new image. Attention: The newly composed image shares its channel data with the original images, such that modifications will effect all images equally. In order to get an independent image a deep-copy as well as a so called detach method are provided. The latter replaces the "shared" image channel(s) with new independent ones. Shared channel data are stored using the boost-like shared pointer class SmartPtr, which uses reference counting for autonomous garbage collection in order to realease unused image channels. \section DATA_TYPES Data-Types The Img template is not implemented completely inline to reduce compilation expense. Therefore, the Img template is instantiated for the following types T - icl8u 8bit unsigned char - icl16s 16bit signed integer (short) - icl32s 32bit signed integer (int) - icl32f 32bit single precision float (float) - icl64f 64bit double precision float (double) Derived from this types, Img-classes are predefined as follows - Img : public ImgBase typedef'd to Img8u - Img : public ImgBase typedef'd to Img16s - Img : public ImgBase typedef'd to Img32s - Img : public ImgBase typedef'd to Img32f - Img : public ImgBase typedef'd to Img64f Each of these data types has several advantages/disadvantages. The greatest disadvantage of the integer types, is their bounded range (e.g. 0-255 for icl8u), which has the effect, that all information has to be scaled to this range, and all image processing functions must take care that no range-overflow occurs during calculation. Furthermore the limited range may cause loss of information - particular in complex systems. However integer types can often be processed significantly faster. In particular the use of 8-bit unsigned integer images relieves the the memory interface due to it's lower memory usage. A nice rule of thumb is: If processing speed matters, use Img8u images whenever it's possible and avoid Img64f because double processing is much slower on (still common) 32 bit machines (as long as you do not really need double precision) \section ROI Region of Interest (ROI) Each image can be set up with a rectangular region of interest. Nearly all algorithms work only on the pixels within the ROI. If a function does not support ROI handling it will be noticed in the documentation. There are several ways to realize ROI handling in functions. The most common way is to use the ImgIterator with can be accessed using the STL-style functions beginROI(channel) and endROI(channel). \section Color Formats An ImgBase image provides information about the (color) format, that is associated with the image data represented by the images channels. Color is written in brackets, as not all available formats imply color-information. The most known color space is probably the RGB color space. If an ImgBase image has the format formatRGB, than this implies the following: - the image has exactly 3 channels - the first channel contains RED-Data in range [0,255] - the second channel contains GREEN-Data in range [0,255] - the third channel contains BLUE-Data in range [0,255] All additional implemented functions and classes regard this information. The currently available Img formats are member of the enum Format. A special format: formatMatrix can be used for arbitrary purpose. \section CONST_SEC Const-Concept ICL Images use the const concept of C++ to ensure pixel data of const Images (of type const ImgBase or more precisely const Img) is not changed, i.e. it is only accessible for reading. Unfortunately this leads to a conflict with the "shallow-copy" concept of ICL images. \code void func(const Img8u &image){ // given image is const -> data must not be changed Img8u x = image; // x is a shallow copy of image (data is shared) x.clear(); // this affects also the data of image (which shall not // be permitted } \endcode To avoid this conflict, we tried to forbid creating un-const shallow copies of const images by implementing no default copy constructor: \code Img(const Img &other) {... } \endcode but an un-const version of this: \code Img(Img &other) {... } \endcode Here we face some GCC related problem, because gcc is not able for an implicit cast of an Img to an Img& in constructor calls: \code template class Img{ ... }; Img8u create_image(){ return Img8u(); } int main(){ Img8u a = create_image(); } \endcode Here, the compiler gives error: "Can't find constructor Img(Img)". In fact, this constructor can not exist: it must have the following syntax: Img(Img&) Probably further gcc versions will fix this problem! Until then, we accept the const leak at constructor and assignment operator and reimplemented them as ..(const Img &other) \section IPP_MKL IPP/MKL-optimization The Intel Integrated Performance Primitives (Intel IPP) and the Intel Math Kernel Library (Intel MKL) are assembler libraries that provide a C-interface to a large set of highly optimized and hardware accelerated functions for image processing, and other numerical problems for all processors providing MMX and SSE instruction sets, i.e. most common Intel and AMD processors. As far as we know, Intel IPP and Intel MKL can be used freely for non-commercial use, but not for research. Fortunately, IPP/MKL support is purely optional. Therefore you can simply develop your application with an ICL-build without IPP/MKL-optimization and re-link it against an optimized ICL-build lateron. \subsection IPP Intel IPP If Intel IPP is available, it is highly integrated into ICL: - a large number of image processing functions are IPP-accelerated - iclXX data types are typedef'ed to ippXX data types rather than to default types from the \ header - icl::Size extends the IppSize struct which enables the programmer to pass an icl::Size instance directly to an ipp-function call - the same is true for icl::Point and icl::Rect - all ipp-headers will we available, so IPP-functions can be used directly We tuned the Img-class to facilitate the use of IPP functions. \subsection MKL Intel MKL In contrast to the matrix package for small matrices, which is optimized for matrices up to dimensions of 6x6, Intel MKL is optimized for larger matrices. As under certain conditions, MKL is more then 100 times faster, we decided to add MKL support as well. However, MKL is currently only used in the implementation of some DynMatrix multiplication functions in the ICLUtils package. \section ICLCore Modules If you like to explore the ICLCore documentation by your own, take a look a the following sub modules:\n -# \ref TYPES -# \ref GENERAL -# \ref IMAGE -# \ref STRUTILS \section EXTERNAL_DEPS Optional 3rd Party Dependencies The list of 3rd party dependencies is given on