Image Component Library (ICL)
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Classes | Typedefs | Enumerations | Functions
icl::core Namespace Reference

Classes

class  AbstractCanvas
class  BayerConverter
 Utiltity class for bayer pattern conversion. More...
class  CCLUT
class  Channel
 Utility helper class for faster and more convenient access to single channel image data. More...
struct  ChromaAndRGBClassifier
 Combination classifier using RG-chroma. as well as RGB-thresholded reference color classifiation. More...
struct  ChromaClassifier
 Classifier interface using RG-chromaticity space and two parables. More...
class  Converter
 General Image Converter. More...
struct  DataSegment
 The DataSegment class defines a strided data segment (or 1D or 2D ordred array of vectors) More...
struct  DataSegment< T, 1 >
 template specialization for data-segments, where each entry is just 1D More...
struct  DataSegmentBase
 Abstract data segment class. More...
class  FixedConverter
 Special converter "producing" images with fixed parameters. More...
class  ImageRenderer
struct  ImageSerializer
 Utility class for binary Image Serialization. More...
class  Img
 The Img class implements the ImgBase Image interface with type specific functionalities \. More...
struct  ImgBasePtrPtr
 utility class that helps for an implicit conversion between Img<T>* to ImgBase** More...
class  ImgBase
 ImgBase is the Image-Interface class that provides save access to underlying Img-template \. More...
class  ImgBorder
 Class to setup an images border pixels. More...
class  ImgBuffer
 Singelton class that provides access to reusable temporary images. More...
class  ImgIterator
 Iterator class used to iterate through an Images ROI-pixels. More...
class  ImgParams
 The ImgParams class stores all image parameters \. More...
class  Line
 The ICLs abstract line class describing a line from Point "start" to Point "end". More...
class  Line32f
 The ICLs abstract line class describing a line from Point "start" to Point "end". More...
class  LineSampler
 Utility class for line sampling. More...
struct  CvMatDelOp
 Utility Delete Operator used within CvMatWrapper. More...
class  CvMatWrapper
 Utility class that wraps around a CvMat of type CV_32FC1. More...
struct  Parable
 Utility class for the parable-based chromaticity segmentation. More...
class  PixelRef
 Pixel-Type class for copying image pixles to image pixels. More...
struct  PseudoColorConverter
 Utility class for speudocolor conversion. More...

Typedefs

typedef math::FixedColVector
< icl8u, 3 > 
Color
 Default color type of the ICL.
typedef math::FixedColVector
< icl8u, 3 > 
RGB
 RGB Color.
typedef math::FixedColVector
< icl8u, 4 > 
RGBA
 RGBA Color.
typedef math::FixedColVector
< icl32f, 3 > 
Color32f
 Special color type for float valued colors.
typedef math::FixedColVector
< icl8u, 4 > 
Color4D
 Special color type for e.g. rgba color information.
typedef math::FixedColVector
< icl32f, 4 > 
Color4D32f
 Special color type for e.g. rgba color information (float)
typedef Img< icl8uImg8u
 typedef for 8bit integer images
typedef Img< icl16sImg16s
 typedef for 16bit integer images
typedef Img< icl32sImg32s
 typedef for 8bit integer images
typedef Img< icl32fImg32f
 typedef for 32bit float images
typedef Img< icl64fImg64f
 typedef for 64bit float images

Enumerations

enum  ccimpl {
  ccAvailable = 0, ccEmulated = 1, ccAdapted = 2, ccUnavailable = 3,
  ccImpossible = 4
}
 Internal used type, that describes an implementation type of a specific color conversion function. More...
enum  DepthPreference { PREFERE_SRC_DEPTH, PREFERE_DST_DEPTH }
 Modes that define whether to prefer the source image's or the destination image's depth. More...
enum  depth {
  depth8u = 0, depth16s = 1, depth32s = 2, depth32f = 3,
  depth64f = 4, depthLast = depth64f
}
 determines the pixel type of an image (8Bit-int or 32Bit-float) More...
enum  format {
  formatGray = 0, formatRGB = 1, formatHLS = 2, formatYUV = 3,
  formatLAB = 4, formatChroma = 5, formatMatrix = 6, formatLast = formatMatrix
}
 determines the color-format, that is associated with the images channels More...
enum  scalemode { interpolateNN = IPPI_INTER_NN, interpolateLIN = IPPI_INTER_LINEAR, interpolateRA = IPPI_INTER_SUPER }
 for scaling of Img images theses functions are provided More...
enum  axis { axisHorz = ippAxsHorizontal, axisVert = ippAxsVertical, axisBoth = ippAxsBoth }
 for flipping of images More...

Functions

ICLCore_API void cc (const ImgBase *src, ImgBase *dst, bool roiOnly=false)
 Color conversion from source to destination image.
ICLCore_API bool lut_available (format srcFmt, format dstFmt)
 returns whether a lookup table was already created for src and dst format
ICLCore_API void createLUT (format srcFmt, format dstFmt)
 Internally creates a lookup table to accelerate conversion between given formats.
ICLCore_API void releaseLUT (format srcFmt, format dstFmt)
 releases the internal lookup table created with createLUT
ICLCore_API void releaseAllLUTs ()
 releases all lookup tables that were created with createLUT
ICLCore_API std::string translateCCImpl (ccimpl i)
 translates a ccimpl enum into a string representation
ICLCore_API ccimpl translateCCImlp (const std::string &s)
 translates the string represenation of a
ICLCore_API ccimpl cc_available (format srcFmt, format dstFmt)
 returns the ccimpl state to a conversion from srcFmt to dstFmt
ICLCore_API void convertYUV420ToRGB8 (const unsigned char *pucSrc, const utils::Size &s, Img8u *poDst)
 Convert an image in YUV420-format to RGB8 format (ippi accelerated)
template<class S , class D >
ICLCore_API void planarToInterleaved (const Img< S > *src, D *dst, int dstLineStep=-1)
 Convert an 4 channel Img8u into Qts ARGB32 interleaved format.
template<class S , class D >
ICLCore_API void interleavedToPlanar (const S *src, Img< D > *dst, int srcLineStep=-1)
 Converts interleaved image data into planar representation.
