Crate turbojpeg

Expand description

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.
Fractional scaling during decompression: save time and memory by downscaling or upscaling the JPEG image while decoding.

§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.
ScalingFactor: Fractional scaling factor.
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.

Crate turbojpegCopy item path