JPEG +Image Transform Extension Guide

This document introduces you to the JPEG image transform extensions.

Purpose

The +Image Transform framework supports standard extensions for advanced JPEG functions.

The +functions are,

Orientation (Rotation and Mirror over horizontal and vertical Axis)
Overlay
Squeeze

Orientation

The +COrientationTransformExtension extension to CImageTransform allows you to +rotate in steps of 90 degrees or to mirror a JPEG file either from file or +memory.

When you require an Image Transform plugin which supports +the Orientation extension, call CImageTransform::SetTransformationsL() or CImageTransform::EOrientation(). +The client must get the COrientationTransformExtension extension and use this +to set up the required transformation:

+ +IMPORT_C void COrientationTransformExtension::SetOrientationL(TOrientation aOrientation); + +

The orientation changes supported by the COrientationTransformExtension are,

90 degree clockwise
180 degree clockwise
270 degree clockwise
mirroring over the vertical +axis
mirroring over the horizontal +axis
transpose over the main +diagonal
transpose over the minor +diagonal.

In the example function below a JPEG image is rotated by 90 degrees:

+ + // Create the image transform + CImageTransform* imageTransform = CImageTransform::NewL(iFs); + CleanupStack::PushL(imageTransform); + + // Setup the image transform + imageTransform->SetSourceFilenameL(aSrcFileName); + imageTransform->SetDestFilenameL(aDestFileName); + imageTransform->SetTransformationsL(CImageTransform::EOrientation); + imageTransform->SetupL(); + + // Get the extension plugin supporting orientation + TUid lRotateUid = {KUidOrientationTransformExtension }; + TInt err = KErrNone; + COrientationTransformExtension* lRotateExt = static_cast<COrientationTransformExtension*> + (imageTransform->Extension(lRotateUid, err)); + + // Check here whether the plugin supports this extension or not set the orientation on + // the plugin + lRotateExt->SetOrientationL(COrientationTransformExtension::ERotation90DegreesClockwise); + + // Perform the transformation + imageTransform->Transform(aStatus); + + // CImageTransform::Transform() is an asynchronous function + // and the result of the transformation would be known in the + // RunL() function of the active object associated with the aStatus + +

The image rotation can be performed in the compressed domain +allowing a transformation of the image. Benefits of speed and memory usage +can be obtained dependent on the implementation of the plugin.

Overlay

COverlayTransformExtension extension +to Image Transform framework allows lossless overlay or blend of images. Examples +of the use of COverlayTransformExtension include adding +timestamp or place-stamp, some text or inserting a company logo. The images +below show an example of overlay functionality:

+ +

The image overlay transformation can, depending on its implementation, +be very fast eliminating the need to decode the whole image making it very +useful, for example a camera application. The types of image that can be overlaid +onto the main JPEG image can be discovered through the extension. It is also +possible to overlay a CFbsBitmap. If you need transparency, +then you have to choose an image format supporting a transparency channel +such as PNG.

When you require an Image Transform plugin which supports +the Overlay extension, call CImageTransform::SetTransformationsL() or CImageTransform::EOverlay(). +The client must get the COverlayTransformExtension extension and use this +to set up the required transformation. The client can control the desired +position for overlay, and the transparency for image. The example below show +the successful setup for COverlayTransformExtension with +the JPEG image overlaid by an image at (0,0) position co-ordinates:

+ + // Create the image transform + CImageTransform* imageTransform = CImageTransform::NewL(iFs); + CleanupStack::PushL(imageTransform); + + // Setup the image transform + imageTransform->SetSourceFilenameL(aSrcFileName); + imageTransform->SetDestFilenameL(aDestFileName); + imageTransform->SetTransformationsL(CImageTransform::EOverlay); + imageTransform->SetupL(); + + // Get the extension plugin supporting overlay + TUid lOverlayUid = {KUidOverlayTransformExtension }; + TInt err = KErrNone; + COverlayTransformExtension * lOverlayExt = static_cast< COverlayTransformExtension *> + (imageTransform->Extension(lOverlayUid, err)); + + // Check here whether the plugin supports this extension or not Set the position on + // the plugin + lOverlayExt->Position(TPoint(0,0)); + + // Set the overlay file and its type + lOverlayExt->SetOverlayFileL(aOverlayFileName, KImageTypeJPGUid); + + // Perform the transformation + imageTransform->Transform(aStatus); + + // CImageTransform::Transform() is an asynchronous function + // and the result of the transformation would be known in the + // RunL() function of the active object associated with the aStatus + +

Squeeze

The CSqueezeTransformExtension() extension +to the Image Transform framework allows,

Auto-resize
Squeeze.

