image =	colorConvertImg (inColorImg,targetColorSpace)
image =	colorConvertImg (inColorImg,inColorConversionTransform)

Detailed Description

convert a color image from a given color space to another

This algorithm allows to convert an input color image from its color space (the sourceColorSpace) to another color space defined by InColorConversionTransform (the targetColorSpace)

IPSDK will select the algorithm to use in function of the color space of the input image attribute InColorImg and of TargetColorSpace value of parameter InColorConversionTransform.

Details of used transformations can be found at Color models.

In some cases, a linear transform allows to transform a color space to another with following equation :

$OutColorImg[i, c_j]=\sum_{c_k=0}^{c_k=N_c^I-1}{a_{c_j,c_k} \times InColorImg[i, c_k]}+b_{c_j} OutColorImg[i, c_j]=\sum_{c_k=0}^{c_k=N_c^I-1}{a_{c_j,c_k} \times InColorImg[i, c_k]}+b_{c_j}$

where :

and are color plan indexes
is equal to number of color channels of input image
$a_{c_j,c_k}$ are components of matrix of underlying linear system
$b_{c_j}$ are components of vector of underlying linear system

This linear system can then be rewritten as follow :

$OutColorImg_c[i]=A \times InColorImg_c[i]+B$

where :

and are respectively a $N_c^I \times N_c^O$ matrix and a vector associated to underlying linear system
and are color space vector respresentations of used images

This is the case when :

ipsdk::image::hasLinearTransform(sourceColorSpace, targetColorSpace) returns true.
sourceColorSpace or targetColorSpace is equal to ipsdk::image::eColorGeometryType::eCGT_User. In this case, LinearTransform value of parameter InColorConversionTransform will be used as linear transform.

In some other cases such as sourceColorSpace or targetColorSpace in :

ipsdk::image::eColorGeometryType::eCGT_CieLab
ipsdk::image::eColorGeometryType::eCGT_CieLuv
ipsdk::image::eColorGeometryType::eCGT_HLS
ipsdk::image::eColorGeometryType::eCGT_HSV

a specific algorithm is used to proceed to conversion.

Note: If the source color space is Cie Lab or Cie Luv and if a user linear transform is provided, then this linear transform should allow to go from CIE XYZ color space to the user color space. The transform from the Cie Lab/Cie Luv to the CIE XYZ color space will be automatically pre-proceeded.; If the target color space is Cie Lab or Cie Luv and if a user linear transform is provided, then this linear transform should allow to go from the user color space to the CIE XYZ color space. The transform from CIE XYZ color space to the Cie Lab/Cie Luv will be automatically post-proceeded.; For RGB to XYZ or RGB to Cie Lab conversions, we consider that the input color space is standard RGB (sRGB). Hence, to comply with this predicate, the input color image range must be [0, 255].

In the case where the output image is not provided, the output buffer type is set to :

the input buffer type if proceeding an RGB<->RGBA conversion
the input buffer type if targetColorSpace is equal to ipsdk::image::eColorGeometryType::eCGT_YCbCr
ipsdk::image::eImageBufferType::eIBT_Real32 otherwise

Warning: If an output image is provided, be sure to use a suitable output image buffer type to avoid problems such as signed/unsigned conversion, buffers overflow or loss of precision. In such a case, the output value is undefined.

Rgb to YPbPr example

In this case, output image values are given by:

$\begin{bmatrix} OutColorImg[i, Y] \\ OutColorImg[i, U] \\ OutColorImg[i, V] \end{bmatrix} = \begin{bmatrix} 0.299 & 0.587 & 0.114 \\ 0.5 & -0.41869 & -0.08131 \\ -0.16874 & -0.33126 & 0.5 \end{bmatrix} \begin{bmatrix} InColorImg[i, Red] \\ InColorImg[i, Green] \\ InColorImg[i, Blue] \end{bmatrix}$

Here is an example of a YPbPr to Rgb color base conversion operation applied to a 8-bits image :

YPbPr to Rgb example

In this case, the output image values are given by:

$\begin{bmatrix} OutColorImg[i, Red] \\ OutColorImg[i, Green] \\ OutColorImg[i, Blue] \end{bmatrix} = \begin{bmatrix} 1 & 0 & 1.13983 \\ 1 & -0.39465 & -0.58060 \\ 1 & 2.03211 & 0 \end{bmatrix} \begin{bmatrix} InColorImg[i, Y] \\ InColorImg[i, U] \\ InColorImg[i, V] \end{bmatrix}$

Here is an example of a YPbPr to Rgb color base conversion operation applied to a 8-bits image :

See also: https://en.wikipedia.org/wiki/YCbCr; https://en.wikipedia.org/wiki/RGB_color_model

Example of Python code :

Example imports

import PyIPSDK
import PyIPSDK.IPSDKIPLColor as color
import PyIPSDK.IPSDKIPLUtility as util

Code Example

    # opening of input image
    inImg = PyIPSDK.loadTiffImageFile(inputImgPath)
    
    # rgb to YPbPr computation
    outImgYPbPr = color.colorConvertImg(inImg, PyIPSDK.eColorGeometryType.eCGT_YPbPr)
    
    # rgb to L*a*b* computation
    outImgLab = color.colorConvertImg(inImg, PyIPSDK.eColorGeometryType.eCGT_CieLab)
    
    # rgb to user color space
    # (mix of input red and green color with additional offset for output red component
    # green and blue channels left unchanged)
    transMat = [0.5, 0.5, 0, -12,
                0,   1,   0, 0,
                0,   0,   1, 0]
    outImgUser = color.colorConvertImg(inImg, PyIPSDK.createToUserColorConversionTransform(transMat))

Example of C++ code :

Example informations

Header file

#include <IPSDKIPL/IPSDKIPLColor/Processor/ColorConvertImg/ColorConvertImg.h>

Code Example

        // opening input image
        ImagePtr pInputColorImg = loadTiffImageFile(inputImgPath);
        // compute color base conversion on input image
        ImagePtr pOutColorImg = colorConvertImg(pInputColorImg, targetColorGeometryType);