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.
§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()
orDecompressor
. - Compress images into JPEG using
compress()
orCompressor
. - Transform images without recompression using
transform()
orTransformer
. The transformations are described in theTransform
struct. - Read header of JPEG image to get its size without decompression using
Decompressor::read_header()
orread_header()
. - Decompress images into YUV using
decompress_to_yuv()
orDecompressor
. - Compress images from YUV using
compress_yuv()
orCompressor
.
§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
Re-exports§
pub extern crate image as image;
pub extern crate libc;
pub extern crate turbojpeg_sys as raw;
Structs§
- Compresses raw pixel data into JPEG.
- JPEG header that describes the compressed image.
- Decompresses JPEG data into raw pixels.
- An image with pixels of type
T
. - Output buffer for JPEG data (borrowed or owned).
- Owned buffer with JPEG data.
- Lossless transform of a JPEG image.
- Transform cropping region.
- Transforms JPEG images without recompression.
- A YUV (YCbCr) planar image with pixels of type
T
.
Enums§
- JPEG colorspaces.
- An error that can occur in TurboJPEG.
- Pixel format determines the layout of pixels in memory.
- Chrominance subsampling options.
- Transform operation.
Traits§
- Trait implemented for
image::Pixel
s that correspond to aPixelFormat
supported by TurboJPEG.
Functions§
- Compress an image to JPEG.
- Compresses an
image::ImageBuffer
into JPEG. - Compress a YUV image to JPEG.
- Compute the maximum size of a compressed image.
- Decompress a JPEG image.
- Decompresses image from JPEG into an
image::ImageBuffer
. - Decompress a JPEG image to YUV.
- Read the JPEG header without decompressing the image.
- Losslessly transform a JPEG image without recompression.
- Determine size in bytes of a YUV image.
Type Aliases§
- Specialized
Result
type for TurboJPEG.