ICLCore_API void cc_util_rgb_to_yuv (const icl32s r, const icl32s g, const icl32s b, icl32s &y, icl32s &u, icl32s &v)
 converts given (r,g,b) pixel into the yuv format
ICLCore_API void cc_util_yuv_to_rgb (const icl32s y, const icl32s u, const icl32s v, icl32s &r, icl32s &g, icl32s &b)
 converts given (y,u,v) pixel into the rgb format
ICLCore_API void cc_util_rgb_to_hls (const icl32f r255, const icl32f g255, const icl32f b255, icl32f &h, icl32f &l, icl32f &s)
 converts given (r,g,b) pixel into the hls format
ICLCore_API void cc_util_hls_to_rgb (const icl32f h255, const icl32f l255, const icl32f sl255, icl32f &r, icl32f &g, icl32f &b)
 converts given (h,l,s) pixel into the rgb format
ICLCore_API void cc_util_rgb_to_chroma (const icl32f r, const icl32f g, const icl32f b, icl32f &chromaR, icl32f &chromaG)
 converts given (r,g,b) pixel into the RG-chroma format
void cc_util_rgb_to_lab (const icl32f &r, const icl32f &g, const icl32f &b, icl32f &L, icl32f &A, icl32f &B)
 converts given (r,g,b) pixel into the Lab format
const ColoriclCreateColor (std::string name)
Color darker (const Color &c, double factor=0.8)
 Creates a (by default 20 percent) darker color.
Color lighter (const Color &c, double factor=0.8)
 Creates a (by default 20 percent) lighter color.
Color ICLCore_API color_from_string (const std::string &name)
 Parses a color string representation into a color structur.
ICLCore_API std::vector
< utils::Point
convexHull (std::vector< utils::Point > P)
 convex hull monotone chain algorithm for int-points
ICLCore_API std::vector
< utils::Point32f
convexHull (std::vector< utils::Point32f > P)
 convex hull monotone chain algorithm for float-points
ICLCore_API ImgBaseimgNew (depth d=depth8u, const ImgParams &params=ImgParams::null)
 create a new image instance of the given depth type and with given parameters
ImgBaseimgNew (depth d, const utils::Size &size, format fmt, const utils::Rect &roi=utils::Rect::null)
 creates a new Img (see the above function for more details)
ImgBaseimgNew (depth d, const utils::Size &size, int channels=1, const utils::Rect &roi=utils::Rect::null)
 creates a new Img (see the above function for more details)
ImgBaseimgNew (depth d, const utils::Size &size, int channels, format fmt, const utils::Rect &roi=utils::Rect::null)
 creates a new Img (see the above function for more details)
ICLCore_API ImgBaseensureDepth (ImgBase **ppoImage, depth eDepth)
 ensures that an image has the specified depth
ICLCore_API ImgBaseensureCompatible (ImgBase **dst, depth d, const ImgParams &params)
 ensures that an image has given depth and parameters
ImgBaseensureCompatible (ImgBase **dst, depth d, const utils::Size &size, int channels, const utils::Rect &roi=utils::Rect::null)
 ensures that an image has given depth, size, number of channels and ROI
ImgBaseensureCompatible (ImgBase **dst, depth d, const utils::Size &size, format fmt, const utils::Rect &roi=utils::Rect::null)
 ensures that an image has given depth, size, format and ROI
ICLCore_API ImgBaseensureCompatible (ImgBase **dst, depth d, const utils::Size &size, int channels, format fmt, const utils::Rect &roi=utils::Rect::null)
 ensures that an image has given parameters
ICLCore_API ImgBaseensureCompatible (ImgBase **dst, const ImgBase *src)
 ensures that the destination image gets same depth, size, channel count, depth, format and ROI as source image
ICLCore_API int getChannelsOfFormat (format fmt)
 determines the count of channels, for each color format
template<class T >
depth getDepth ()
 getDepth<T> returns to depth enum associated to type T
ICLCore_API std::ostream & operator<< (std::ostream &s, const format &f)
 puts a string representation of format into the given stream
ICLCore_API std::ostream & operator<< (std::ostream &s, const depth &d)
 puts a string representation of depth into the given stream
ICLCore_API std::istream & operator>> (std::istream &s, format &f)
 puts a string representation of format into the given stream
ICLCore_API std::istream & operator>> (std::istream &s, depth &d)
 puts a string representation of depth into the given stream
ICLCore_API unsigned int getSizeOf (depth eDepth)
 return sizeof value for the given depth type
template<class T >
void copy (const T *src, const T *srcEnd, T *dst)
 moves data from source to destination array (no casting possible)
template<class srcT , class dstT >
void convert (const srcT *poSrcStart, const srcT *poSrcEnd, dstT *poDst)
 moves value from source to destination array (with casting on demand)
template<class T >
ICLCore_API void getMinAndMax (T a, T b, T c, T &minVal, T &maxVal)
 function, that calculates the mininum and the maximum value of three value
ICLCore_API std::vector< double > mean (const ImgBase *poImg, int iChannel=-1, bool roiOnly=false)
 Computes the mean value of a ImgBase* ingroup MATH.
ICLCore_API std::vector< double > variance (const ImgBase *poImg, const std::vector< double > &mean, bool empiricMean=true, int iChannel=-1, bool roiOnly=false)
 Compute the variance value of an image a with given mean.
ICLCore_API std::vector< double > variance (const ImgBase *poImg, int iChannel=-1, bool roiOnly=false)
 Compute the variance value of an image a.
ICLCore_API std::vector< double > stdDeviation (const ImgBase *poImage, int iChannel=-1, bool roiOnly=false)
 Compute the std::deviation of an image.
ICLCore_API std::vector< double > stdDeviation (const ImgBase *poImage, const std::vector< double > mean, bool empiricMean=true, int iChannel=-1, bool roiOnly=false)
 Compute the std::deviation of an image with given channel means.
ICLCore_API std::vector
< std::pair< double, double > > 
meanAndStdDev (const ImgBase *image, int iChannel=-1, bool roiOnly=false)
 Calculates mean and standard deviation of given image simultanously.
ICLCore_API std::vector< int > channelHisto (const ImgBase *image, int channel, int levels=256, bool roiOnly=false)
 computes the color histogramm of given image channel
