Enum DynamicImage

enum DynamicImage

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

ImageLuma8(crate::buffer_::GrayImage)

Each pixel in this image is 8-bit Luma

ImageLumaA8(crate::buffer_::GrayAlphaImage)

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

ImageRgb8(crate::buffer_::RgbImage)

Each pixel in this image is 8-bit Rgb

ImageRgba8(crate::buffer_::RgbaImage)

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

ImageLuma16(ImageBuffer<crate::color::Luma<u16>, Vec<u16>>)

Each pixel in this image is 16-bit Luma

ImageLumaA16(ImageBuffer<crate::color::LumaA<u16>, Vec<u16>>)

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

ImageRgb16(ImageBuffer<crate::color::Rgb<u16>, Vec<u16>>)

Each pixel in this image is 16-bit Rgb

ImageRgba16(ImageBuffer<crate::color::Rgba<u16>, Vec<u16>>)

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

ImageRgb32F(crate::Rgb32FImage)

Each pixel in this image is 32-bit float Rgb

ImageRgba32F(crate::Rgba32FImage)

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

Implementations

impl DynamicImage

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Decodes an encoded image into a dynamic image.

fn to_rgb8(self: &Self) -> RgbImage

Returns a copy of this image as an RGB image.

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

Returns a copy of this image as an RGB image.

fn to_rgb32f(self: &Self) -> Rgb32FImage

Returns a copy of this image as an RGB image.

fn to_rgba8(self: &Self) -> RgbaImage

Returns a copy of this image as an RGBA image.

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

Returns a copy of this image as an RGBA image.

fn to_rgba32f(self: &Self) -> Rgba32FImage

Returns a copy of this image as an RGBA image.

fn to_luma8(self: &Self) -> GrayImage

Returns a copy of this image as a Luma image.

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

Returns a copy of this image as a Luma image.

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

Returns a copy of this image as a Luma image.

fn to_luma_alpha8(self: &Self) -> GrayAlphaImage

Returns a copy of this image as a LumaA image.

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

Returns a copy of this image as a LumaA image.

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

Returns a copy of this image as a LumaA image.

fn into_rgb8(self: 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.

fn into_rgb16(self: 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.

fn into_rgb32f(self: 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.

fn into_rgba8(self: 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.

fn into_rgba16(self: 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.

fn into_rgba32f(self: 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.

fn into_luma8(self: 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.

fn into_luma16(self: 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.

fn into_luma_alpha8(self: 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.

fn into_luma_alpha16(self: 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.

fn crop(self: &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

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

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

fn as_rgb8(self: &Self) -> Option<&RgbImage>

Return a reference to an 8bit RGB image

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

Return a mutable reference to an 8bit RGB image

fn as_rgba8(self: &Self) -> Option<&RgbaImage>

Return a reference to an 8bit RGBA image

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

Return a mutable reference to an 8bit RGBA image

fn as_luma8(self: &Self) -> Option<&GrayImage>

Return a reference to an 8bit Grayscale image

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

Return a mutable reference to an 8bit Grayscale image

fn as_luma_alpha8(self: &Self) -> Option<&GrayAlphaImage>

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

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

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

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

Return a reference to an 16bit RGB image

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

Return a mutable reference to an 16bit RGB image

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

Return a reference to an 16bit RGBA image

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

Return a mutable reference to an 16bit RGBA image

fn as_rgb32f(self: &Self) -> Option<&Rgb32FImage>

Return a reference to an 32bit RGB image

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

Return a mutable reference to an 32bit RGB image

fn as_rgba32f(self: &Self) -> Option<&Rgba32FImage>

Return a reference to an 32bit RGBA image

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

Return a mutable reference to an 16bit RGBA image

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

Return a reference to an 16bit Grayscale image

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

Return a mutable reference to an 16bit Grayscale image

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

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

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

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

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

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

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

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

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

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

fn as_bytes(self: &Self) -> &[u8]

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

fn into_bytes(self: 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.

fn color(self: &Self) -> ColorType

Return this image's color type.

fn width(self: &Self) -> u32

Returns the width of the underlying image

fn height(self: &Self) -> u32

Returns the height of the underlying image

fn grayscale(self: &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.

fn invert(self: &mut Self)

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

fn resize(self: &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.

fn resize_exact(self: &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

fn thumbnail(self: &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.

fn thumbnail_exact(self: &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.

fn resize_to_fill(self: &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.

fn blur(self: &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.

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

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

fn unsharpen(self: &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

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

Filters this image with the specified 3x3 kernel.

fn adjust_contrast(self: &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.

fn brighten(self: &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.

fn huerotate(self: &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)

fn flipv(self: &Self) -> DynamicImage

Flip this image vertically

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

fn fliph(self: &Self) -> DynamicImage

Flip this image horizontally

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

fn rotate90(self: &Self) -> DynamicImage

Rotate this image 90 degrees clockwise.

fn rotate180(self: &Self) -> DynamicImage

Rotate this image 180 degrees.

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

fn rotate270(self: &Self) -> DynamicImage

Rotate this image 270 degrees clockwise.

fn apply_orientation(self: &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:

# fn only_check_if_this_compiles() -> Result<(), Box<dyn std::error::Error>> {
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);
# Ok(())
# }

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.

fn write_to<W: Write + Seek>(self: &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.

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

Encode this image with the provided encoder.

fn save<Q>(self: &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.

fn save_with_format<Q>(self: &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.

impl Clone for DynamicImage

fn clone(self: &Self) -> Self
fn clone_from(self: &mut Self, source: &Self)

impl Debug for DynamicImage

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

impl Default for DynamicImage

fn default() -> Self

impl Freeze for DynamicImage

impl From for DynamicImage

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

impl From for DynamicImage

fn from(image: Rgba32FImage) -> Self

impl From for DynamicImage

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

impl From for DynamicImage

fn from(image: Rgb32FImage) -> Self

impl From for DynamicImage

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

impl From for DynamicImage

fn from(image: RgbImage) -> Self

impl From for DynamicImage

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

impl From for DynamicImage

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

impl From for DynamicImage

fn from(image: GrayAlphaImage) -> Self

impl From for DynamicImage

fn from(image: RgbaImage) -> Self

impl From for DynamicImage

fn from(image: GrayImage) -> Self

impl From for DynamicImage

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

impl GenericImage for DynamicImage

fn put_pixel(self: &mut Self, x: u32, y: u32, pixel: Rgba<u8>)
fn blend_pixel(self: &mut Self, x: u32, y: u32, pixel: Rgba<u8>)
fn get_pixel_mut(self: &mut Self, _: u32, _: u32) -> &mut Rgba<u8>

Do not use is function: It is unimplemented!

impl GenericImageView for DynamicImage

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

impl PartialEq for DynamicImage

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

impl RefUnwindSafe for DynamicImage

impl Send for DynamicImage

impl StructuralPartialEq for DynamicImage

impl Sync for DynamicImage

impl Unpin for DynamicImage

impl UnsafeUnpin for DynamicImage

impl UnwindSafe for DynamicImage

impl<R, P> ReadPrimitive for DynamicImage

impl<T> Any for DynamicImage

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for DynamicImage

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

impl<T> BorrowMut for DynamicImage

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

impl<T> CloneToUninit for DynamicImage

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> From for DynamicImage

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> Pointable for DynamicImage

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> ToOwned for DynamicImage

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

impl<T, U> Into for DynamicImage

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 DynamicImage

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

impl<T, U> TryInto for DynamicImage

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