Enum DynamicImage

#[non_exhaustive]
pub enum DynamicImage {
    ImageLuma8(GrayImage),
    ImageLumaA8(GrayAlphaImage),
    ImageRgb8(RgbImage),
    ImageRgba8(RgbaImage),
    ImageLuma16(ImageBuffer<Luma<u16>, Vec<u16>>),
    ImageLumaA16(ImageBuffer<LumaA<u16>, Vec<u16>>),
    ImageRgb16(ImageBuffer<Rgb<u16>, Vec<u16>>),
    ImageRgba16(ImageBuffer<Rgba<u16>, Vec<u16>>),
    ImageRgb32F(Rgb32FImage),
    ImageRgba32F(Rgba32FImage),
}

A Dynamic Image

This represents a matrix of pixels which are convertible from and to an RGBA representation. More variants that adhere to these principles may get added in the future, in particular to cover other combinations typically used.

Usage

This type can act as a converter between specific ImageBuffer instances.

use image::{DynamicImage, GrayImage, RgbImage};

let rgb: RgbImage = RgbImage::new(10, 10);
let luma: GrayImage = DynamicImage::ImageRgb8(rgb).into_luma8();

Design

There is no goal to provide an all-encompassing type with all possible memory layouts. This would hardly be feasible as a simple enum, due to the sheer number of combinations of channel kinds, channel order, and bit depth. Rather, this type provides an opinionated selection with normalized channel order which can store common pixel values without loss.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

ImageLuma8(GrayImage)

Each pixel in this image is 8-bit Luma

ImageLumaA8(GrayAlphaImage)

Each pixel in this image is 8-bit Luma with alpha

ImageRgb8(RgbImage)

Each pixel in this image is 8-bit Rgb

ImageRgba8(RgbaImage)

Each pixel in this image is 8-bit Rgb with alpha

ImageLuma16(ImageBuffer<Luma<u16>, Vec<u16>>)

Each pixel in this image is 16-bit Luma

ImageLumaA16(ImageBuffer<LumaA<u16>, Vec<u16>>)

Each pixel in this image is 16-bit Luma with alpha

ImageRgb16(ImageBuffer<Rgb<u16>, Vec<u16>>)

Each pixel in this image is 16-bit Rgb

ImageRgba16(ImageBuffer<Rgba<u16>, Vec<u16>>)

Each pixel in this image is 16-bit Rgb with alpha

ImageRgb32F(Rgb32FImage)

Each pixel in this image is 32-bit float Rgb

ImageRgba32F(Rgba32FImage)

Each pixel in this image is 32-bit float Rgb with alpha

Implementations

impl DynamicImage

pub fn new(w: u32, h: u32, color: ColorType) -> DynamicImage

Creates a dynamic image backed by a buffer depending on the color type given.

pub fn new_luma8(w: u32, h: u32) -> DynamicImage

Creates a dynamic image backed by a buffer of gray pixels.

pub fn new_luma_a8(w: u32, h: u32) -> DynamicImage

Creates a dynamic image backed by a buffer of gray pixels with transparency.

pub fn new_rgb8(w: u32, h: u32) -> DynamicImage

Creates a dynamic image backed by a buffer of RGB pixels.

pub fn new_rgba8(w: u32, h: u32) -> DynamicImage

Creates a dynamic image backed by a buffer of RGBA pixels.

pub fn new_luma16(w: u32, h: u32) -> DynamicImage

Creates a dynamic image backed by a buffer of gray pixels.

pub fn new_luma_a16(w: u32, h: u32) -> DynamicImage

Creates a dynamic image backed by a buffer of gray pixels with transparency.

pub fn new_rgb16(w: u32, h: u32) -> DynamicImage

Creates a dynamic image backed by a buffer of RGB pixels.

pub fn new_rgba16(w: u32, h: u32) -> DynamicImage

Creates a dynamic image backed by a buffer of RGBA pixels.

pub fn new_rgb32f(w: u32, h: u32) -> DynamicImage

Creates a dynamic image backed by a buffer of RGB pixels.