A auto-resize adjusts the image size and encoding quality to achieve +a desired file size. If the file size requirement has not been met, then you +can use squeeze to compress the image even further. The JPEG squeeze module +is a convenient tool when creating MMS.

When you require an Image +Transform plugin which supports the Squeeze extension, call CImageTransform::SetTransformationsL() or CImageTransform::ESqueeze().

Squeezing an image can be accomplished through:

+ +IMPORT_C void CSqueezeTransformExtension::SetDestSizeInBytes(TUint aMaxDestDataSize ) ; + +

+ IMPORT_C void SetAdvancedSqueezeModeL(TAdvancedSqueezeParams* aSqueezeAutoResizeParams ) ; +

In the latter case can be made through the use of TAdvancedSqueezeParams::TAutoResizeAction. +The enumeration to do auto resize are,

+ EAutoResizeActionPreserveSourceEncodingQuality for preserving +the source encoding quality while shrinking the width and height of the image
EAutoResizeActionPrioritizeLargeImageSize for +preserving the maxImageSize while lowering the encoding quality
EAutoResizeActionResizePrioritizeHighEncodingQuality for +preserving the highest possible encoding quality while shrinking the width +and height of the image
EAutoResizeActionMiddleCourse for +simultaneously lower the encoding quality and shrink the width and height +of the image.

These settings are used by the auto resize to determine size and +encoding quality for the new image file.

The JPEG squeeze enblaes +images to be set to a enblaes pre-defined size. This is useful if storage +size is critical or if there are limitations when sending images i.e. MMS +file size. The dimensions of the image are preserved; the JPEG compression +ratio being changed to maintain the image size.

Note: The +JPEG squeeze functionality must be used with care. Drastically decreasing +file size will result in poor image quality.

In the below example, +the JPEG image is squeezed to get a file size less than the specified maxium +size:

+ + // Create the image transform + CImageTransform* imageTransform = CImageTransform::NewL(iFs); + CleanupStack::PushL(imageTransform); + // Setup the image transform + imageTransform->SetSourceFilenameL(aSrcFileName); + imageTransform->SetDestFilenameL(aDestFileName); + imageTransform->SetTransformationsL(CImageTransform::ESqueeze); + imageTransform->SetupL(); + // Get the extension plugin supporting squeeze + TUid lSqueezeUid = {KUidSqueezeTransformExtension }; + TInt err = KErrNone; + CSqueezeTransformExtension * lSqueezeExt = static_cast< CSqueezeTransformExtension*> +(imageTransform->Extension(lSqueezeUid, err)); + // Check here whether the plugin supports this extension or not + // Set the max dest size in bytes + lSqueezeExt-> SetDestSizeInBytes(aMaxSizeInBytes); + // Perform the transformation + imageTransform->Transform(aStatus); + // CImageTransform::Transform() is an asynchronous function + // and the result of the transformation would be known in the + // RunL() function of the active object associated with the aStatus + +

The example code below show how the JPEG squeeze image is +used to make an image fulfill the MMS ‘Image Rich’ class constraints, i.e. +file size less than 100k bytes and image size no more than 640*480 pixels.

+ + // Create the image transform + CImageTransform* imageTransform = CImageTransform::NewL(iFs); + CleanupStack::PushL(imageTransform); + // Setup the image transform + imageTransform->SetSourceFilenameL(aSrcFileName); + imageTransform->SetDestFilenameL(aDestFileName); + imageTransform->SetTransformationsL(CImageTransform::ESqueeze); + imageTransform->SetupL(); + // Get the extension plugin supporting squeeze + TUid lSqueezeUid = {KUidSqueezeTransformExtension }; + TInt err = KErrNone; + CSqueezeTransformExtension * lSqueezeExt = static_cast< CSqueezeTransformExtension*> +(imageTransform->Extension(lSqueezeUid, err)); + TInt res = KErrNone; + TInt newSize = 0; + TAdvancedSqueezeParams info ; + + // MMS Image Rich + info.iMaxDestSizeInBytes = 100000; + info.iMaxImageSize.iWidth = 640; + info.iMaxImageSize.iHeight = 480; + info.iMinImageSize. iWidth = 160; + info.iMinImageSize. iHeight = 120; + info.iResizeAction = EAutoResizeActionPrioritizeLargeImageSize; + info.iMinEncodingQuality = 0.5f; + info.iSamplingUid = KUidSamplingColor420; + lSqueezeExt->SetAdvancedSqueezeModeL(&info); + // Perform the transformation + imageTransform->Transform(aStatus); + // CImageTransform::Transform() is an asynchronous function + // and the result of the transformation would be known in the + // RunL() function of the active object associated with the aStatus + +

+ +