ICLCore_API std::vector
< std::vector< int > > 
hist (const ImgBase *image, int levels=256, bool roiOnly=false)
 computes the color histogramm of given image
template<class T >
ImgBasePtrPtr< T > bpp (Img< T > *image)
 utility function to cast an Img<T> implicitly into an ImgBase **
template<class T >
ImgBasePtrPtr< T > bpp (Img< T > &image)
 utility function to cast an Img<T>* implicitly into an ImgBase **
template<class T >
static T p2o (T *ptr)
 Conversion function to transform a pointer into an object.
template<class ImgType >
const ImgType * combineImages (const std::vector< const ImgType * > &vec)
 Combine several images using shallow copy.
template<class ImgType >
ImgType * combineImages (const std::vector< ImgType * > &vec)
 Combine several images using shallow copy. Non-const version.
template<class T >
void deepCopyChannel (const Img< T > *src, int srcC, Img< T > *dst, int dstC)
 Copies the channel from one image to another.
template<class S , class D >
void convertChannel (const Img< S > *src, int srcC, Img< D > *dst, int dstC)
 copies/converts the data from one image to another image (IPP-OPTIMIZED)
template<class T >
void clearChannelROI (Img< T > *im, int c, T clearVal, const utils::Point &offs, const utils::Size &size)
 sets an arbitrary image ROI to a given value
template<class T >
void deepCopyChannelROI (const Img< T > *src, int srcC, const utils::Point &srcOffs, const utils::Size &srcSize, Img< T > *dst, int dstC, const utils::Point &dstOffs, const utils::Size &dstSize)
ICLCore_API std::ostream & operator<< (std::ostream &s, const ImgBase &image)
 puts a string representation of the image into given steam
ICLCore_API std::ostream & operator<< (std::ostream &os, const ImgParams &p)
 ostream operator SIZExCHANNELS@FORMAT.ROI
ICLCore_API std::istream & operator>> (std::istream &is, ImgParams &p)
 istream operator
ICLCore_API std::ostream & operator<< (std::ostream &s, const Line &l)
 ostream operator (start-x,start-y)(end-x,end-y)
ICLCore_API std::istream & operator>> (std::istream &s, Line &l)
 istream operator
ICLCore_API std::ostream & operator<< (std::ostream &s, const Line32f &l)
 ostream operator (start-x,start-y)(end-x,end-y)
ICLCore_API std::istream & operator>> (std::istream &s, Line32f &l)
 istream operator
ICLCore_API ImgBaseipl_to_img (CvArr *src, ImgBase **dst=0, DepthPreference e=PREFERE_SRC_DEPTH) throw (utils::ICLException)
 Convert OpenCV IplImage to ICLimage.
ICLCore_API IplImage * img_to_ipl (const ImgBase *src, IplImage **dst=0, DepthPreference e=PREFERE_SRC_DEPTH) throw (utils::ICLException)
 Convert ICLimage to OpenCV IplImage.
ICLCore_API CvMat * img_to_cvmat (const ImgBase *src, CvMat *dst=0, int channel=0) throw (utils::ICLException)
 Copy single ICLimage channel to OpenCV single channel CvMat.
ICLCore_API IplImage * img_to_ipl_shallow (ImgBase *src, IplImage *dst=0) throw (utils::ICLException)
 Convert single channel ICLimage to OpenCV IplImage.
ICLCore_API CvMat * img_to_cvmat_shallow (const ImgBase *src, CvMat *dst=0) throw (utils::ICLException)
 Convert single channel ICLimage to OpenCV CvMat.
template<class T >
std::ostream & operator<< (std::ostream &str, const CvMatWrapper< T > &m)
 Overloaded ostream operator for the CvMat32fWrapper.

type conversion of channel ROIs

copies/converts the ROI data from one image to the ROI of another image (IPP-OPTIMIZED)

template<class S , class D >
void convertChannelROI (const Img< S > *src, int srcC, const utils::Point &srcOffs, const utils::Size &srcROISize, Img< D > *dst, int dstC, const utils::Point &dstOffs, const utils::Size &dstROISize)

scaling of channel ROIs

scales an image channels ROI into another images ROI (with implicit type conversion) (IPP-OPTIMIZED)

template<class T >
ICLCore_API void scaledCopyChannelROI (const Img< T > *src, int srcC, const utils::Point &srcOffs, const utils::Size &srcSize, Img< T > *dst, int dstC, const utils::Point &dstOffs, const utils::Size &dstSize, scalemode eScaleMode)
template<class T >
ICLCore_API void flippedCopyChannelROI (axis eAxis, const Img< T > *src, int srcC, const utils::Point &srcOffs, const utils::Size &srcSize, Img< T > *dst, int dstC, const utils::Point &dstOffs, const utils::Size &dstSize)
 mirror copy ROI data from one image to the ROI of another image (IPP-OPTIMIZED)
ICLCore_API void flippedCopy (axis eAxis, const ImgBase *poSrc, ImgBase **ppoDst=0)
 mirror copy of an image from source to destination image (1:1 copy)
ICLCore_API void flippedCopyROI (axis eAxis, const ImgBase *poSrc, ImgBase **ppoDst=0)
 mirror copy of an images ROI into a destination images ROI

Typedef Documentation

Default color type of the ICL.

Special color type for float valued colors.

Special color type for e.g. rgba color information.

Special color type for e.g. rgba color information (float)

RGB Color.

RGBA Color.


Enumeration Type Documentation

Internal used type, that describes an implementation type of a specific color conversion function.

Enumerator:
ccAvailable 

conversion is supported natively/directly

ccEmulated 

conversion is supported using the bridge format RGB

ccAdapted 

conversion is actually not possible but although performed ( like XXX to matrix )

ccUnavailable 

conversion is not implemented yet, but possible

ccImpossible 

conversion does not make sense (like croma to RGB )

Modes that define whether to prefer the source image's or the destination image's depth.

Enumerator:
PREFERE_SRC_DEPTH 

prefer source depth

PREFERE_DST_DEPTH 

prefer destination depth


Function Documentation

