[][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.

Jump forward to crate content

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.

FormatDecodingEncoding
PNGAll supported color typesSame as decoding
JPEGBaseline and progressiveBaseline JPEG
GIFYesYes
BMPYesRGB(8), RGBA(8), Gray(8), GrayA(8)
ICOYesYes
TIFFBaseline(no fax support) + LZW + PackBitsRGB(8), RGBA(8), Gray(8)
WebPLossy(Luma channel only)No
PNMPBM, PGM, PPM, standard PAMYes
DDSDXT1, DXT3, DXT5No
TGAYesNo
farbfeldYesYes

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 a Read 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 the ImageDecoder trait.

Using image encoders

Encoding pixel data is supported for the majority of formats but not quite as broadly.

  • DynamicImage::save is converse of open and stores a DynamicImage.
  • 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 the ImageDecoder 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 ImageBuffer type.

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