Trait GenericImageView

pub trait GenericImageView

Trait to inspect an image.

use image::{GenericImageView, Rgb, RgbImage};

let buffer = RgbImage::new(10, 10);
let image: &dyn GenericImageView<Pixel = Rgb<u8>> = &buffer;

Associated Types

type Pixel: Pixel;

The type of pixel.

Required Methods

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

The width and height of this image.

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

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

Panics

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

Provided Methods

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.

This function can be implemented in a way that ignores bounds checking.

Safety

The coordinates must be in_bounds of the image.

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.

Panics

Panics if the dimensions provided fall out of bounds.

fn try_view(&self, x: u32, y: u32, width: u32, height: u32) -> Result<SubImage<&Self>, ImageError>
where
    Self: Sized,

Returns a subimage that is an immutable view into this image so long as the provided coordinates and dimensions are within the bounds of this Image.

fn buffer_like(&self) -> ImageBuffer<Self::Pixel, Vec<<Self::Pixel as Pixel>::Subpixel>>

Create an empty ImageBuffer with the same pixel type as this image.

This should ensure metadata such as the color space are transferred without copying any of the pixel data. The idea is to prepare a buffer ready to be filled with a filtered or portion of the channel data from the current image without performing the work of copying the data into that buffer twice.

The default implementation defers to GenericImageView::buffer_like.

fn buffer_with_dimensions(&self, width: u32, height: u32) -> ImageBuffer<Self::Pixel, Vec<<Self::Pixel as Pixel>::Subpixel>>

Create an empty ImageBuffer with different dimensions.

See GenericImageView::buffer_like.

Uses for this are for instances preparing a buffer for only a portion of the image, or extracting the metadata to prepare a buffer of a different pixel type.

fn to_pixel_view(&self) -> Option<ViewOfPixel<'_, Self::Pixel>>

If the buffer has a fitting layout, return a canonical view of the samples.

This is the basis of optimization and by default return None. It lets consumers of generic images access the sample data through a canonical descriptor of its layout directly instead of pixel-by-pixel. This provides more efficient forms of access that the GenericImageView trait itself does not demand from all its implementations.

Implementation of this method should be cheap to call.

If implemented, a SubImage proxy of this image will provide a sample view as well.

Implementors