Struct image::ImageBuffer[][src]

pub struct ImageBuffer<P: Pixel, Container> { /* fields omitted */ }

Generic image buffer

This is an image parameterised by its Pixel types, represented by a width and height and a container of channel data. It provides direct access to its pixels and implements the GenericImageView and GenericImage traits. In many ways, this is the standard buffer implementing those traits. Using this concrete type instead of a generic type parameter has been shown to improve performance.

The crate defines a few type aliases with regularly used pixel types for your convenience, such as RgbImage, GrayImage etc.

To convert between images of different Pixel types use DynamicImage.

You can retrieve a complete description of the buffer’s layout and contents through as_flat_samples and as_flat_samples_mut. This can be handy to also use the contents in a foreign language, map it as a GPU host buffer or other similar tasks.

Examples

Create a simple canvas and paint a small cross.

use image::{RgbImage, Rgb};

let mut img = RgbImage::new(32, 32);

for x in 15..=17 {
    for y in 8..24 {
        img.put_pixel(x, y, Rgb([255, 0, 0]));
        img.put_pixel(y, x, Rgb([255, 0, 0]));
    }
}

Overlays an image on top of a larger background raster.

use image::{GenericImage, GenericImageView, ImageBuffer, open};

let on_top = open("path/to/some.png").unwrap().into_rgb();
let mut img = ImageBuffer::from_fn(512, 512, |x, y| {
    if (x + y) % 2 == 0 {
        image::Rgb([0, 0, 0])
    } else {
        image::Rgb([255, 255, 255])
    }
});

image::imageops::overlay(&mut img, &on_top, 128, 128);

Convert an RgbaImage to a GrayImage.

use image::{open, DynamicImage};

let rgba = open("path/to/some.png").unwrap().into_rgba();
let gray = DynamicImage::ImageRgba8(rgba).into_luma();

Implementations

impl<P, Container> ImageBuffer<P, Container> where
    P: Pixel + 'static,
    P::Subpixel: 'static,
    Container: Deref<Target = [P::Subpixel]>, 
[src]

pub fn from_raw(
    width: u32,
    height: u32,
    buf: Container
) -> Option<ImageBuffer<P, Container>>
[src]

Contructs a buffer from a generic container (for example a Vec or a slice)

Returns None if the container is not big enough (including when the image dimensions necessitate an allocation of more bytes than supported by the container).

pub fn into_raw(self) -> Container[src]

Returns the underlying raw buffer

pub fn as_raw(&self) -> &Container[src]

Returns the underlying raw buffer

pub fn dimensions(&self) -> (u32, u32)[src]

The width and height of this image.

pub fn width(&self) -> u32[src]

The width of this image.

pub fn height(&self) -> u32[src]

The height of this image.

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

Notable traits for Pixels<'a, P>

impl<'a, P: Pixel + 'a> Iterator for Pixels<'a, P> where
    P::Subpixel: 'a, 
type Item = &'a P;
[src]

Returns an iterator over the pixels of this image. The iteration order is x = 0 to width then y = 0 to height

pub fn rows(&self) -> Rows<'_, P>

Notable traits for Rows<'a, P>

impl<'a, P: Pixel + 'a> Iterator for Rows<'a, P> where
    P::Subpixel: 'a, 
type Item = Pixels<'a, P>;
[src]

Returns an iterator over the rows of this image.

Only non-empty rows can be iterated in this manner. In particular the iterator will not yield any item when the width of the image is 0 or a pixel type without any channels is used. This ensures that its length can always be represented by usize.

pub fn enumerate_pixels(&self) -> EnumeratePixels<'_, P>

Notable traits for EnumeratePixels<'a, P>

impl<'a, P: Pixel + 'a> Iterator for EnumeratePixels<'a, P> where
    P::Subpixel: 'a, 