ICLCore_API void icl::core::cc ( const ImgBase *  src,
ImgBase *  dst,
bool  roiOnly = false 
)

Color conversion from source to destination image.

All color conversions of the ICL are tackled by this function. The destination images size is adapted to the source images size, as cc does not provide implicit scaling; Use the Converter class, also located in this package, for color conversion with implicit scaling instead.

Currently ICL supports the following color formats:

  • RGB (sRGB)
  • HLS
  • YUV
  • LAB
  • r-g-Chromaticity
  • Grayscale

Color Ranges

As default, the all ICL color spaces are represented in the full range of [0,255] in all depths. By this, we get the advantage of being able to treat all color images in the same way. The disadvantage is, that already existing color conversion routines must be adapted to scale each color component to that range.

sRGB, most common and default

Obviously, the RGB Color Model (or its absolute Version sRGB -> standard RGB) is one of the best known one by most of the users. Although many computer vision approaches are using other color spaces as HLS or LAB, the sRGB color space complies a kind of angle point for color conversion functions. So in most cases, the sRGB format forms a bridge format for conversion from one to another format (xxx->yyy ==> xxx->rgb followed by rgb->yyy ; Another bridge color space (XYZ) is not considered here). In term of efficiency of the color conversion code: Converting from or to RGB is fast, other conversion may be much slower.

YUV Color Space Conversion

The literature yuv color model conversion is mostly a bit confusing and far away from a kind of pseudocode, that can easily be converted to (fast) c++ code. The YUV Color model divides an incoming RGB signal into its luminance component (Y) and two chrominance components (U and V). The common yuv-color holds Y in the range [0,1], u in range [-0.436,0.436] and v in range [-0.615,0,615]. These different ranges compound implementing algorithms. Hence the color conversion functions of the ICL are adapted to scale the resulting values to the range [0,255] in all channels. Outgoing from the basic equation for converting rgb to yuv and back

        Y = 0.299*R + 0.587*G + 0.114*B
        U = -0.147*R - 0.289*G + 0.436*B = 0.492*(B- Y)
        V = 0.615*R - 0.515*G - 0.100*B = 0.877*(R- Y)
        R = Y + 1.140*V
        G = Y - 0.394*U - 0.581*V
        B = Y + 2.032*U
        

The formulas are adapted for using ranges [0,255]:

        Y = (0.299*R + 0.587*G + 0.114*B);  
        U = 0.56433408*(B-Y) + 127.5;
        V = 0.71326676*(R-Y) + 127.5;
        R = Y +               290.7   * v2;
        G = Y - 100.47 * u2 - 148.155 * v2;   with: u2 = 0.0034196078*U - 0.436;
        B = Y + 518.16 * u2;                   and  v2 = 0.0048235294*V - 0.615;
        

To avoid expensive floating point operations, the conversions can be optimized by creating a so called fixed point approximation of the above code:

        Y = ( 1254097*R + 2462056*G + 478151*B ) >> 22;  
        U = ( 2366989*(B-Y) + 534773760        ) >> 22;
        V = ( 2991658*(R-Y) + 534773760        ) >> 22;
        R = Y +  ( ( 290 * V2 ) >> 22 );
        G = Y -  ( ( 100  * U2 + 148 * V2) >> 22 ); with: U2 = 14343*U - 1828717; 
        B = Y +  ( ( 518 * U2 ) >> 22 );             and  V2 = 20231*v - 2579497; 
        

This approximation produces errors less 3/255, and runs up to 20% faster. A further optimization can be implemented using lookup tables.

The SSE-implementation uses the original floating point calculation, that is extended to match the value range [0,255]:

        Y = 0.299f*R + 0.587f*G + 0.114*B
        U = 0.492f*(B-Y) + 128.0f
        V = 0.877f*(R-Y) + 128.0f
        if(V < 0.0f) V = 0.0f;
        else if(V > 255.0f) V = 255.0f;
        R = Y + 1.140*(V - 128)
        G = Y - 0.394*(U - 128) - 0.581*(V - 128)
        B = Y + 2.032*(U - 128)
        R = clip(R, 0, 255);
        G = clip(G, 0, 255);
        B = clip(B, 0, 255);
        

IPP Compatibility

In order to achieve compatibility with the yuv color conversion provided by intel IPP (which is used if IPP is available), also ICL's color conversion methods were slightly adapted. We again used fixed point approximations for the algorithms described in the IPP manual:

        rgb-to-yuv:
        y = ( 1254097*r + 2462056*g + 478151*b ) >> 22;  
        u = (2063598*(b-y) >> 22) + 128;
        v = (3678405*(r-y) >> 22) + 128;
        if(v<0) v=0;
        else if(v > 255) v = 255;
        
        yuv-to-rgb:
        icl32s u2 = u-128;
        icl32s v2 = v-128;
        icl32s y2 = y<<22;
        r = (y2 + 4781506 * v2 ) >> 22;
        g = (y2 - 1652556 * u2 - 2436891 *v2 ) >> 22;
        b = (y2 + 8522826 * u2 ) >> 22;
        

please note Due to the clipping process of 'v' in rgb_to_yuv, this method cannot restore an original rgb value completetly. Since we lost some information in v, the resulting r and g values are differ as follows: r-r' in [-32,35], and g-g' in [-17,18]

HLS Color Space Conversion

The HLS color space, also known as the HSI color space with another channel order describes colors in more independent components. The Hue component complies an angle and is as well as all other color information scaled to the range [0,254]. The value H=255 is identical to H=0 (red). Independent from the colors hue, its Lightness is estimated by the second component. Basic colors as red (r=255,g=0,b=0) have a lightness of 127; lighter colors have a hight L value; darker colors have a lower one. The last component is the Saturation of the color. The color model can be drawn as a double (hex)cone . Note that the HLS color spaces resolution is higher in its center (L near 127). The following formulas describe the conversion from and to the RGB format:

        (H,L,S) RGBToHLS(R,G,B)
        (r,g,b) = (R,G,B)/255;
        m = min(r,g,b)
        v = max(r,g,b)
        l = (m+v)/2
        if(l <= 0){
          (H,L,S) = (0,0,0)
          return
        }
        vm = v-m
        if ( vm > 0 ) {
          if(l<=0.5){
            s=vm/(v+m)
          }else{
            s=vm/(2.0-v-m)
          }
        }else{
          (H,L,S)=(0,l*255,0)
          return
        }
        r2 = (v - r) / vm
        g2 = (v - g) / vm
        b2 = (v - b) / vm
        if (r == v)
          h = (g == m ? 5.0 + b2 : 1.0 - g2)
        else if (g == v)
          h = (b == m ? 1.0 + r2 : 3.0 - b2)
        else
          h = (r == m ? 3.0 + g2 : 5.0 - r2)
        if(h == 255) h = 0
          (H,L,S) = (h*255/6,l*255,s*255)
        