pub fn new_rgba32f(w: u32, h: u32) -> DynamicImage

Creates a dynamic image backed by a buffer of RGBA pixels.

pub fn from_decoder(decoder: impl ImageDecoder) -> ImageResult<Self>

Decodes an encoded image into a dynamic image.

pub fn to_rgb8(&self) -> RgbImage

Returns a copy of this image as an RGB image.

pub fn to_rgb16(&self) -> ImageBuffer<Rgb<u16>, Vec<u16>>

Returns a copy of this image as an RGB image.

pub fn to_rgb32f(&self) -> Rgb32FImage

Returns a copy of this image as an RGB image.

pub fn to_rgba8(&self) -> RgbaImage

Returns a copy of this image as an RGBA image.

pub fn to_rgba16(&self) -> ImageBuffer<Rgba<u16>, Vec<u16>>

Returns a copy of this image as an RGBA image.

pub fn to_rgba32f(&self) -> Rgba32FImage

Returns a copy of this image as an RGBA image.

pub fn to_luma8(&self) -> GrayImage

Returns a copy of this image as a Luma image.

pub fn to_luma16(&self) -> ImageBuffer<Luma<u16>, Vec<u16>>

Returns a copy of this image as a Luma image.

pub fn to_luma32f(&self) -> ImageBuffer<Luma<f32>, Vec<f32>>

Returns a copy of this image as a Luma image.

pub fn to_luma_alpha8(&self) -> GrayAlphaImage

Returns a copy of this image as a LumaA image.

pub fn to_luma_alpha16(&self) -> ImageBuffer<LumaA<u16>, Vec<u16>>

Returns a copy of this image as a LumaA image.

pub fn to_luma_alpha32f(&self) -> ImageBuffer<LumaA<f32>, Vec<f32>>

Returns a copy of this image as a LumaA image.

pub fn into_rgb8(self) -> RgbImage

Consume the image and returns a RGB image.

If the image was already the correct format, it is returned as is. Otherwise, a copy is created.

pub fn into_rgb16(self) -> ImageBuffer<Rgb<u16>, Vec<u16>>

Consume the image and returns a RGB image.

If the image was already the correct format, it is returned as is. Otherwise, a copy is created.

pub fn into_rgb32f(self) -> Rgb32FImage

Consume the image and returns a RGB image.

If the image was already the correct format, it is returned as is. Otherwise, a copy is created.

pub fn into_rgba8(self) -> RgbaImage

Consume the image and returns a RGBA image.

If the image was already the correct format, it is returned as is. Otherwise, a copy is created.

pub fn into_rgba16(self) -> ImageBuffer<Rgba<u16>, Vec<u16>>

Consume the image and returns a RGBA image.

If the image was already the correct format, it is returned as is. Otherwise, a copy is created.

pub fn into_rgba32f(self) -> Rgba32FImage

Consume the image and returns a RGBA image.

If the image was already the correct format, it is returned as is. Otherwise, a copy is created.

pub fn into_luma8(self) -> GrayImage

Consume the image and returns a Luma image.

If the image was already the correct format, it is returned as is. Otherwise, a copy is created.

pub fn into_luma16(self) -> ImageBuffer<Luma<u16>, Vec<u16>>

Consume the image and returns a Luma image.

If the image was already the correct format, it is returned as is. Otherwise, a copy is created.

pub fn into_luma_alpha8(self) -> GrayAlphaImage

Consume the image and returns a LumaA image.

If the image was already the correct format, it is returned as is. Otherwise, a copy is created.

pub fn into_luma_alpha16(self) -> ImageBuffer<LumaA<u16>, Vec<u16>>

Consume the image and returns a LumaA image.

If the image was already the correct format, it is returned as is. Otherwise, a copy is created.

pub fn crop(&mut self, x: u32, y: u32, width: u32, height: u32) -> DynamicImage

Return a cut-out of this image delimited by the bounding rectangle.

Note: this method does not modify the object, and its signature will be replaced with crop_imm()’s in the 0.24 release

