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

Notes on the Reference Adaptation of Image Transform Extensions

A reference adaptation is shipped with Symbian based on Scalado CAPS. This section notes any plugin specific information.

The CAPS adaptation of the Orientation and Overlay extensions may fail on images with optimised Huffman tables.
Transforms through the CAPS adaptation are lossless where possible. The standard way of rotating a JPEG image requires a decoding and a subsequent encoding which will cause a loss of data. The main advantage is however, that the operation will be very fast as no decoding is taken place.
The CAPS adaptation supports overlay of PNG and JPEG images onto the main JPEG image.
The CAPS adaptation for squeeze and auto-resize uses statistics when determining the size and encoding quality for the new image file. These settings vary a lot depending on the qualities of the images. In order for auto-resize to function satisfactorily it may be necessary to tune the algorithm on representative images, i.e. images taken by the target device camera.