Crate turbojpeg

Rust bindings for TurboJPEG, which provides simple and fast operations for JPEG images:

• Compression: encode images into JPEG.
• Decompression: decode JPEGs into pixels.
• Lossless transformations: apply basic geometric transformations (rotate, mirror, …) without going through decompression and compression, so that the image does not lose quality.
• Decompression into YUV: decode JPEG into YUV (YCbCr), without performing the color transform into RGB.

Integration with image-rs (version 0.24)

To easily encode and decode images from the image crate (version 0.24), please enable the optional dependency "image" of this crate in your Cargo.toml. Then you can use the functions decompress_image() and compress_image():

// read JPEG data from file
let jpeg_data = std::fs::read("examples/parrots.jpg")?;

// decompress `jpeg_data` into an `image::RgbImage`
let image: image::RgbImage = turbojpeg::decompress_image(&jpeg_data)?;

// compress `image` into JPEG with quality 95 and 2x2 chrominance subsampling
let jpeg_data = turbojpeg::compress_image(&image, 95, turbojpeg::Subsamp::Sub2x2)?;

This crate supports these specializations of image::ImageBuffer:

• image::RgbImage
• image::RgbaImage (JPEG does not support alpha channel, so alpha is ignored when encoding and set to 255 when decoding)
• image::GrayImage

The Image type

For more advanced usage of TurboJPEG, you will need to use the Image type. This is a simple struct that contains the geometry of the image (width, height and pitch/stride), pixel format (such as RGB, ABGR or grayscale) and the pixel data itself.

Image is parameterized by the pixel data container, so you will use Image<&[u8]> as input argument for compression, Image<&out [u8]> as output argument for decompression, and you may also find Image<Vec<u8>> useful as an owned container of image data in you application.

Operations

• Decompress images from JPEG using decompress() or Decompressor.
• Compress images into JPEG using compress() or Compressor.
• Transform images without recompression using transform() or Transformer. The transformations are described in the Transform struct.
• Read header of JPEG image to get its size without decompression using Decompressor::read_header() or read_header().
• Decompress images into YUV using decompress_to_yuv() or Decompressor.
• Compress images from YUV using compress_yuv() or Compressor.

The OutputBuf and OwnedBuf types

During compression, we need to write the produced JPEG data into some memory buffer. You have two options:

• Write the data into a mutable slice (&mut [u8]) that you already allocated and initialized. This has the disadvantage that you must allocate all memory up front, so you need to make the buffer very large to ensure that it can hold the compressed image even in the worst case, when the compression does not reduce the image size at all. You will also need to initialize the memory to comply with the Rust safety requirements.

• Write the data into a memory buffer managed by TurboJPEG. This has the advantage that TurboJPEG can automatically resize the buffer, so we don’t have to conservatively allocate and initialize a large chunk of memory, but we can let TurboJPEG grow the buffer as needed. This kind of buffer is exposed as the OwnedBuf.

To handle both of these cases, this crate provides the OutputBuf type, which can hold either a &mut [u8] or an OwnedBuf.

Features

• image: enables the optional dependency on the image crate.
• pkg-config: uses pkg-config to find the libturbojpeg library.
• bindgen: uses bindgen to generate the libturbojpeg bindings.

Re-exports

• pub extern crate image as image;
• pub extern crate libc;
• pub extern crate turbojpeg_sys as raw;

Structs

• Compressor
  Compresses raw pixel data into JPEG.
• DecompressHeader
  JPEG header that describes the compressed image.
• Decompressor
  Decompresses JPEG data into raw pixels.
• Image
  An image with pixels of type T.
• OutputBuf
  Output buffer for JPEG data (borrowed or owned).
• OwnedBuf
  Owned buffer with JPEG data.
• Transform
  Lossless transform of a JPEG image.
• TransformCrop
  Transform cropping region.
• Transformer
  Transforms JPEG images without recompression.
• YuvImage
  A YUV (YCbCr) planar image with pixels of type T.

Enums

• Colorspace
  JPEG colorspaces.
• Error
  An error that can occur in TurboJPEG.
• PixelFormat
  Pixel format determines the layout of pixels in memory.
• Subsamp
  Chrominance subsampling options.
• TransformOp
  Transform operation.

Traits

• JpegPixel
  Trait implemented for image::Pixels that correspond to a PixelFormat supported by TurboJPEG.

Functions

• compress
  Compress an image to JPEG.
• compress_image
  Compresses an image::ImageBuffer into JPEG.
• compress_yuv
  Compress a YUV image to JPEG.
• compressed_buf_len
  Compute the maximum size of a compressed image.
• decompress
  Decompress a JPEG image.
• decompress_image
  Decompresses image from JPEG into an image::ImageBuffer.
• decompress_to_yuv
  Decompress a JPEG image to YUV.
• read_header
  Read the JPEG header without decompressing the image.
• transform
  Losslessly transform a JPEG image without recompression.
• yuv_pixels_len
  Determine size in bytes of a YUV image.

Type Aliases

• Result
  Specialized Result type for TurboJPEG.