type Item = (u32, u32, &'a P);
[src]

Enumerates over the pixels of the image. The iterator yields the coordinates of each pixel along with a reference to them. The iteration order is x = 0 to width then y = 0 to height

pub fn enumerate_rows(&self) -> EnumerateRows<'_, P>

Notable traits for EnumerateRows<'a, P>

impl<'a, P: Pixel + 'a> Iterator for EnumerateRows<'a, P> where
    P::Subpixel: 'a, 
type Item = (u32, EnumeratePixels<'a, P>);
[src]

Enumerates over the rows of the image. The iterator yields the y-coordinate of each row along with a reference to them.

pub fn get_pixel(&self, x: u32, y: u32) -> &P[src]

Gets a reference to the pixel at location (x, y)

Panics

Panics if (x, y) is out of the bounds (width, height).

pub fn sample_layout(&self) -> SampleLayout[src]

Get the format of the buffer when viewed as a matrix of samples.

pub fn into_flat_samples(self) -> FlatSamples<Container> where
    Container: AsRef<[P::Subpixel]>, 
[src]

Return the raw sample buffer with its stride an dimension information.

The returned buffer is guaranteed to be well formed in all cases. It is layed out by colors, width then height, meaning channel_stride <= width_stride <= height_stride. All strides are in numbers of elements but those are mostly u8 in which case the strides are also byte strides.

pub fn as_flat_samples(&self) -> FlatSamples<&[P::Subpixel]> where
    Container: AsRef<[P::Subpixel]>, 
[src]

Return a view on the raw sample buffer.

See into_flat_samples for more details.

pub fn as_flat_samples_mut(&mut self) -> FlatSamples<&mut [P::Subpixel]> where
    Container: AsMut<[P::Subpixel]>, 
[src]

Return a mutable view on the raw sample buffer.

See into_flat_samples for more details.

impl<P, Container> ImageBuffer<P, Container> where
    P: Pixel + 'static,
    P::Subpixel: 'static,
    Container: Deref<Target = [P::Subpixel]> + DerefMut
[src]

pub fn pixels_mut(&mut self) -> PixelsMut<'_, P>

Notable traits for PixelsMut<'a, P>

impl<'a, P: Pixel + 'a> Iterator for PixelsMut<'a, P> where
    P::Subpixel: 'a, 
type Item = &'a mut P;
[src]

Returns an iterator over the mutable pixels of this image.

pub fn rows_mut(&mut self) -> RowsMut<'_, P>

Notable traits for RowsMut<'a, P>

impl<'a, P: Pixel + 'a> Iterator for RowsMut<'a, P> where
    P::Subpixel: 'a, 
type Item = PixelsMut<'a, P>;
[src]

Returns an iterator over the mutable rows of this image.

Only non-empty rows can be iterated in this manner. In particular the iterator will not yield any item when the width of the image is 0 or a pixel type without any channels is used. This ensures that its length can always be represented by usize.

pub fn enumerate_pixels_mut(&mut self) -> EnumeratePixelsMut<'_, P>

Notable traits for EnumeratePixelsMut<'a, P>

impl<'a, P: Pixel + 'a> Iterator for EnumeratePixelsMut<'a, P> where
    P::Subpixel: 'a, 
type Item = (u32, u32, &'a mut P);
[src]

Enumerates over the pixels of the image. The iterator yields the coordinates of each pixel along with a mutable reference to them.

pub fn enumerate_rows_mut(&mut self) -> EnumerateRowsMut<'_, P>

Notable traits for EnumerateRowsMut<'a, P>

impl<'a, P: Pixel + 'a> Iterator for EnumerateRowsMut<'a, P> where
    P::Subpixel: 'a, 
type Item = (u32, EnumeratePixelsMut<'a, P>);
[src]

Enumerates over the rows of the image. The iterator yields the y-coordinate of each row along with a mutable reference to them.

pub fn get_pixel_mut(&mut self, x: u32, y: u32) -> &mut P[src]

Gets a reference to the mutable pixel at location (x, y)

Panics

Panics if (x, y) is out of the bounds (width, height).

pub fn put_pixel(&mut self, x: u32, y: u32, pixel: P)[src]

Puts a pixel at location (x, y)

Panics

Panics if (x, y) is out of the bounds (width, height).

impl<P, Container> ImageBuffer<P, Container> where
    P: Pixel + 'static,
    [P::Subpixel]: EncodableLayout,
    Container: Deref<Target = [P::Subpixel]>, 
[src]

pub fn save<Q>(&self, path: Q) -> ImageResult<()> where
    Q: AsRef<Path>, 
[src]

Saves the buffer to a file at the path specified.

The image format is derived from the file extension. Currently only jpeg and png files are supported.

impl<P, Container> ImageBuffer<P, Container> where
    P: Pixel + 'static,
    [P::Subpixel]: EncodableLayout,
    Container: Deref<Target = [P::Subpixel]>, 
[src]

pub fn save_with_format<Q>(
    &self,
    path: Q,
    format: ImageFormat
) -> ImageResult<()> where
    Q: AsRef<Path>, 
[src]

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

See save_buffer_with_format for supported types.

impl<P: Pixel + 'static> ImageBuffer<P, Vec<P::Subpixel>> where
    P::Subpixel: 'static, 
[src]

pub fn new(width: u32, height: u32) -> ImageBuffer<P, Vec<P::Subpixel>>[src]

Creates a new image buffer based on a Vec<P::Subpixel>.

Panics

Panics when the resulting image is larger the the maximum size of a vector.

pub fn from_pixel(
    width: u32,
    height: u32,
    pixel: P
) -> ImageBuffer<P, Vec<P::Subpixel>>
[src]

Constructs a new ImageBuffer by copying a pixel

Panics

Panics when the resulting image is larger the the maximum size of a vector.

pub fn from_fn<F>(
    width: u32,
    height: u32,
    f: F
) -> ImageBuffer<P, Vec<P::Subpixel>> where
    F: FnMut(u32, u32) -> P, 
[src]

Constructs a new ImageBuffer by repeated application of the supplied function.

The arguments to the function are the pixel’s x and y coordinates.

Panics

Panics when the resulting image is larger the the maximum size of a vector.

pub fn from_vec(
    width: u32,
    height: u32,
    buf: Vec<P::Subpixel>
) -> Option<ImageBuffer<P, Vec<P::Subpixel>>>
[src]

Creates an image buffer out of an existing buffer. Returns None if the buffer is not big enough.

pub fn into_vec(self) -> Vec<P::Subpixel>[src]

Consumes the image buffer and returns the underlying data as an owned buffer

impl ImageBuffer<Luma<u8>, Vec<u8, Global>>[src]

pub fn expand_palette(
    self,
    palette: &[(u8, u8, u8)],
    transparent_idx: Option<u8>
) -> RgbaImage
[src]

Expands a color palette by re-using the existing buffer. Assumes 8 bit per pixel. Uses an optionally transparent index to adjust it’s alpha value accordingly.

Trait Implementations

impl<P, Container> Clone for ImageBuffer<P, Container> where
    P: Pixel,
    Container: Deref<Target = [P::Subpixel]> + Clone
[src]

impl<'a, 'b, Container, FromType: Pixel + 'static, ToType: Pixel + 'static> ConvertBuffer<ImageBuffer<ToType, Vec<<ToType as Pixel>::Subpixel, Global>>> for ImageBuffer<FromType, Container> where
    Container: Deref<Target = [FromType::Subpixel]>,
    ToType: FromColor<FromType>,
    FromType::Subpixel: 'static,
    ToType::Subpixel: 'static, 
[src]

fn convert(&self) -> ImageBuffer<ToType, Vec<ToType::Subpixel>>[src]

Examples

Convert RGB image to gray image.

use image::buffer::ConvertBuffer;
use image::GrayImage;
 
let image_path = "examples/fractal.png";
let image = image::open(&image_path)
    .expect("Open file failed")
    .to_rgba();
 
let gray_image: GrayImage = image.convert();

impl<P: Debug + Pixel, Container: Debug> Debug for ImageBuffer<P, Container>[src]

impl<P, Container> Deref for ImageBuffer<P, Container> where
    P: Pixel + 'static,
    P::Subpixel: 'static,
    Container: Deref<Target = [P::Subpixel]>, 
[src]

type Target = [P::Subpixel]

The resulting type after dereferencing.

impl<P, Container> DerefMut for ImageBuffer<P, Container> where
    P: Pixel + 'static,
    P::Subpixel: 'static,
    Container: Deref<Target = [P::Subpixel]> + DerefMut
[src]

impl<P, Container> GenericImage for ImageBuffer<P, Container> where
    P: Pixel + 'static,
    Container: Deref<Target = [P::Subpixel]> + DerefMut,
    P::Subpixel: 'static, 
[src]

type InnerImage = Self

Underlying image type. This is mainly used by SubImages in order to always have a reference to the original image. This allows for less indirections and it eases the use of nested SubImages. Read more

unsafe fn unsafe_put_pixel(&mut self, x: u32, y: u32, pixel: P)[src]

Puts a pixel at location (x, y), ignoring bounds checking.

fn blend_pixel(&mut self, x: u32, y: u32, p: P)[src]

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

DEPRECATED: This method will be removed. Blend the pixel directly instead.

impl<P, Container> GenericImageView for ImageBuffer<P, Container> where
    P: Pixel + 'static,
    Container: Deref<Target = [P::Subpixel]> + Deref,
    P::Subpixel: 'static, 
[src]

type Pixel = P

The type of pixel.

type InnerImageView = Self

Underlying image type. This is mainly used by SubImages in order to always have a reference to the original image. This allows for less indirections and it eases the use of nested SubImages. Read more

unsafe fn unsafe_get_pixel(&self, x: u32, y: u32) -> P[src]

Returns the pixel located at (x, y), ignoring bounds checking.

impl<P: Hash + Pixel, Container: Hash> Hash for ImageBuffer<P, Container>[src]

impl<P, Container> Index<(u32, u32)> for ImageBuffer<P, Container> where
    P: Pixel + 'static,
    P::Subpixel: 'static,
    Container: Deref<Target = [P::Subpixel]>, 
[src]

type Output = P

The returned type after indexing.

impl<P, Container> IndexMut<(u32, u32)> for ImageBuffer<P, Container> where
    P: Pixel + 'static,
    P::Subpixel: 'static,
    Container: Deref<Target = [P::Subpixel]> + DerefMut
[src]

impl<P: PartialEq + Pixel, Container: PartialEq> PartialEq<ImageBuffer<P, Container>> for ImageBuffer<P, Container>[src]

impl<P: Eq + Pixel, Container: Eq> Eq for ImageBuffer<P, Container>[src]

impl<P: Pixel, Container> StructuralEq for ImageBuffer<P, Container>[src]

impl<P: Pixel, Container> StructuralPartialEq for ImageBuffer<P, Container>[src]

Auto Trait Implementations

impl<P, Container> RefUnwindSafe for ImageBuffer<P, Container> where
    Container: RefUnwindSafe,
    P: RefUnwindSafe

impl<P, Container> Send for ImageBuffer<P, Container> where
    Container: Send,
    P: Send

impl<P, Container> Sync for ImageBuffer<P, Container> where
    Container: Sync,
    P: Sync

impl<P, Container> Unpin for ImageBuffer<P, Container> where
    Container: Unpin,
    P: Unpin

impl<P, Container> UnwindSafe for ImageBuffer<P, Container> where
    Container: UnwindSafe,
    P: UnwindSafe

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

The resulting type after obtaining ownership.

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.