pub fn crop_imm(&self, x: u32, y: u32, width: u32, height: u32) -> DynamicImage

Return a cut-out of this image delimited by the bounding rectangle.

pub fn as_rgb8(&self) -> Option<&RgbImage>

Return a reference to an 8bit RGB image

pub fn as_mut_rgb8(&mut self) -> Option<&mut RgbImage>

Return a mutable reference to an 8bit RGB image

pub fn as_rgba8(&self) -> Option<&RgbaImage>

Return a reference to an 8bit RGBA image

pub fn as_mut_rgba8(&mut self) -> Option<&mut RgbaImage>

Return a mutable reference to an 8bit RGBA image

pub fn as_luma8(&self) -> Option<&GrayImage>

Return a reference to an 8bit Grayscale image

pub fn as_mut_luma8(&mut self) -> Option<&mut GrayImage>

Return a mutable reference to an 8bit Grayscale image

pub fn as_luma_alpha8(&self) -> Option<&GrayAlphaImage>

Return a reference to an 8bit Grayscale image with an alpha channel

pub fn as_mut_luma_alpha8(&mut self) -> Option<&mut GrayAlphaImage>

Return a mutable reference to an 8bit Grayscale image with an alpha channel

pub fn as_rgb16(&self) -> Option<&ImageBuffer<Rgb<u16>, Vec<u16>>>

Return a reference to an 16bit RGB image

pub fn as_mut_rgb16(&mut self) -> Option<&mut ImageBuffer<Rgb<u16>, Vec<u16>>>

Return a mutable reference to an 16bit RGB image

pub fn as_rgba16(&self) -> Option<&ImageBuffer<Rgba<u16>, Vec<u16>>>

Return a reference to an 16bit RGBA image

pub fn as_mut_rgba16(&mut self) -> Option<&mut ImageBuffer<Rgba<u16>, Vec<u16>>>

Return a mutable reference to an 16bit RGBA image

pub fn as_rgb32f(&self) -> Option<&Rgb32FImage>

Return a reference to an 32bit RGB image

pub fn as_mut_rgb32f(&mut self) -> Option<&mut Rgb32FImage>

Return a mutable reference to an 32bit RGB image

pub fn as_rgba32f(&self) -> Option<&Rgba32FImage>

Return a reference to an 32bit RGBA image

pub fn as_mut_rgba32f(&mut self) -> Option<&mut Rgba32FImage>

Return a mutable reference to an 16bit RGBA image

pub fn as_luma16(&self) -> Option<&ImageBuffer<Luma<u16>, Vec<u16>>>

Return a reference to an 16bit Grayscale image

pub fn as_mut_luma16(&mut self) -> Option<&mut ImageBuffer<Luma<u16>, Vec<u16>>>

Return a mutable reference to an 16bit Grayscale image

pub fn as_luma_alpha16(&self) -> Option<&ImageBuffer<LumaA<u16>, Vec<u16>>>

Return a reference to an 16bit Grayscale image with an alpha channel

pub fn as_mut_luma_alpha16( &mut self, ) -> Option<&mut ImageBuffer<LumaA<u16>, Vec<u16>>>

Return a mutable reference to an 16bit Grayscale image with an alpha channel

pub fn as_flat_samples_u8(&self) -> Option<FlatSamples<&[u8]>>

Return a view on the raw sample buffer for 8 bit per channel images.

pub fn as_flat_samples_u16(&self) -> Option<FlatSamples<&[u16]>>

Return a view on the raw sample buffer for 16 bit per channel images.

pub fn as_flat_samples_f32(&self) -> Option<FlatSamples<&[f32]>>

Return a view on the raw sample buffer for 32bit per channel images.

pub fn as_bytes(&self) -> &[u8]

Return this image’s pixels as a native endian byte slice.

pub fn into_bytes(self) -> Vec<u8>

Return this image’s pixels as a byte vector. If the ImageBuffer container is Vec<u8>, this operation is free. Otherwise, a copy is returned.

pub fn color(&self) -> ColorType

Return this image’s color type.

pub fn width(&self) -> u32

