[−][src]Crate image
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.
Overview
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.
Format | Decoding | Encoding |
---|---|---|
PNG | All supported color types | Same as decoding |
JPEG | Baseline and progressive | Baseline JPEG |
GIF | Yes | Yes |
BMP | Yes | RGB(8), RGBA(8), Gray(8), GrayA(8) |
ICO | Yes | Yes |
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) |
farbfeld | Yes | Yes |
Using images decoders
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.
open
is a very simple way to load images from the file system, automatically deducing the format but offering little customization.load_from_memory
,load_from_memory_with_format
present a similar interface for images whose encoded data is already present in memory.io::Reader
is 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.ImageDecoder
is a trait for querying meta data and reading image pixels into a generic byte buffer. It also contains aRead
adaptor for stream reading the pixels.DynamicImage::from_decoder
can be used for creating a buffer from a single specific or any custom decoder implementing theImageDecoder
trait.
Using image encoders
Encoding pixel data is supported for the majority of formats but not quite as broadly.
DynamicImage::save
is the converse ofopen
and stores aDynamicImage
.DynamicImage::write_to
can be used to encode an image into any writer, for example into a vector of bytes in memory.save_buffer
,save_buffer_with_format
provide a low-level interface for saving an image in the file system, where the library initializes the chosen encoder.ImageEncoder
is a trait for encoding a byte buffer of image data and the inverse of theImageDecoder
interface.
Image buffers
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 GenericImageView
and GenericImage
model a view on a 2D-matrix of
addressable pixels and a buffer of independently accessible pixels respectively.
The two main types for owning pixel data are ImageBuffer
and DynamicImage
. Note that
the latter is an enum over well-supported pixel types that also offers conversion
functionality.
Additionally, the 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.
A note on format specific features
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.
Re-exports
pub use crate::error::ImageError; |
pub use crate::error::ImageResult; |
pub use crate::flat::FlatSamples; |
Modules
bmp | Decoding and Encoding of BMP Images |
buffer | Iterators and other auxiliary structure for the |
dds | Decoding of DDS images |
dxt | Decoding of DXT (S3TC) compression |
error | Contains detailed error representation. |
farbfeld | Decoding of farbfeld images |
flat | Image representations for ffi. |
gif | Decoding of GIF Images |
hdr | Decoding of Radiance HDR Images |
ico | Decoding and Encoding of ICO files |
imageops | Image Processing Functions |
io | Input and output of images. |
jpeg | Decoding and Encoding of JPEG Images |
math | Mathematical helper functions and types. |
png | Decoding and Encoding of PNG Images |
pnm | Decoding of netpbm image formats (pbm, pgm, ppm and pam). |
tga | Decoding of TGA Images |
tiff | Decoding and Encoding of TIFF Images |
webp | Decoding of WebP Images |
Structs
Bgr | BGR colors |
Bgra | BGR colors + alpha channel |
Delay | The delay of a frame relative to the previous one. |
Frame | A single animation frame |
Frames | An implementation dependent iterator, reading the frames as requested |
ImageBuffer | Generic image buffer |
Luma | Grayscale colors |
LumaA | Grayscale colors + alpha channel |
Pixels | Immutable pixel iterator |
Progress | Represents the progress of an image operation. |
Rgb | RGB colors |
Rgba | RGB colors + alpha channel |
SubImage | A View into another image |
Enums
ColorType | An enumeration over supported color types and bit depths |
DynamicImage | A Dynamic Image |
ExtendedColorType | An enumeration of color types encountered in image formats. |
ImageFormat | An enumeration of supported image formats. Not all formats support both encoding and decoding. |
ImageOutputFormat | An enumeration of supported image formats for encoding. |
Traits
AnimationDecoder | AnimationDecoder trait |
EncodableLayout | Types which are safe to treat as an immutable byte slice in a pixel layout for image encoding. |
GenericImage | A trait for manipulating images. |
GenericImageView | Trait to inspect an image. |
ImageDecoder | The trait that all decoders implement |
ImageDecoderExt | Specialized image decoding not be supported by all formats |
ImageEncoder | The trait all encoders implement |
Pixel | A generalized pixel. |
Primitive | Primitive trait from old stdlib |
Functions
guess_format | Guess image format from memory block |
image_dimensions | Read the dimensions of the image located at the specified path. This is faster than fully loading the image and then getting its dimensions. |
load | Create a new image from a Reader |
load_from_memory | Create a new image from a byte slice |
load_from_memory_with_format | Create a new image from a byte slice |
open | Open the image located at the path specified. The image's format is determined from the path's file extension. |
save_buffer | Saves the supplied buffer to a file at the path specified. |
save_buffer_with_format | Saves the supplied buffer to a file at the path specified in the specified format. |
Type Definitions
GrayAlphaImage | Sendable grayscale + alpha channel image buffer |
GrayImage | Sendable grayscale image buffer |
RgbImage | Sendable Rgb image buffer |
RgbaImage | Sendable Rgb + alpha channel image buffer |