An optimization, that allows conversion directly with (r,g,b) values in range [0,255] is not yet implemented.

        (R,G,B) HLSToRGB(H,L,S)
        (h,l,s) = (H,L,S)/255;
        v = (l <= 0.5) ? (l * (1.0 + sl)) : (l + sl - l * sl)
        if (v <= 0 ) {
          R = G = B = 0;
          return;
        }
        m = l + l - v;
        sv = (v - m ) / v;
        h *= 6.0;
        int sextant = (int)h;
        fract = h - sextant;
        vsf = v * sv * fract;
        mid1 = m + vsf;
        mid2 = v - vsf;
        switch (sextant) {
          case 0: r = v;    g = mid1; b = m;    break;
          case 1: r = mid2; g = v;    b = m;    break;
          case 2: r = m;    g = v;    b = mid1; break;
          case 3: r = m;    g = mid2; b = v;    break;
          case 4: r = mid1; g = m;    b = v;    break;
          case 5: r = v;    g = m;    b = mid2; break;
        }
        (R,G,B) = (r,g,b)*255;
        

An additional optimization can be implemented using lookup tables.

Lab Color Space Conversion

The LAB color space (strictly CIE L*a*b*), was designed to describe the complete range of colors, that can be seen by the human eye. It must not be mixed up with the "Hunter Lab" color space, that is sure related to the CIE L*a*b*, but in detail much different. "The three parameters in the model represent the lightness of the color (L*, L*=0 yields black and L*=100 indicates white), its position between magenta and green (a*, negative values indicate green while positive values indicate magenta) and its position between yellow and blue (b*, negative values indicate blue and positive values indicate yellow)"(wikipedia). "CIE 1976 L*a*b* is based directly on the CIE 1931 XYZ color space as an attempt to linearize the perceptibility of color differences, using the color difference metric described by the MacAdam ellipse"(wikipedia). So an euclidian (linear) color difference metric can be used here. The following code show the formulas LabToXYZ, XYZToLab, RGBToXYZ and XYZToRGB.

        RGBToXYZ
        static icl32f m[3][3] = {{ 0.412453, 0.35758 , 0.180423},
                                 { 0.212671, 0.71516 , 0.072169},
                                 { 0.019334, 0.119193, 0.950227}};
        X = m[0][0] * R + m[0][1] * G + m[0][2] * B;
        Y = m[1][0] * R + m[1][1] * G + m[1][2] * B;
        Z = m[2][0] * R + m[2][1] * G + m[2][2] * B;
        XYZToRGB
        static icl32f m[3][3] = {{ 3.2405, -1.5372,-0.4985},
                                 {-0.9693,  1.8760, 0.0416},
                                 { 0.0556, -0.2040, 1.0573}};
        R = m[0][0] * x + m[0][1] * y + m[0][2] * z;
        G = m[1][0] * x + m[1][1] * y + m[1][2] * z;
        B = m[2][0] * x + m[2][1] * y + m[2][2] * z;
        XYZToLAB
        wX = 0.950455;
        wY = 1.0;
        wZ = 1.088753;
        _13 = 1.0/3.0;
        XXn = X / wX;
        YYn = Y / wY;
        ZZn = Z / wZ;
        L = (YYn > 0.008856) ? ((116 * pow (YYn, _13))-16) : (903.3 * YYn);
        fX = (XXn > 0.008856) ? pow (XXn, _13) : 7.787 * XXn + (16 / 116);
        fY = (YYn > 0.008856) ? pow (YYn, _13) : 7.787 * YYn + (16 / 116); 
        fZ = (ZZn > 0.008856) ? pow (ZZn, _13) : 7.787 * ZZn + (16 / 116);
        L = 116 * fY - 16;
        a = 500.0 * (fX - fY);
        b = 200.0 * (fY - fZ);
        LABToXYZ
        n = 16.0/116.0;
        wX = 0.950455;
        wY = 1.0;
        wZ = 1.088754f;
        fy = (l+16)/116;
        fx = fy+a/500;
        fz = fy-b/200;
        X = (fx>0.206893f) ?  wX*pow(fx,3) : wX*(fx-n)/7.787f;
        Y = (fy>0.206893f) ?  wY*pow(fy,3) : wY*(fy-n)/7.787f;
        Z = (fz>0.206893f) ?  wZ*pow(fz,3) : wZ*(fz-n)/7.787f;
        

Gray Scale Conversion

The gray scale conversion is optimized for speed performance. Although, L of Lab is not equal to the Y of YUV, color formats, that have an brightness-like component are converted to gray scale by picking this channel. RGB is converted to gray by the simple channel mean (r+g+b)/3.

formatMatrix Conversion

As the matrix image format offers no color information, matrix image data is just copied from the source image channels to the destination image channels. If the source image has more channels, the remaining channels are left unregarded. If otherwise the destination image has more channels, this channels are left unchanged

r-g-Chromaticity Color Space Conversion

The chromaticity space r,g,b divides the R,G,B components by the city block norm of the according color r=R/(R+G+B), g=G/(R+G+B), b= B/(R+G+B). By this means, the b-component becomes redundant, and can be left out, which leads to the r-g-chromaticity space. Conversions form the r-g-Chromaticity space to other formats are not possible, as to much information is lost.

Benchmarks

The following tables, show the cross format conversion times: TODO: re-run this test --> which machine / which image size ?

depth32f

src\dstrgb yuv lab hls gray chroma
rgb 10* 26 47 30 7 21
yuv 23 8 387?64 2 45
lab 45 63 8 75 2 63
hls 23 43 67 8 2 44
gray 11 12 11 13 3 **
chroma ** ** ** ** ** 6

