Overview

This crate provides native rust implementations of image encoding and decoding as well as some basic image manipulation functions. Additional documentation can currently also be found in the README.md file which is most easily viewed on github.

There are two core problems for which this library provides solutions: a unified interface for image encodings and simple generic buffers for their content. It's possible to use either feature without the other. The focus is on a small and stable set of common operations that can be supplemented by other specialized crates. The library also prefers safe solutions with few dependencies.

High level API

Load images using ImageReader:

use std::io::Cursor;
use image::ImageReader;
# fn main() -> Result<(), image::ImageError> {
# let bytes = vec![0u8];

let img = ImageReader::open("myimage.png")?.decode()?;
let img2 = ImageReader::new(Cursor::new(bytes)).with_guessed_format()?.decode()?;
# Ok(())
# }

And save them using save or write_to methods:

# use std::io::{Write, Cursor};
# use image::{DynamicImage, ImageFormat};
# #[cfg(feature = "png")]
# fn main() -> Result<(), image::ImageError> {
# let img: DynamicImage = unimplemented!();
# let img2: DynamicImage = unimplemented!();
img.save("empty.jpg")?;

let mut bytes: Vec<u8> = Vec::new();
img2.write_to(&mut Cursor::new(&mut bytes), image::ImageFormat::Png)?;
# Ok(())
# }
# #[cfg(not(feature = "png"))] fn main() {}

With default features, the crate includes support for many common image formats.

Image buffers

The two main types for storing images:

• ImageBuffer which holds statically typed image contents.
• DynamicImage which is an enum over the supported ImageBuffer formats and supports conversions between them.

As well as a few more specialized options:

• GenericImage trait for a mutable image buffer.
• GenericImageView trait for read only references to a GenericImage.
• flat module containing types for interoperability with generic channel matrices and foreign interfaces.

Low level encoding/decoding API

Implementations of ImageEncoder provides low level control over encoding:

# use std::io::Write;
# use image::DynamicImage;
# use image::ImageEncoder;
# #[cfg(feature = "jpeg")]
# fn main() -> Result<(), image::ImageError> {
# use image::codecs::jpeg::JpegEncoder;
# let img: DynamicImage = unimplemented!();
# let writer: Box<dyn Write> = unimplemented!();
let encoder = JpegEncoder::new_with_quality(&mut writer, 95);
img.write_with_encoder(encoder)?;
# Ok(())
# }
# #[cfg(not(feature = "jpeg"))] fn main() {}

While ImageDecoder and ImageDecoderRect give access to more advanced decoding options:

# use std::io::{BufReader, Cursor};
# use image::DynamicImage;
# use image::ImageDecoder;
# #[cfg(feature = "png")]
# fn main() -> Result<(), image::ImageError> {
# use image::codecs::png::PngDecoder;
# let img: DynamicImage = unimplemented!();
# let reader: BufReader<Cursor<&[u8]>> = unimplemented!();
let decoder = PngDecoder::new(&mut reader)?;
let icc = decoder.icc_profile();
let img = DynamicImage::from_decoder(decoder)?;
# Ok(())
# }
# #[cfg(not(feature = "png"))] fn main() {}