Image Util: Encoding, Decoding, and Transforming Images

This tutorial demonstrates how you can convert, resize, rotate, and crop an image, and decode and encode a JPEG image.

Warm-up

Become familiar with the Image Util API basics by learning about:

Initializing Image Utilities
Initialize the image utilities for use.
Image manipulation
- Converting the Color Space
  Convert an image from one color space to another.
- Resizing an Image
  Resize an image.
- Rotating an Image
  Rotate an image.
- Cropping an Image
  Crop an image.
Decoding from a File or Memory
Decode a JPEG image from a file or from memory.
Encoding to a File or Memory
Encode raw image data to a JPEG file or to memory in the JPEG format.

Initializing Image Utilities

To initialize image utilities for use:

To use the functions and data types of the Image Util API (in mobile and wearable applications), include the <image_util.h> header file in your application:
```
#include <image_util.h>
```
To ensure that an Image Util function has been executed properly, make sure that the return value is equal to IMAGE_UTIL_ERROR_NONE.

Declare the required variables:

#define SAMPLE_FILENAME "sample_image.jpg"
#define OUTPUT_ROTATED_JPEG "rotated_image.jpg"

const image_util_colorspace_e colorspace = IMAGE_UTIL_COLORSPACE_RGB888;
unsigned char *img_rotate_target = NULL;
unsigned char *img_source = NULL;
int ret = 0;
int width = 0, height = 0;
unsigned int size_decode = 0;

To find out which JPEG color spaces are supported on the device, use the image_util_foreach_supported_jpeg_colorspace() function:
```
int image_util_foreach_supported_jpeg_colorspace(image_util_supported_jpeg_colorspace_cb callback,
                                                 void * user_data);
```
The possible color spaces are defined in the image_util_colorspace_e enumeration (in mobile and wearable applications).

For more information about the YUV color space, see http://www.fourcc.org/yuv.php.

To support the image_util_transform_run() function, which is used for all image transformations, set the source image and create a handle for it (to be used as the second parameter):

ret = image_util_decode_jpeg(SAMPLE_FILENAME, colorspace, &img_source,
                             &width, &height, &size_decode);

ret = media_format_create(&fmt);
ret = media_format_set_video_mime(fmt, colorspace);
ret = media_format_set_video_width(fmt, width);
ret = media_format_set_video_height(fmt, height);

ret = media_packet_create_alloc(fmt, NULL, NULL, &src);
ret = media_packet_get_buffer_size(src, &size);

src = malloc(size);
ret = media_packet_get_buffer_data_ptr(src, &src_ptr);
ret = memcpy(src_ptr, img_source, size);

Converting the Color Space

To convert an image from one color space to another:

Create a transformation handle using the image_util_transform_create() function:
```
transformation_h handle;
ret = image_util_transform_create(&handle);
```
Optionally, enable hardware acceleration using the image_util_transform_set_hardware_acceleration() function:
```
ret = image_util_transform_set_hardware_acceleration(handle, true);
```
Set the target color space using the image_util_transform_set_colorspace() function:
```
ret = image_util_transform_set_colorspace(handle, colorspace);
```

Execute the transformation using the image_util_transform_run() function:

ret = image_util_transform_run(handle, src,
                               (image_util_transform_completed_cb)completed_callback,
                               user_data);

Note
Here, the image_util_transform_run() function only converts the color space. The function does not change the image width or height, or any other image property. Because of the restrictions of the image processing library, not all color space combinations are supported for conversion. For example, the NV12 format is commonly used in hardware chips, but it is not supported by the library. If hardware acceleration is enabled, you can execute 2 more image transformations using the same transformation handle.

Note

Here, the image_util_transform_run() function only converts the color space. The function does not change the image width or height, or any other image property.
Because of the restrictions of the image processing library, not all color space combinations are supported for conversion. For example, the NV12 format is commonly used in hardware chips, but it is not supported by the library.
If hardware acceleration is enabled, you can execute 2 more image transformations using the same transformation handle.

Handle the transformation results in the image_util_transform_completed_cb() callback, which is invoked after the transformation is complete.
After the transformation is complete, destroy the transformation handle using the image_util_transform_destroy() function:
```
ret = image_util_transform_destroy(handle);
```

Resizing an Image

To resize an image:

Create a transformation handle using the image_util_transform_create() function:
```
transformation_h handle;
ret = image_util_transform_create(&handle);
```
Optionally, enable hardware acceleration using the image_util_transform_set_hardware_acceleration() function:
```
ret = image_util_transform_set_hardware_acceleration(handle, true);
```
Set the target resolution using the image_util_transform_set_resolution() function:
```
ret = image_util_transform_set_resolution(handle, width, height);
```

Execute the transformation using the image_util_transform_run() function:

ret = image_util_transform_run(handle, src,
                               (image_util_transform_completed_cb)completed_callback,
                               user_data);

Note
The image format has no effect on the transformation. If the color space is YUV, the target image width and height must be multiples of 8. This restriction does not apply to RGB images. If hardware acceleration is enabled, you can execute 2 more image transformations using the same transformation handle.

Handle the transformation results in the image_util_transform_completed_cb() callback, which is invoked after the transformation is complete.
After the transformation is complete, destroy the transformation handle using the image_util_transform_destroy() function:
```
ret = image_util_transform_destroy(handle);
```

Rotating an Image

To rotate an image:

Create a transformation handle using the image_util_transform_create() function:
```
transformation_h handle;
ret = image_util_transform_create(&handle);
```
Optionally, enable hardware acceleration using the image_util_transform_set_hardware_acceleration() function:
```
ret = image_util_transform_set_hardware_acceleration(handle, true);
```
Set the amount of rotation using the image_util_transform_set_rotation() function:
```
ret = image_util_transform_set_rotation(handle, rotation);
```
The possible values for the rotation parameter are defined in the image_util_rotation_e enumeration (in mobile and wearable applications).

Execute the transformation using the image_util_transform_run() function:

ret = image_util_transform_run(handle, src,
                               (image_util_transform_completed_cb)completed_callback,
                               user_data);

Note
The image format has no effect on the transformation. If the color space is YUV, the target image width and height must be multiples of 8. This restriction does not apply to RGB images. If hardware acceleration is enabled, you can execute 2 more image transformations using the same transformation handle.

Handle the transformation results in the image_util_transform_completed_cb() callback, which is invoked after the transformation is complete.
After the transformation is complete, destroy the transformation handle using the image_util_transform_destroy() function:
```
ret = image_util_transform_destroy(handle);
```

Cropping an Image

To crop an image:

Create a transformation handle using the image_util_transform_create() function:
```
transformation_h handle;
ret = image_util_transform_create(&handle);
```
Optionally, enable hardware acceleration using the image_util_transform_set_hardware_acceleration() function:
```
ret = image_util_transform_set_hardware_acceleration(handle, true);
```

Set the crop area using the image_util_transform_set_crop_area() function:

ret = image_util_transform_set_crop_area(handle, start_x, start_y, end_x, end_y);

Execute the transformation using the image_util_transform_run() function:

ret = image_util_transform_run(handle, src,
                               (image_util_transform_completed_cb)completed_callback,
                               user_data);

Note
Because of a YUV restriction, and because the crop start position can be set arbitrarily, the cropped image width and height must be even. If hardware acceleration is enabled, you can execute 2 more image transformations using the same transformation handle.

Handle the transformation results in the image_util_transform_completed_cb() callback, which is invoked after the transformation is complete.
After the transformation is complete, destroy the transformation handle using the image_util_transform_destroy() function:
```
ret = image_util_transform_destroy(handle);
```

Decoding from a File or Memory

To decode a JPEG image:

To decode the image from a file, use the image_util_decode_jpeg() function. Manually allocate the memory for the image buffer based on a calculated buffer size.

ret = image_util_decode_jpeg(SAMPLE_FILENAME, colorspace, &img_source,
                             &width, &height, &size_decode);

To decode the image from memory, use the image_util_decode_jpeg_from_memory() function. Manually allocate the memory for the image buffer based on a calculated buffer size.

ret = image_util_decode_jpeg_from_memory(jpeg_buffer, jpeg_size, colorspace,
                                         image_buffer, width, height, size);

Encoding to a File or Memory

To encode a rotated or flipped image:

To encode the image to a JPEG file, use the image_util_encode_jpeg() function:

ret = image_util_encode_jpeg(img_flip_target, dest_width, dest_height,
                             colorspace, 100, OUTPUT_ROTATED_JPEG);

To encode the image to memory in the JPEG format, use the image_util_encode_jpeg_to_memory() function:

ret = image_util_encode_jpeg_to_memory(img_flip_target, dest_width, dest_height,
                                       colorspace, 100, jpeg_buffer, jpeg_size);