imaqCast
Usage
int imaqCast(Image* dest, const Image* source, ImageType type, const float* lookup, int shift);
Purpose
Changes the type of an image.
Image Types Supported
IMAQ_IMAGE_U8, IMAQ_IMAGE_U16, IMAQ_IMAGE_I16, IMAQ_IMAGE_SGL, IMAQ_IMAGE_COMPLEX, IMAQ_IMAGE_RGB, IMAQ_IMAGE_HSL, IMAQ_IMAGE_RGB_U64
Parameters
|
Name
|
Type
|
Description
|
|---|---|---|
| dest | Image* | The destination image. Set this parameter equal to source or NULL to perform the change directly on the source image. |
| source | const Image* | The source image. |
| type | ImageType | The new type for the image. type is the new type for the dest image if it is being used, otherwise it is the new type for source. |
| lookup | const float* | An optional lookup table. If you do not wish to use a lookup table, this parameter may be NULL. See the description on how the lookup table is employed. |
| shift | int | The shift value for converting 16-bit images to 8-bit images. The function executes this conversion by shifting the 16-bit pixel values to the right by the specified number of shift operations, up to a maximum of 8 shift operations, and then truncating to get an 8-bit value. Enter a value of –1 to ignore the bit depth and shift 0. Enter a value of 0 to use the bit depth to cast the image. |
Return Value
| Type |
Description |
|---|---|
| int | On success, this function returns a non-zero value. On failure, this function returns 0. To get extended error information, call imaqGetLastError(). |
Parameter Discussion
This function can perform the change directly on the source image, or it can leave the source image unchanged and instead copy the source image to a destination image and then convert the destination image. If dest is equal to source, the function changes the type of source. Otherwise, the function resizes dest to the size of source and then copies the pixels. If the source type and the type parameter are the same, the function copies pixels without modifications. You can also use imaqCopyRect() to copy pixels without modifying them. If the source type and the type parameter are not the same, the function casts the pixel values to the new type, as shown in the following table.
| source Type | type Parameter | Result |
|---|---|---|
| IMAQ_IMAGE_U8 | IMAQ_IMAGE_U16, IMAQ_IMAGE_I16, IMAQ_IMAGE_SGL | If you provide a lookup table, the destination pixel will have the lookup value of the source pixel. The lookup table must contain 256 elements. If you do not provide a lookup table, the function copies the source value to the destination without modifications. |
| IMAQ_IMAGE_U8, IMAQ_IMAGE_U16, IMAQ_IMAGE_I16, IMAQ_IMAGE_SGL | IMAQ_IMAGE_RGB | Each color component of the destination is set to the source value. If the source value is greater than 255, the function sets each color component to 255. If the source value is less than 0, the function sets each color component to 0. |
| IMAQ_IMAGE_U8, IMAQ_IMAGE_U16, IMAQ_IMAGE_I16, IMAQ_IMAGE_SGL | IMAQ_IMAGE_HSL | The function sets the luminance component of the destination to the source value. If the source value is greater than 255, the function sets the luminance to 255. If the source value is less than 0, the function sets the luminance to 0. The function sets hue and saturation to 0. |
| IMAQ_IMAGE_U8, IMAQ_IMAGE_U16, IMAQ_IMAGE_I16, IMAQ_IMAGE_SGL | IMAQ_IMAGE_COMPLEX | The function sets the real component of the destination to the source value. The function sets the imaginary component of the destination to 0. |
| IMAQ_IMAGE_U16, IMAQ_IMAGE_I16 | IMAQ_IMAGE_U8 | The function right-shifts the source value by the given shift value (divides each source pixel value by 2shift) and stores the value in the destination. If the shifted value is greater than 255, the function sets the destination value to 255. |
| IMAQ_IMAGE_U8, IMAQ_IMAGE_U16, IMAQ_IMAGE_I16, IMAQ_IMAGE_SGL | IMAQ_IMAGE_RGB_U64 | Each color component of the destination is set to the source value. If the source value is greater than 65535 the function sets the color component to 65535. If the source value is less than 0 the function sets each color component to 0. |
| IMAQ_IMAGE_RGB_U64 | IMAQ_IMAGE_U8 | The function shifts the source value to the 8-bit range using the specified bit depth of the source image. Then the function sets the destination value to the average of the three color components of the source. |
| IMAQ_IMAGE_RGB_U64 | IMAQ_IMAGE_U16, IMAQ_IMAGE_I16, IMAQ_IMAGE_SGL | The function sets the destination to the average of the three color components of the source. If the average of the source color components is out of the range of the destination, the function coerces the average to the range. |
| IMAQ_IMAGE_RGB_U64 | IMAQ_IMAGE_RGB | The function shifts the source value to the 8-bit range using the specified bit depth of the source image. Then the function sets each color component in the destination value to the corresponding component in the source value. |
| IMAQ_IMAGE_RGB_U64 | IMAQ_IMAGE_HSL | The function shifts the source value to the 8-bit range using the specified bit depth of the source image. Then the function converts each pixel from the RGB color space to the HSL color space. |
| IMAQ_IMAGE_U16, IMAQ_IMAGE_I16 | IMAQ_IMAGE_SGL | If you provide a lookup table, the destination pixel will have the lookup value of the source pixel. The lookup table must contain 65,536 elements. If you do not provide a lookup table, the function copies the source value to the destination unmodified. |
| IMAQ_IMAGE_SGL | IMAQ_IMAGE_U8, IMAQ_IMAGE_U16, IMAQ_IMAGE_I16 | The function sets the destination value to the source value. If the source value is out of the range of the destination, the function coerces the source to the range. |
| IMAQ_IMAGE_RGB | IMAQ_IMAGE_U8, IMAQ_IMAGE_U16, IMAQ_IMAGE_I16, IMAQ_IMAGE_SGL | The function sets the destination value to the average of the three color components of the source. |
| IMAQ_IMAGE_RGB | IMAQ_IMAGE_HSL | The function converts each pixel from the RGB color space to the HSL color space. |
| IMAQ_IMAGE_RGB, IMAQ_IMAGE_RGB_U64 | IMAQ_IMAGE_COMPLEX | The function sets the real portion of the destination value to the average of the three color components of the source, and it sets the imaginary portion of the destination to 0. |
| IMAQ_IMAGE_HSL | IMAQ_IMAGE_U8, IMAQ_IMAGE_U16, IMAQ_IMAGE_I16, IMAQ_IMAGE_SGL | The function sets the destination value to the luminance component of the source value. |
| IMAQ_IMAGE_HSL | IMAQ_IMAGE_RGB, IMAQ_IMAGE_RGB_U64 | The function converts each pixel from the HSL color space to the RGB color space. |
| IMAQ_IMAGE_HSL | IMAQ_IMAGE_COMPLEX | The function sets the real portion of the destination value to the value of the luminance component of the source, and it sets the imaginary portion of the destination to 0. |
| IMAQ_IMAGE_COMPLEX | IMAQ_IMAGE_U8, IMAQ_IMAGE_U16, IMAQ_IMAGE_I16, IMAQ_IMAGE_SGL | The function sets the destination value to the magnitude of the source value. |
| IMAQ_IMAGE_COMPLEX | IMAQ_IMAGE_RGB, IMAQ_IMAGE_RGB_U64 | The function sets each color component of the destination value to the magnitude of the source value. |
| IMAQ_IMAGE_COMPLEX | IMAQ_IMAGE_HSL | The function sets the luminance component of the destination value to the magnitude of the source value, and it sets the hue and saturation components to 0. |
| IMAQ_IMAGE_U16 | IMAQ_IMAGE_I16 | The function sets the destination value to the source value. If the source value is out of the range of the destination, the function coerces the source to the range. |
| IMAQ_IMAGE_I16 | IMAQ_IMAGE_U16 | The function sets the destination value to the source value. If the source value is out of the range of the destination, the function coerces the source to the range. |