L_IntelligentDownScaleBitmap

#include "l_bitmap.h"

L_LTIMGSFX_API L_INT L_IntelligentDownScaleBitmap (pBitmap, pMaskBitmap, crRemoveObjectColor, crPreserveObjectColor, nNewWidth, nNewHeight, nDownScalingOrder, uFlags)

pBITMAPHANDLE pBitmap;

/* pointer to the bitmap handle */

pBITMAPHANDLE pMaskBitmap;

/* pointer to the mask bitmap handle */

COLORREF crRemoveObjectColor;

/* color of removed area */

COLORREF crPreserveObjectColor;

/* color of preserved area */

L_INT nNewWidth;

/* new width */

L_INT nNewHeight;

/* new height */

L_INT nDownScalingOrder;

/* downscaling behavior */

L_UINT32 uFlags;

/* reserved for future */

Reduces the image size while preserving important features automatically. Also, it can remove or preserve certain objects chosen by the user without affecting the natural look of the image.

This feature is available in version 16 or higher.

Parameter

Description

pBitmap

Pointer to the bitmap handle referencing the bitmap on which to apply effect.

pMaskBitmap

Pointer to the bitmap handle that references the mask bitmap. The mask bitmap is the same image as the original image but uses a color on certain areas that need to be removed or preserved during the downscaling operation. Pass NULL if there is no mask bitmap. Pass a bitmap the same size as pBitmap to avoid having the function return ERROR_INV_PARAMETER.

crRemoveObjectColor

COLORREF value that specifies the color of the area in the mask bitmap to be removed. It is preferred to be different than the colors used in the image in the pBitmap. Pass INTELLIGENTRESCALE_NOREMOVECOLOR if you do not want to pass any color value.

crPreserveObjectColor

COLORREF value that specifies the color of the area in the mask bitmap to be preserved. It is preferred to be different than the color specified in crRemoveObjectColor and colors used in the image in the pBitmap. Pass INTELLIGENTRESCALE_NOREMOVECOLOR if you do not want to pass a color value.

nNewWidth

New width in pixels. Possible values are range from 1 to (width of the image -1).

nNewHeight

New height in pixels. Possible values are range from 1 to (height of the image -1).

nDownScalingOrder

Downscaling behavior. Possible values are:

 

Value

Meaning

 

INTELLIGENTRESCALE_VERTHORZ

Downscale the image width first, then the height.

 

INTELLIGENTRESCALE_HORZVERT

Downscale the image height first, then the width.

uFlags

Reserved for future use. Must be zero.

Returns

SUCCESS

The function was successful.

< 1

An error occurred. Refer to Return Codes.

Comments

Sometimes dark areas are affected during downscaling since dark areas are considered to be  "unimportant". To prevent dark objects from being affected during downscaling, negate the image, apply downscaling, then negate the image again to get the colors of original image. Alternatively, apply a mask on the dark objects.

Intelligent downscaling has limitations when images are too condensed or where the content layout prevents the downscaling from being performed correctly without harming important parts.

Downscaling performed using a mask is done only on the width dimension. To downscale using a mask on the height dimension, rotate the image, downscale the width dimension, then rotate the image again.

The mask color for an area being removed must be different from the colors in the image. If multiple "remove" objects are masked, all must have the same mask color.

The mask color of the "preserve" area must be different than colors in the image, and different from the remove area color. If multiple "preserve" objects are masked, then all must have the same mask color.

To make the amount of downscaling equal to the size of remove area, set the new width equal to the image width. This does NOT apply to preserve area and does NOT apply to the intelligent upscaling.

Sometimes, setting the new dimension does not totally delete the remove area. In this case, pass a new width to the original image that is less than the width of the (failed) downscaled image. For instance, if the downscaled image width is 300 pixels, but still has a few lines remaining of the remove area after downscaling reset the width to 290 pixels and re-do the downscale.

If a mask has a preserve area but no remove area, you must specify nNewWidth.

For best results, draw the mask from top to bottom of the image, passing over the remove area. Make the mask wide enough to force downscaling to be performed only in the remove area.

This function does not support 12 or 16-bit grayscale or 48 or 64-bit color images. If the image is 12 or 16-bit grayscale or 48 or 64-bit color, the function will not return an error.

This function does not support signed data images. It returns the error code ERROR_SIGNED_DATA_NOT_SUPPORTED if a signed data image is passed to this function.

This function does not support 32-bit grayscale images. It returns the error code ERROR_GRAY32_UNSUPPORTED if a 32-bit grayscale image is passed to this function.

Required DLLs and Libraries

LTIMGSFX

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

Platforms

Windows 2000 / XP, Windows Vista

See Also

Functions:

L_SizeBitmap, L_SizeBitmapInterpolate, L_IntelligentUpScaleBitmap

Topics:

Raster Image Functions: Intelligent Rescale

 

Introduction: Intelligent Rescale

 

Using the Intelligent Rescale Demo

Example

#if defined (LEADTOOLS_V16_OR_LATER)
L_INT IntelligentDownScaleExample(L_VOID)
{
   L_INT nRet;
   BITMAPHANDLE LeadBitmap;   // Bitmap handle to hold the loaded image.

   nRet=L_LoadBitmap(TEXT("%UserProfile%\\My Documents\\LEADTOOLS Images\\SAMPLE3.CMP"), &LeadBitmap,sizeof(BITMAPHANDLE), 0, ORDER_RGB, NULL, NULL);
   if(nRet !=SUCCESS)
      return nRet;

   nRet=L_IntelligentDownScaleBitmap(&LeadBitmap, NULL, (COLORREF)INTELLIGENTRESCALE_NOREMOVECOLOR, (COLORREF)INTELLIGENTRESCALE_NOPRESERVECOLOR,
      500, LeadBitmap.Height, INTELLIGENTRESCALE_VERTHORZ, 0);

   if(nRet !=SUCCESS)
      return nRet;

   nRet = L_SaveBitmap(TEXT("C:\\Result.BMP"), &LeadBitmap, FILE_BMP, 24, 0, NULL);

   if(nRet !=SUCCESS)
      return nRet;

   return SUCCESS;
}
#endif // LEADTOOLS_V16_OR_LATER