* times in ms ** this does not make sense!

depth8u

src\dstrgb yuv lab hls gray chroma
rgb 3 9 31 22 3 22
yuv 13 2 487?56 0.2 33
lab 31 40 2 54 0.2 52
hls 12 21 43 2 0.2 33
gray 3 4 4 4 0.2 **
chroma ** ** ** ** ** 6

cross depth conversion depth8u --> depth32f

src\dstrgb yuv lab hls gray chroma
rgb 9 10 32 22 4 23
yuv 11 8 474?54 3 34
lab 30 41 8 52 3 53
hls 14 22 43 8 3 34
gray 8 8 8 8 3 **
chroma 7 ** ** ** ** 5

Region of Interest (ROI)

A new feature is the ROI-Support of the "cc" function. If the "roiOnly"-flag given to cc function is set to true, the source images ROI is converted into the destination images ROI. In this case, the destination image is not adapted to the source image. Instead, a single test is performed to ensure, that the source images ROI has the same size as the destination images ROI. If the test fails, an error occurs and the function returns immediately.
Note: internally all functions are optimized for running without ROI support (in this case, the images data arrays are 1D). Thus, the ROI-Support mode (roiOnly = true) runs approx. 20% (2%-50%) slower depended on the specific source and destination format.

Intel IPP

Most functions are not IPP accelerated even if IPP support is available because IPP supports most conversions for interleaved formats only. However a few very common conversions make use of available IPP acceleration:

  • RGB -> YUV
  • YUV -> RGB
  • RGB -> HLS
  • HLS -> RGB

The IPP accelerated times are not part of the benchmark above. Usually, as a rule of thumb, IPP is supposed to be at least twice as fast as the C++-fallback implementation.

Important note regarding IPP compatibility</b>

Currently, IPP and C++ fallback version are not 100% compatible as IPP uses additional optimizations that causes, that the U- and V- channel range are not full 8bit range [0-255]. We aim to fix that in future

ICLCore_API ccimpl icl::core::cc_available ( format  srcFmt,
format  dstFmt 
)

returns the ccimpl state to a conversion from srcFmt to dstFmt

ICLCore_API void icl::core::cc_util_hls_to_rgb ( const icl32f  h255,
const icl32f  l255,
const icl32f  sl255,
icl32f &  r,
icl32f &  g,
icl32f &  b 
)

converts given (h,l,s) pixel into the rgb format

ICLCore_API void icl::core::cc_util_rgb_to_chroma ( const icl32f  r,
const icl32f  g,
const icl32f  b,
icl32f &  chromaR,
icl32f &  chromaG 
)

converts given (r,g,b) pixel into the RG-chroma format

ICLCore_API void icl::core::cc_util_rgb_to_hls ( const icl32f  r255,
const icl32f  g255,
const icl32f  b255,
icl32f &  h,
icl32f &  l,
icl32f &  s 
)

converts given (r,g,b) pixel into the hls format

void icl::core::cc_util_rgb_to_lab ( const icl32f &  r,
const icl32f &  g,
const icl32f &  b,
icl32f &  L,
icl32f &  A,
icl32f &  B 
)

converts given (r,g,b) pixel into the Lab format

ICLCore_API void icl::core::cc_util_rgb_to_yuv ( const icl32s  r,
const icl32s  g,
const icl32s  b,
icl32s &  y,
icl32s &  u,
icl32s &  v 
)

converts given (r,g,b) pixel into the yuv format

ICLCore_API void icl::core::cc_util_yuv_to_rgb ( const icl32s  y,
const icl32s  u,
const icl32s  v,
icl32s &  r,
icl32s &  g,
icl32s &  b 
)

converts given (y,u,v) pixel into the rgb format

ICLCore_API std::vector<int> icl::core::channelHisto ( const ImgBase *  image,
int  channel,
int  levels = 256,
bool  roiOnly = false 
)

computes the color histogramm of given image channel

Color ICLCore_API icl::core::color_from_string ( const std::string &  name)

Parses a color string representation into a color structur.

If an error occurs, a warning is shown and black color is returned first checks for some default color names:

  • black
  • white
  • red
  • green
  • blue
  • cyan
  • magenta
  • yellow
  • gray50
  • gray100
  • gray150
  • gray200
template<class S , class D >
void icl::core::convertChannelROI ( const Img< S > *  src,
int  srcC,
const utils::Point &  srcOffs,
const utils::Size &  srcROISize,
Img< D > *  dst,
int  dstC,
const utils::Point &  dstOffs,
const utils::Size &  dstROISize 
) [inline]

This function is used by all other deepCopyROI functions internally. It copies / converts ROI image data to another images ROI using the icl::copy(..) function line by line or, in case of IPP-optimization enabled, corresponding ippCopy/ippConvert Calls (see the following specialized template functions also).

Parameters:
srcsource image
srcCsource image channel
srcOffssource images ROI-offset (src->getROIOffset() is not regarded)
srcROISizesource images ROI-size (src->getROISize() is not regarded)
dstdestination image
dstCdestination image channel
dstOffsdestination images ROI-offset (dst->getROIOffset() is not regarded)
dstROISizedestination images ROI-size (dst->getROISize() is not regarded)
ICLCore_API void icl::core::convertYUV420ToRGB8 ( const unsigned char *  pucSrc,
const utils::Size &  s,
Img8u *  poDst 
)

Convert an image in YUV420-format to RGB8 format (ippi accelerated)

