Struct `ImageReader`

struct ImageReader<R: Read + Seek> { ... }

A multi-format image reader.

Wraps an input reader to facilitate automatic detection of an image's format, appropriate decoding method, and dispatches into the set of supported ImageDecoder implementations.

Usage

Opening a file, deducing the format based on the file path automatically, and trying to decode the image contained can be performed by constructing the reader and immediately consuming it.

# use image::ImageError;
# use image::ImageReader;
# fn main() -> Result<(), ImageError> {
let image = ImageReader::open("path/to/image.png")?
    .decode()?;
# Ok(()) }

It is also possible to make a guess based on the content. This is especially handy if the source is some blob in memory and you have constructed the reader in another way. Here is an example with a pnm black-and-white subformat that encodes its pixel matrix with ascii values.

# use image::ImageError;
# use image::ImageReader;
# fn main() -> Result<(), ImageError> {
use std::io::Cursor;
use image::ImageFormat;

let raw_data = b"P1 2 2\n\
    0 1\n\
    1 0\n";

let mut reader = ImageReader::new(Cursor::new(raw_data))
    .with_guessed_format()
    .expect("Cursor io never fails");
assert_eq!(reader.format(), Some(ImageFormat::Pnm));

# #[cfg(feature = "pnm")]
let image = reader.decode()?;
# Ok(()) }

As a final fallback or if only a specific format must be used, the reader always allows manual specification of the supposed image format with set_format.

Implementations

`impl ImageReader<BufReader<File>>`

fn open<P>(path: P) -> Result<Self> where P: AsRef<Path>

Open a file to read, format will be guessed from path.

This will not attempt any io operation on the opened file.

If you want to inspect the content for a better guess on the format, which does not depend on file extensions, follow this call with a call to with_guessed_format.

`impl<'a, R: 'a + BufRead + Seek> ImageReader<R>`

fn new(buffered_reader: R) -> Self

Create a new image reader without a preset format.

Assumes the reader is already buffered. For optimal performance, consider wrapping the reader with a BufReader::new().

It is possible to guess the format based on the content of the read object with with_guessed_format, or to set the format directly with set_format.

fn with_format(buffered_reader: R, format: ImageFormat) -> Self

Construct a reader with specified format.

Assumes the reader is already buffered. For optimal performance, consider wrapping the reader with a BufReader::new().

fn format(self: &Self) -> Option<ImageFormat>

Get the currently determined format.

fn set_format(self: &mut Self, format: ImageFormat)

Supply the format as which to interpret the read image.

fn clear_format(self: &mut Self)

Remove the current information on the image format.

Note that many operations require format information to be present and will return e.g. an ImageError::Unsupported when the image format has not been set.

fn no_limits(self: &mut Self)

Disable all decoding limits.

fn limits(self: &mut Self, limits: Limits)

Set a custom set of decoding limits.

fn into_inner(self: Self) -> R

Unwrap the reader.

fn into_decoder(self: Self) -> ImageResult<impl ImageDecoder + 'a>

Convert the reader into a decoder.

fn with_guessed_format(self: Self) -> Result<Self>

Make a format guess based on the content, replacing it on success.

Returns Ok with the guess if no io error occurs. Additionally, replaces the current format if the guess was successful. If the guess was unable to determine a format then the current format of the reader is unchanged.

Returns an error if the underlying reader fails. The format is unchanged. The error is a std::io::Error and not ImageError since the only error case is an error when the underlying reader seeks.

When an error occurs, the reader may not have been properly reset and it is potentially hazardous to continue with more io.

Usage

This supplements the path based type deduction from [ImageReader::open()] with content based deduction. This is more common in Linux and UNIX operating systems and also helpful if the path can not be directly controlled.

# use image::ImageError;
# use image::ImageReader;
# fn main() -> Result<(), ImageError> {
let image = ImageReader::open("image.unknown")?
    .with_guessed_format()?
    .decode()?;
# Ok(()) }

fn into_dimensions(self: Self) -> ImageResult<(u32, u32)>

Read the image dimensions.

Uses the current format to construct the correct reader for the format.

If no format was determined, returns an ImageError::Unsupported.

fn decode(self: Self) -> ImageResult<DynamicImage>

Read the image (replaces load).

Uses the current format to construct the correct reader for the format.

If no format was determined, returns an ImageError::Unsupported.

`impl<R> Freeze for ImageReader<R>`

`impl<R> RefUnwindSafe for ImageReader<R>`

`impl<R> Send for ImageReader<R>`

`impl<R> Sync for ImageReader<R>`

`impl<R> Unpin for ImageReader<R>`

`impl<R> UnsafeUnpin for ImageReader<R>`

`impl<R> UnwindSafe for ImageReader<R>`

`impl<T> Any for ImageReader<R>`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for ImageReader<R>`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for ImageReader<R>`

fn borrow_mut(self: &mut Self) -> &mut T

`impl<T> From for ImageReader<R>`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T> Pointable for ImageReader<R>`

unsafe fn init(init: <T as Pointable>::Init) -> usize
unsafe fn deref<'a>(ptr: usize) -> &'a T
unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T
unsafe fn drop(ptr: usize)

`impl<T, U> Into for ImageReader<R>`

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

`impl<T, U> TryFrom for ImageReader<R>`

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

`impl<T, U> TryInto for ImageReader<R>`

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>