Convert

Syntax

Parameters

pSrc	Pointer to the source image ROI.
srcStep	Distance in bytes between starts of consecutive lines in the source image.
srcBitOffset	Offset (in bits) in the first byte of the source image row.
pDst	Pointer to the destination image ROI.
pSrcDst	Pointer to the source and destination image ROI for in-place operation.
dstStep	Distance in bytes between starts of consecutive lines in the destination image.
srcDstStep	Distance in bytes between starts of consecutive lines in the source and destination image for in-place operation.
dstBitOffset	Offset (in bits) in the first byte of the destination image row.
roiSize	Size of the source and destination ROI in pixels.
threshold	Threshold level for Stucki's dithering.
scaleFactor	Scale factor (see Integer Result Scaling).
roundMode	Rounding mode, the following values are possible: ippRndZero specifies that floating-point values are truncated toward zero, ippRndNear specifies that floating-point values are rounded to the nearest even integer when the fractional part equals 0.5; otherwise they are rounded to the nearest integer, ippRndFinancial specifies that floating-point values are rounded down to the nearest integer when the fractional part is less than 0.5, or rounded up to the nearest integer if the fractional part is equal or greater than 0.5.

Description

The function ippiConvert is declared in the ippi.h file. It operates with ROI (see Regions of Interest in Intel IPP).

This function converts pixel values in the source image ROI pSrc to a different data type and writes them to the destination image ROI pDst.

The result of integer operations is always saturated to the destination data type range. It means that if the value of the source pixel is out of the data range of the destination image, the value of the corresponding destination pixel is set to the value of the lower or upper bound (minimum or maximum) of the destination data range:

x = pSrc[i,j]

if (x > MAX_VAL) x = MAX_VAL

if (x < MIN_VAL) x = MIN_VAL

pDst[i,j] = (CASTING)x

If you want to shift data from the signed range to the unsigned range and vice-versa, see "Application Notes" below.

The function flavors with the Sfs descriptor in their names perform scaling of the internally computed results in accordance with the parameter scaleFactor (see Integer Result Scaling).

When converting from floating-point to integer type, rounding defined by roundMode is performed, and the result is saturated to the destination data type range

1u to 8u conversion. The source image has a 8u data type, where each byte represents eight consecutive pixels of the bitonal image (1 bit per pixel). In this case, additional parameter srcBitOffset is required to specify the start position of the source ROI buffer. Each source bit is transformed into the byte of the destination image in the following way: if an input pixel is 0, the corresponding output pixel is set to 0, if an input pixel is 1, the corresponding output pixel is set to 255. Note that in the source image the bit order in each byte is inverse relative to the pixel order, that is, the first pixel in a row is represented by the last (7th) bit of the first byte in the row.

8u to 1u conversion. Source image is converted to a bitonal image using the Stucki's error diffusion dithering algorithm. The destination image has a 8u data type, where each byte represents eight consecutive pixels of the bitonal image (1 bit per pixel). In this case, additional parameter dstBitOffset is required to specify the start position of the destination ROI buffer.

Caution

THE FUNCTION ippiConvert_8u1u_C1R IS DEPRECATED. Please use the function ippiReduceBits_8u1u_C1R instead.

Example “Straightforward Data Conversion” shows data conversion without scaling.

Application Notes

When data is converted from the signed integer to the corresponding unsigned integer and vice versa (8s -->8u, 16u --> 16s), the pixel information may be lost because all negative values will be set to zero (signed-unsigned conversion), or unsigned values from the high half of the range will be set to the maximum value of the signed range (unsigned - signed conversion).

If you want to preserve complete pixel information, in other words, if you need just to shift the data from the signed range to the unsigned range and vice versa, use the function ippiXorC with the parameter value specified in such a way that the most significant bit is set to 1, and all other bits are set to 0. For example if you want to convert pixel values from Ipps16s type to Ipp16u type with the rage shift call the function

ippiXorC_16u_C1R( (Ipp16u *)pSrc, srcStep, 0x8000, pDst, dstStep, roiSize);

In this case the pixels values are converted as follows:

-32768 --> 0

-32767 --> 1

...

-1 --> 32767

0 --> 32768

1 --> 32769

...

32766 --> 65534

32767 --> 65535

Return Values

ippStsNoErr	Indicates no error. Any other value indicates an error or a warning.
ippStsNullPtrErr	Indicates an error when any of the specified pointers is NULL, with the exception of second mode in Case 4.
ippStsSizeErr	Indicates an error condition if roiSize has a field with zero or negative value, or srcBitOffset/dstBitOffset is less than zero.
ippStsStepErr	Indicates an error condition if srcStep or dstStep has a zero or negative value.
ippStsMemAllocErr	Indicates an error condition if memory allocation fails.

Straightforward Data Conversion

      IppStatus convert( void ) {

         IppiSize roi={5,4};
         Ipp32f x[5*4];      
       
         Ipp8u y[5*4];
         ippiSet_32f_C1R( -1.0f, x, 5*sizeof(Ipp32f), roi );
               x[1] = 300; x[2] = 150;

   return ippiConvert_32f8u_C1R( x, 5*sizeof(Ipp32f), y, 5, roi, ippRndNear );
   }

The destination image y contains:

   00 FF 96 00 00
   00 00 00 00 00
   00 00 00 00 00
   00 00 00 00 00