[−][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 this library provides solutions: a unified interface for images encodings and simple generic buffers for their content. It's possible to use either feature without the other. The focus is on 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 | No |
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 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
are 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 strict typed these dynamically validate length and
other layout assumptions required to provide the trait interface. While quite generic You
should be prepared for a bit of boilerplate when using these types.
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 |
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 |