Parameters:
poDstdestination image
pucSrcpointer to source data (data is in YUV420 format, which is planar and which's U- and V-channel has half X- and half Y-resolution. The data pointer has iW*iH*1.5 elements)
simage size
ICLCore_API std::vector<utils::Point> icl::core::convexHull ( std::vector< utils::Point >  P)

convex hull monotone chain algorithm for int-points

Parameters:
Plist of utils::Point (input) call-by-value, as we need an inplace-sort internally
Returns:
list of points of the convex hull first point is identical to the last point in this list!
ICLCore_API std::vector<utils::Point32f> icl::core::convexHull ( std::vector< utils::Point32f >  P)

convex hull monotone chain algorithm for float-points

Parameters:
Plist of utils::Point32f (input) call-by-value, as we need an inplace-sort internally
Returns:
list of points of the convex hull first point is identical to the last point in this list!
ICLCore_API void icl::core::createLUT ( format  srcFmt,
format  dstFmt 
)

Internally creates a lookup table to accelerate conversion between given formats.

Take care: Each LUT uses up to 48MB of system memory

Parameters:
srcFmtsource format
dstFmtdestination format
Color icl::core::darker ( const Color &  c,
double  factor = 0.8 
) [inline]

Creates a (by default 20 percent) darker color.

ICLCore_API std::vector<std::vector<int> > icl::core::hist ( const ImgBase *  image,
int  levels = 256,
bool  roiOnly = false 
)

computes the color histogramm of given image

const Color& icl::core::iclCreateColor ( std::string  name)
ICLCore_API CvMat* icl::core::img_to_cvmat ( const ImgBase *  src,
CvMat *  dst = 0,
int  channel = 0 
) throw (utils::ICLException)

Copy single ICLimage channel to OpenCV single channel CvMat.

Copy single ICLimage channel to single channel CvMat. If dst is NULL, the sourceimagedepth will be used, else the destinationmatrixdepth will be used.

Parameters:
*srcpointer to sourceimage
**dstpointer to pointer to destinationmatrix
channelchannel to use
ICLCore_API CvMat* icl::core::img_to_cvmat_shallow ( const ImgBase *  src,
CvMat *  dst = 0 
) throw (utils::ICLException)

Convert single channel ICLimage to OpenCV CvMat.

Converts single channel ICLimage to a single channel CvMat. Data is shared by source and destination. Be careful when releasig (data)pointers.

Parameters:
*srcpointer to sourceimage
*dstpointer to destinationmatrix (IplImage)
ICLCore_API IplImage* icl::core::img_to_ipl ( const ImgBase *  src,
IplImage **  dst = 0,
DepthPreference  e = PREFERE_SRC_DEPTH 
) throw (utils::ICLException)

Convert ICLimage to OpenCV IplImage.

Converts ICLimage to IplImage. If dst is NULL, the sourceimagedepth will be used, else the destinationimagedepth will be used.

Parameters:
*srcpointer to sourceimage
**dstpointer to pointer to destinationimage (IplImage)
edepthpreference
ICLCore_API IplImage* icl::core::img_to_ipl_shallow ( ImgBase *  src,
IplImage *  dst = 0 
) throw (utils::ICLException)

Convert single channel ICLimage to OpenCV IplImage.

Converts single channel ICLimage to IplImage. Data is shared by source and destination. Using icl8u or icl16s the imagedata is not aligned, but OpenCV expects aligned data. In this case be careful using further OpenCV functions. Be careful when releasig (data)pointers.

Parameters:
*srcpointer to sourceimage
*dstpointer to destinationimage (IplImage)
template<class S , class D >
ICLCore_API void icl::core::interleavedToPlanar ( const S *  src,
Img< D > *  dst,
int  srcLineStep = -1 
)

Converts interleaved image data into planar representation.

The source data is transformed into the destination images ROI

Parameters:
srcdata pointer
dstimage pointer
srcLineStepoptionally given src linestep size
ICLCore_API ImgBase* icl::core::ipl_to_img ( CvArr *  src,
ImgBase **  dst = 0,
DepthPreference  e = PREFERE_SRC_DEPTH 
) throw (utils::ICLException)

Convert OpenCV IplImage to ICLimage.

Converts IplImage to ICLimage. If dst is NULL, the sourceimagedepth will be used, else the destinationimagedepth will be used.

Parameters:
*srcpointer to sourceimage (IplImage)
**dstpointer to pointer to destinationimage (ICLimage)
edepthpreference
Color icl::core::lighter ( const Color &  c,
double  factor = 0.8 
) [inline]

Creates a (by default 20 percent) lighter color.

ICLCore_API bool icl::core::lut_available ( format  srcFmt,
format  dstFmt 
)

returns whether a lookup table was already created for src and dst format

Parameters:
srcFmtsource format
dstFmtdestination format
ICLCore_API std::vector<double> icl::core::mean ( const ImgBase *  poImg,
int  iChannel = -1,
bool  roiOnly = false 
)

Computes the mean value of a ImgBase* ingroup MATH.

IPP-Optimized for icl32f and icl64f

Parameters:
poImginput image
iChannelchannel index (-1 for all channels)
roiOnly
Returns:
mean value of image or image channel (optionally: roi)
ICLCore_API std::vector< std::pair<double, double> > icl::core::meanAndStdDev ( const ImgBase *  image,
int  iChannel = -1,
bool  roiOnly = false 
)

Calculates mean and standard deviation of given image simultanously.

Parameters:
imageinput image
iChannelimage channel if < 0 all channels are used
roiOnly
Returns:
vector v of pairs p with p.first = mean and p.second = stdDev v[i] containing i-th channel's results
ICLCore_API std::ostream& icl::core::operator<< ( std::ostream &  s,
const Line &  l 
)

ostream operator (start-x,start-y)(end-x,end-y)

ICLCore_API std::ostream& icl::core::operator<< ( std::ostream &  s,
const Line32f &  l 
)

ostream operator (start-x,start-y)(end-x,end-y)

template<class T >
std::ostream& icl::core::operator<< ( std::ostream &  str,
const CvMatWrapper< T > &  m 
) [inline]

Overloaded ostream operator for the CvMat32fWrapper.

ICLCore_API std::ostream& icl::core::operator<< ( std::ostream &  s,
const format &  f 
)

puts a string representation of format into the given stream

ICLCore_API std::ostream& icl::core::operator<< ( std::ostream &  s,
const depth &  d 
)

puts a string representation of depth into the given stream

ICLCore_API std::ostream& icl::core::operator<< ( std::ostream &  os,
const ImgParams &  p 
)

ostream operator SIZExCHANNELS@FORMAT.ROI

ICLCore_API std::ostream& icl::core::operator<< ( std::ostream &  s,
const ImgBase &  image 
)

puts a string representation of the image into given steam

ICLCore_API std::istream& icl::core::operator>> ( std::istream &  s,
Line &  l 
)

istream operator

ICLCore_API std::istream& icl::core::operator>> ( std::istream &  s,
Line32f &  l 
)

istream operator

ICLCore_API std::istream& icl::core::operator>> ( std::istream &  s,
format &  f 
)

puts a string representation of format into the given stream

ICLCore_API std::istream& icl::core::operator>> ( std::istream &  s,
depth &  d 
)

puts a string representation of depth into the given stream

ICLCore_API std::istream& icl::core::operator>> ( std::istream &  is,
ImgParams &  p 
)

istream operator

template<class T >
static T icl::core::p2o ( T *  ptr) [inline, static]

Conversion function to transform a pointer into an object.

This function is very common: in many cases, Img<T> member functions return pointer instead of objects. This might lead to some extra code lines, if these pointer are used locally:

        void foo(const Img8u *image){
          const Img8u *channel0 = image->selectChannel(0);
          const Img8u *imageWithFullROI = image->shallowCopy(image->getImageRect());
        
          // do something with the shallow copies
          // e.g. call some other functions
          show_one_channel_image(*channel0);
          process_image_with_full_roi(*imageWithFullROI);
  
          delete channel0;
          delete imageWithFullROI;
        }

This code can be written much shorter using the *NEW* p2o function:

        void foo(const Img8u *image){
          show_one_channel_image(p2o(image->selectChannel(0)));
          process_image_with_full_roi(p2o(image->shallowCopy(image->getImageRect())));
        }

internally: p2o uses a smart pointer to ensure given pointer is released properly before function returns

Implementing the Configurable Interface

        template<class T>
        inline T p2o(T *ptr){
          return T(*SmartPtr<T>(const_cast<T*>(ptr)));
        }

Complexity

the function internally creates a smart Pointer object and calls the copy constructor of given T once. Hence the function complexity scales with the implementation of the standard copy constructor of T. Particularly for ICL's Img<T> classes, the default copy constructor performs a shallow copy internally which induces negligible computational costs.

template<class S , class D >
ICLCore_API void icl::core::planarToInterleaved ( const Img< S > *  src,
D *  dst,
int  dstLineStep = -1 
)

Convert an 4 channel Img8u into Qts ARGB32 interleaved format.

@param pucDst destination data pointer of size poSrc->getDim()*4 @param poSrc source image with 4 channels Convert an 4 channel Img32f into Qts ARGB32 interleaved format This function will first convert the given Img32f poSrc into the buffer image poBuffer. Then it will call the above method, to convert the buffer data into pucDst. If the buffer is not valid, the method will return immediately. @param pucDst destination data pointer of size poSrc->getDim()*4 @param poSrc source image with 4 channels @param poBuffer buffer to use for internal depth conversion. Converts a planar Img<S> images ROI into its interleaved representations by mixing the channels This function is highly optimized, because it is needed whenever we need interleaved images

Parameters:
srcsource image image
dstdestination data pointer
dstLineStepoptinal linestep of the destination image. This must be given, if it differs from the source images lineStep multiplied by the source images channel count

releases all lookup tables that were created with createLUT

ICLCore_API void icl::core::releaseLUT ( format  srcFmt,
format  dstFmt 
)

releases the internal lookup table created with createLUT

Parameters:
srcFmtsource format
dstFmtdestination format
template<class T >
ICLCore_API void icl::core::scaledCopyChannelROI ( const Img< T > *  src,
int  srcC,
const utils::Point &  srcOffs,
const utils::Size &  srcSize,
Img< T > *  dst,
int  dstC,
const utils::Point &  dstOffs,
const utils::Size &  dstSize,
scalemode  eScaleMode 
)

This function provides all necessary functionalities for scaling images. Please regard, that the fallback- implementation is very slow. Only scaling operations with identical source and destination type is optimized by corresponding ippResize calls (see also the specialized template functions).

Parameters:
srcsource image
srcCsource image channel
srcOffssource images ROI-offset (src->getROIOffset() is not regarded)
srcSizesource images ROI-size (src->getROISize() is not regarded)
dstdestination image
dstCdestination image channel
dstOffsdestination images ROI-offset (dst->getROIOffset() is not regarded)
dstSizedestination images ROI-size (dst->getROISize() is not regarded)
eScaleModescaling mode to use (nearest neighbor, linear, or region-average)
ICLCore_API std::vector<double> icl::core::stdDeviation ( const ImgBase *  poImage,
int  iChannel = -1,
bool  roiOnly = false 
)

Compute the std::deviation of an image.

Parameters:
poImageinput image
iChannelchannel index (all channels if -1)
roiOnly
ICLCore_API std::vector<double> icl::core::stdDeviation ( const ImgBase *  poImage,
const std::vector< double >  mean,
bool  empiricMean = true,
int  iChannel = -1,
bool  roiOnly = false 
)

Compute the std::deviation of an image with given channel means.

Parameters:
poImageinput image
meanvector with channel means
empiricMeanif true, sum of square distances is devided by n-1 else by n
iChannelchannel index (all channels if -1)
roiOnly
ICLCore_API ccimpl icl::core::translateCCImlp ( const std::string &  s)

translates the string represenation of a

ICLCore_API std::string icl::core::translateCCImpl ( ccimpl  i)

translates a ccimpl enum into a string representation

The returned string for ccAvailable is "available" (...)

ICLCore_API std::vector<double> icl::core::variance ( const ImgBase *  poImg,
const std::vector< double > &  mean,
bool  empiricMean = true,
int  iChannel = -1,
bool  roiOnly = false 
)

Compute the variance value of an image a with given mean.

Parameters:
poImginput imge
meanvector with channel means
empiricMeanif true, sum of square distances is devided by n-1 else by n
iChannelchannel index (-1 for all channels)
roiOnly
Returns:
The variance value form the vector
ICLCore_API std::vector<double> icl::core::variance ( const ImgBase *  poImg,
int  iChannel = -1,
bool  roiOnly = false 
)

Compute the variance value of an image a.

Parameters:
poImginput imge
iChannelchannel index (-1 for all channels)
roiOnly
Returns:
The variance value form the vector
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines