This crate provides native rust implementations of image encoders and decoders and 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.
|PNG||All supported color types||Same as decoding|
|JPEG||Baseline and progressive||Baseline JPEG|
|BMP||Yes||RGB(8), RGBA(8), Gray(8), GrayA(8)|
|TIFF||Baseline(no fax support) + LZW + PackBits||RGB(8), RGBA(8), Gray(8)|
|WebP||Lossy(Luma channel only)||No|
|PNM||PBM, PGM, PPM, standard PAM||Yes|
|DDS||DXT1, DXT3, DXT5||No|
|TGA||Yes||RGB(8), RGBA(8), BGR(8), BGRA(8), Gray(8), GrayA(8)|
There exists a huge variety of image formats that are concerned with efficiently encoding image
pixel data and auxiliary meta data for many different purposes. The
image library provides
decoders for many common formats, depending on the active features. The best way to use them
depends on your use case.
openis a very simple way to load images from the file system, automatically deducing the format but offering little customization.
load_from_memory_with_formatpresent a similar interface for images whose encoded data is already present in memory.
io::Readeris a builder providing a superset of the functions. It offers both customization and auto-deduction but is slightly more involved. The main benefit is that the interface is easier to evolve.
ImageDecoderis a trait for querying meta data and reading image pixels into a generic byte buffer. It also contains a
Readadaptor for stream reading the pixels.
DynamicImage::from_decodercan be used for creating a buffer from a single specific or any custom decoder implementing the
Encoding pixel data is supported for the majority of formats but not quite as broadly.
DynamicImage::saveis the converse of
openand stores a
DynamicImage::write_tocan be used to encode an image into any writer, for example into a vector of bytes in memory.
save_buffer_with_formatprovide a low-level interface for saving an image in the file system, where the library initializes the chosen encoder.
ImageEncoderis a trait for encoding a byte buffer of image data and the inverse of the
The library adds containers for channel data which together form some representation of a 2D
matrix of pixels. These are all statically typed to avoid misinterpretation of byte data (and
since Rust has no standard safe encapsulation for reinterpreting byte slices as another type).
The main traits
GenericImage model a view on a 2D-matrix of
addressable pixels and a buffer of independently accessible pixels respectively.
flat module contains items for interoperability with generic channel
matrices and foreign interface. While still strictly typed, these dynamically validate length and
other layout assumptions required to provide the trait interface. While they are quite generic, you
should be prepared for a bit of boilerplate when using these types.
One of the main goals of
image is stability, in runtime but also for programmers. This
ensures that performance as well as safety fixes reach a majority of its user base with little
effort. Re-exporting all details of its dependencies would run counter to this goal as it
linked all major version bumps between them and
image. As such, we are wary of exposing too
many details, or configuration options, that are not shared between different image formats.
Nevertheless, the advantage of precise control is hard to ignore. We will thus consider wrappers, not direct re-exports, in either of the following cases:
- A standard specifies that configuration x is required for decoders/encoders and there exists an essentially canonical way to control it.
- At least two different implementations agree on some (sub-)set of features in practice.
- A technical argument including measurements of the performance, space benefits, or otherwise objectively quantified benefits can be made, and the added interface is unlikely to require breaking changes.
Features that fulfill two or more criteria are preferred.
Re-exports of dependencies that reach version
1 will be discussed when it happens.
Decoding and Encoding of BMP Images
Iterators and other auxiliary structure for the
Decoding of DDS images
Decoding of DXT (S3TC) compression
Contains detailed error representation.
Decoding of farbfeld images
Image representations for ffi.
Decoding of GIF Images
Decoding of Radiance HDR Images
Decoding and Encoding of ICO files
Image Processing Functions
Input and output of images.
Decoding and Encoding of JPEG Images
Mathematical helper functions and types.
Decoding and Encoding of PNG Images
Decoding of netpbm image formats (pbm, pgm, ppm and pam).
Decoding of TGA Images
Decoding and Encoding of TIFF Images
Decoding of WebP Images
BGR colors + alpha channel
The delay of a frame relative to the previous one.
A single animation frame
An implementation dependent iterator, reading the frames as requested
Generic image buffer
Grayscale colors + alpha channel
Immutable pixel iterator
Represents the progress of an image operation.
RGB colors + alpha channel
A View into another image
An enumeration over supported color types and bit depths
A Dynamic Image
An enumeration of color types encountered in image formats.
An enumeration of supported image formats. Not all formats support both encoding and decoding.
An enumeration of supported image formats for encoding.
Types which are safe to treat as an immutable byte slice in a pixel layout for image encoding.
A trait for manipulating images.
Trait to inspect an image.
The trait that all decoders implement
Specialized image decoding not be supported by all formats
The trait all encoders implement
A generalized pixel.
Primitive trait from old stdlib
Guess image format from memory block
Read the dimensions of the image located at the specified path. This is faster than fully loading the image and then getting its dimensions.
Create a new image from a Reader
Create a new image from a byte slice
Create a new image from a byte slice
Open the image located at the path specified. The image's format is determined from the path's file extension.
Saves the supplied buffer to a file at the path specified.
Saves the supplied buffer to a file at the path specified in the specified format.
Sendable grayscale + alpha channel image buffer
Sendable grayscale image buffer
Sendable Rgb image buffer
Sendable Rgb + alpha channel image buffer