Returns the width of the underlying image

pub fn height(&self) -> u32

Returns the height of the underlying image

pub fn grayscale(&self) -> DynamicImage

Return a grayscale version of this image. Returns Luma images in most cases. However, for f32 images, this will return a grayscale Rgb/Rgba image instead.

pub fn invert(&mut self)

Invert the colors of this image. This method operates inplace.

pub fn resize( &self, nwidth: u32, nheight: u32, filter: FilterType, ) -> DynamicImage

Resize this image using the specified filter algorithm. Returns a new image. The image’s aspect ratio is preserved. The image is scaled to the maximum possible size that fits within the bounds specified by nwidth and nheight.

pub fn resize_exact( &self, nwidth: u32, nheight: u32, filter: FilterType, ) -> DynamicImage

Resize this image using the specified filter algorithm. Returns a new image. Does not preserve aspect ratio. nwidth and nheight are the new image’s dimensions

pub fn thumbnail(&self, nwidth: u32, nheight: u32) -> DynamicImage

Scale this image down to fit within a specific size. Returns a new image. The image’s aspect ratio is preserved. The image is scaled to the maximum possible size that fits within the bounds specified by nwidth and nheight.

This method uses a fast integer algorithm where each source pixel contributes to exactly one target pixel. May give aliasing artifacts if new size is close to old size.

pub fn thumbnail_exact(&self, nwidth: u32, nheight: u32) -> DynamicImage

Scale this image down to a specific size. Returns a new image. Does not preserve aspect ratio. nwidth and nheight are the new image’s dimensions. This method uses a fast integer algorithm where each source pixel contributes to exactly one target pixel. May give aliasing artifacts if new size is close to old size.

pub fn resize_to_fill( &self, nwidth: u32, nheight: u32, filter: FilterType, ) -> DynamicImage

Resize this image using the specified filter algorithm. Returns a new image. The image’s aspect ratio is preserved. The image is scaled to the maximum possible size that fits within the larger (relative to aspect ratio) of the bounds specified by nwidth and nheight, then cropped to fit within the other bound.

pub fn blur(&self, sigma: f32) -> DynamicImage

Performs a Gaussian blur on this image. sigma is a measure of how much to blur by. Use DynamicImage::fast_blur() for a faster but less accurate version.

pub fn fast_blur(&self, sigma: f32) -> DynamicImage

Performs a fast blur on this image. sigma is the standard deviation of the (approximated) Gaussian

pub fn unsharpen(&self, sigma: f32, threshold: i32) -> DynamicImage

Performs an unsharpen mask on this image. sigma is the amount to blur the image by. threshold is a control of how much to sharpen.

See https://en.wikipedia.org/wiki/Unsharp_masking#Digital_unsharp_masking

pub fn filter3x3(&self, kernel: &[f32]) -> DynamicImage

Filters this image with the specified 3x3 kernel.

pub fn adjust_contrast(&self, c: f32) -> DynamicImage

Adjust the contrast of this image. contrast is the amount to adjust the contrast by. Negative values decrease the contrast and positive values increase the contrast.

pub fn brighten(&self, value: i32) -> DynamicImage

Brighten the pixels of this image. value is the amount to brighten each pixel by. Negative values decrease the brightness and positive values increase it.

pub fn huerotate(&self, value: i32) -> DynamicImage

Hue rotate the supplied image. value is the degrees to rotate each pixel by. 0 and 360 do nothing, the rest rotates by the given degree value. just like the css webkit filter hue-rotate(180)

pub fn flipv(&self) -> DynamicImage

Flip this image vertically

Use apply_orientation if you want to flip the image in-place instead.

pub fn fliph(&self) -> DynamicImage

Flip this image horizontally

Use apply_orientation if you want to flip the image in-place.

pub fn rotate90(&self) -> DynamicImage

Rotate this image 90 degrees clockwise.

pub fn rotate180(&self) -> DynamicImage

Rotate this image 180 degrees.

Use apply_orientation if you want to rotate the image in-place.

pub fn rotate270(&self) -> DynamicImage

Rotate this image 270 degrees clockwise.

pub fn apply_orientation(&mut self, orientation: Orientation)

Rotates and/or flips the image as indicated by Orientation.

This can be used to apply Exif orientation to an image, e.g. to correctly display a photo taken by a smartphone camera:

use image::{DynamicImage, ImageReader, ImageDecoder};

let mut decoder = ImageReader::open("file.jpg")?.into_decoder()?;
let orientation = decoder.orientation()?;
let mut image = DynamicImage::from_decoder(decoder)?;
image.apply_orientation(orientation);

Note that for some orientations cannot be efficiently applied in-place. In that case this function will make a copy of the image internally.

If this matters to you, please see the documentation on the variants of Orientation to learn which orientations can and cannot be applied without copying.

pub fn write_to<W: Write + Seek>( &self, w: &mut W, format: ImageFormat, ) -> ImageResult<()>

Encode this image and write it to w.

Assumes the writer is buffered. In most cases, you should wrap your writer in a BufWriter for best performance.

pub fn write_with_encoder(&self, encoder: impl ImageEncoder) -> ImageResult<()>

Encode this image with the provided encoder.

pub fn save<Q>(&self, path: Q) -> ImageResult<()>

where Q: AsRef<Path>,

Saves the buffer to a file at the path specified.

The image format is derived from the file extension.

pub fn save_with_format<Q>( &self, path: Q, format: ImageFormat, ) -> ImageResult<()>

where Q: AsRef<Path>,

Saves the buffer to a file at the specified path in the specified format.

See save_buffer_with_format for supported types.

Trait Implementations

impl Clone for DynamicImage

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DynamicImage

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for DynamicImage

fn default() -> Self

Returns the “default value” for a type.

impl From<DynamicImage> for ImageBuffer<Luma<u16>, Vec<u16>>

fn from(value: DynamicImage) -> Self

Converts to this type from the input type.

impl From<DynamicImage> for GrayImage

fn from(value: DynamicImage) -> Self

Converts to this type from the input type.

impl From<DynamicImage> for ImageBuffer<LumaA<u16>, Vec<u16>>

fn from(value: DynamicImage) -> Self

Converts to this type from the input type.

impl From<DynamicImage> for GrayAlphaImage

fn from(value: DynamicImage) -> Self

Converts to this type from the input type.

impl From<DynamicImage> for ImageBuffer<Rgb<u16>, Vec<u16>>

fn from(value: DynamicImage) -> Self

Converts to this type from the input type.

impl From<DynamicImage> for RgbImage

fn from(value: DynamicImage) -> Self

Converts to this type from the input type.

impl From<DynamicImage> for Rgba32FImage

fn from(value: DynamicImage) -> Self

Converts to this type from the input type.

impl From<DynamicImage> for ImageBuffer<Rgba<u16>, Vec<u16>>

fn from(value: DynamicImage) -> Self

Converts to this type from the input type.

impl From<DynamicImage> for RgbaImage

fn from(value: DynamicImage) -> Self

Converts to this type from the input type.

impl From<ImageBuffer<Luma<f32>, Vec<f32>>> for DynamicImage

fn from(image: ImageBuffer<Luma<f32>, Vec<f32>>) -> Self

Converts to this type from the input type.

impl From<ImageBuffer<Luma<u16>, Vec<u16>>> for DynamicImage

fn from(image: ImageBuffer<Luma<u16>, Vec<u16>>) -> Self

Converts to this type from the input type.

impl From<ImageBuffer<Luma<u8>, Vec<u8>>> for DynamicImage

fn from(image: GrayImage) -> Self

Converts to this type from the input type.

impl From<ImageBuffer<LumaA<f32>, Vec<f32>>> for DynamicImage

fn from(image: ImageBuffer<LumaA<f32>, Vec<f32>>) -> Self

Converts to this type from the input type.

impl From<ImageBuffer<LumaA<u16>, Vec<u16>>> for DynamicImage

fn from(image: ImageBuffer<LumaA<u16>, Vec<u16>>) -> Self

Converts to this type from the input type.

impl From<ImageBuffer<LumaA<u8>, Vec<u8>>> for DynamicImage

fn from(image: GrayAlphaImage) -> Self

Converts to this type from the input type.

impl From<ImageBuffer<Rgb<f32>, Vec<f32>>> for DynamicImage

fn from(image: Rgb32FImage) -> Self

Converts to this type from the input type.

impl From<ImageBuffer<Rgb<u16>, Vec<u16>>> for DynamicImage

fn from(image: ImageBuffer<Rgb<u16>, Vec<u16>>) -> Self

Converts to this type from the input type.

impl From<ImageBuffer<Rgb<u8>, Vec<u8>>> for DynamicImage

fn from(image: RgbImage) -> Self

Converts to this type from the input type.

impl From<ImageBuffer<Rgba<f32>, Vec<f32>>> for DynamicImage

fn from(image: Rgba32FImage) -> Self

Converts to this type from the input type.

impl From<ImageBuffer<Rgba<u16>, Vec<u16>>> for DynamicImage

fn from(image: ImageBuffer<Rgba<u16>, Vec<u16>>) -> Self

Converts to this type from the input type.

impl From<ImageBuffer<Rgba<u8>, Vec<u8>>> for DynamicImage

fn from(image: RgbaImage) -> Self

Converts to this type from the input type.

impl GenericImage for DynamicImage

fn get_pixel_mut(&mut self, _: u32, _: u32) -> &mut Rgba<u8>

👎Deprecated since 0.24.0: Use get_pixel and put_pixel instead.

Do not use is function: It is unimplemented!

fn put_pixel(&mut self, x: u32, y: u32, pixel: Rgba<u8>)

Put a pixel at location (x, y). Indexed from top left.

fn blend_pixel(&mut self, x: u32, y: u32, pixel: Rgba<u8>)

👎Deprecated since 0.24.0: Use iterator pixels_mut to blend the pixels directly

Put a pixel at location (x, y), taking into account alpha channels

unsafe fn unsafe_put_pixel(&mut self, x: u32, y: u32, pixel: Self::Pixel)

Puts a pixel at location (x, y). Indexed from top left.

fn copy_from<O>(&mut self, other: &O, x: u32, y: u32) -> ImageResult<()>

where O: GenericImageView<Pixel = Self::Pixel>,

Copies all of the pixels from another image into this image.

fn copy_within(&mut self, source: Rect, x: u32, y: u32) -> bool

Copies all of the pixels from one part of this image to another part of this image.

fn sub_image( &mut self, x: u32, y: u32, width: u32, height: u32, ) -> SubImage<&mut Self>

where Self: Sized,

Returns a mutable subimage that is a view into this image. If you want an immutable subimage instead, use GenericImageView::view The coordinates set the position of the top left corner of the SubImage.

impl GenericImageView for DynamicImage

type Pixel = Rgba<u8>

The type of pixel.

fn dimensions(&self) -> (u32, u32)

The width and height of this image.

fn get_pixel(&self, x: u32, y: u32) -> Rgba<u8>

Returns the pixel located at (x, y). Indexed from top left.

fn width(&self) -> u32

The width of this image.

fn height(&self) -> u32

The height of this image.

fn in_bounds(&self, x: u32, y: u32) -> bool

Returns true if this x, y coordinate is contained inside the image.

unsafe fn unsafe_get_pixel(&self, x: u32, y: u32) -> Self::Pixel

Returns the pixel located at (x, y). Indexed from top left.

fn pixels(&self) -> Pixels<'_, Self>

where Self: Sized,

Returns an Iterator over the pixels of this image. The iterator yields the coordinates of each pixel along with their value

fn view(&self, x: u32, y: u32, width: u32, height: u32) -> SubImage<&Self>

where Self: Sized,

Returns a subimage that is an immutable view into this image. You can use GenericImage::sub_image if you need a mutable view instead. The coordinates set the position of the top left corner of the view.

impl PartialEq for DynamicImage

fn eq(&self, other: &DynamicImage) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for DynamicImage