Skip to content

TurboJPEG plugin

Jump to bottom
dromagnoli edited this page Jan 14, 2013 · 2 revisions

Table of Contents

LibJPEG Turbo Bindings

The LibJPEG Turbo project aims to provide an ImageWriter/ImageReader implementation on top of the LibJpeg Turbo which is both a C low-level library API which uses SIMD instructions to accelerate JPEG encoding as well as the name of the project which provides this library. That project also provides a higher-level set of API, known as TurboJPEG/OSS, which is built on top of the lower-level libjpeg-turbo, by exposing a simpler set of methods. See LibJpeg Turbo for additional information on it.
The GeoSolutions LibJPEG Turbo bindings currently leverage on TurboJpeg libs through JAVA bindings.

  • tj-1.1.x branch is based on Java bindings created on top of TurboJpeg 1.1.1, through the JNAerator and bridj tools with these steps.
  • master branch is instead based on Java bindings available from the TurboJpeg 1.2 series with these steps.

Installation

Required .so libraries are available at: http://sourceforge.net/projects/libjpeg-turbo/files/
Download the version you need and make sure they are referred by the LD_LIBRARY_PATH environment variable.

TurboJpegImageWriter

Let us put together some information about how the TurboJpegImageWriter works.

The writing operation does the following steps:

  • takes the bytes related to the image to be compressed
  • pass them to the underlying TurboJPEG native library together with a set of additional flags and parameters to customize the compression, which are exposed through [#TurboJpegImageWriteParam]
  • get back a byte array containing the JPEG encoded bytes
  • write the bytes to the specified output stream (which needs to be an instance of OutputStream/ImageOutputStreamAdapter2/File)

TurboJpegImageWriteParam

Now we are going to introduce some information on the parameters that we can use to control how the TurboJpegImageWriter will encode images:

  • Quality default is 0.75f. Valid values are within 0 and 1
  • Compression Types, the only supported one is JPEG
  • EXIFMetadata an instance of EXIFMetada object representing EXIF to be put into the encoded JPEG image.
  • componentSubsampling represents the Chrominance subsampling factor applied by the turbojpeg library. Supported values are (They may slightly change between TurboJPEG version 1.1 and 1.2) :
    • TJ_444 : 4:4:4 chrominance subsampling (no chrominance subsampling). The JPEG or YUV image will contain one chrominance component for every pixel in the source image.
    • TJ_422 : 4:2:2 chrominance subsampling. The JPEG or YUV image will contain one chrominance component for every 2x1 block of pixels in the source image.
    • TJ_420 : 4:2:0 chrominance subsampling. The JPEG or YUV image will contain one chrominance component for every 2x2 block of pixels in the source image.
    • TJ_GRAYSCALE : Grayscale. The JPEG or YUV image will contain no chrominance components.
Quoting from turboJpeg documentation:
When an image is converted from the RGB to the YCbCr colorspace as part of the JPEG compression process, some of the Cb and Cr (chrominance) components can be discarded or averaged together to produce a smaller image with little perceptible loss of image clarity (the human eye is more sensitive to small changes in brightness than small changes in color.) This is called "chrominance subsampling".

TurboJpegImageReader

The reader takes the data from a byte array or from a Stream, and passes the data to the turbojpeg binary library via a byte array. A set of params can be specified when decompressing (see next subsection).

The output BufferedImage type can be either BufferedImage.TYPE_BYTE_GRAY or BufferedImage.TYPE_3BYTE_BGR.

Setting reader properties

You may need to setup some properties for your reader. You can do so by setting the property it.geosolutions.imageio.plugins.turbojpeg.flags to a comma separated list of values among: FLAG_ACCURATEDCT, FLAG_BOTTOMUP, FLAG_FASTDCT, FLAG_FASTUPSAMPLE, FLAG_FORCEMMX, FLAG_FORCESSE, FLAG_FORCESSE2, FLAG_FORCESSE3. By default FLAG_FASTUPSAMPLE is used.

Since the reader properties are set via a system prop, they are shared between all the reader instances.

TurboJpegUtilities

This utility class contains some utility methods ported from the TurboJPEG C code, basically involving destination buffer size computation.
Finally, it also contains the isAvailable() method which allows to check whether the underlying TurboJPEG native libraries have been found/loaded.

Exif Support

The TurboJPEG library doesn't provide any support to put/add EXIF within a JPEG encode image. Therefore, we have setup Exif Support Utility classes which allows to setup EXIF object to be put into the output stream when writing the bytes resulting from the compression operation.

Clone this wiki locally