Struct FlatSamples

pub struct FlatSamples<Buffer> {
    pub samples: Buffer,
    pub layout: SampleLayout,
    pub color_hint: Option<ColorType>,
}

A flat buffer over a (multi channel) image.

In contrast to ImageBuffer, this representation of a sample collection is much more lenient in the layout thereof. It also allows grouping by color planes instead of by pixel as long as the strides of each extent are constant. This struct itself has no invariants on the strides but not every possible configuration can be interpreted as a GenericImageView or GenericImage. The methods as_view and as_view_mut construct the actual implementors of these traits and perform necessary checks. To manually perform this and other layout checks use is_normal or has_aliased_samples.

Instances can be constructed not only by hand. The buffer instances returned by library functions such as ImageBuffer::as_flat_samples guarantee that the conversion to a generic image or generic view succeeds. A very different constructor is with_monocolor. It uses a single pixel as the backing storage for an arbitrarily sized read-only raster by mapping each pixel to the same samples by setting some strides to 0.

Fields

samples: Buffer

Underlying linear container holding sample values.

layout: SampleLayout

A repr(C) description of the layout of buffer samples.

color_hint: Option<ColorType>

Supplementary color information.

You may keep this as None in most cases. This is NOT checked in View or other converters. It is intended mainly as a way for types that convert to this buffer type to attach their otherwise static color information. A dynamic image representation could however use this to resolve representational ambiguities such as the order of RGB channels.

Implementations

impl<Buffer> FlatSamples<Buffer>

pub fn strides_cwh(&self) -> (usize, usize, usize)

Get the strides for indexing matrix-like [(c, w, h)].

For a row-major layout with grouped samples, this tuple is strictly increasing.

pub fn extents(&self) -> (usize, usize, usize)

Get the dimensions (channels, width, height).

The interface is optimized for use with strides_cwh instead. The channel extent will be before width and height.

pub fn bounds(&self) -> (u8, u32, u32)

Tuple of bounds in the order of coordinate inputs.

This function should be used whenever working with image coordinates opposed to buffer coordinates. The only difference compared to extents is the output type.

pub fn as_ref<T>(&self) -> FlatSamples<&[T]>

where Buffer: AsRef<[T]>,

Get a reference based version.

pub fn as_mut<T>(&mut self) -> FlatSamples<&mut [T]>

where Buffer: AsMut<[T]>,

Get a mutable reference based version.

pub fn to_vec<T>(&self) -> FlatSamples<Vec<T>>

where T: Clone, Buffer: AsRef<[T]>,

Copy the data into an owned vector.

pub fn get_sample<T>(&self, channel: u8, x: u32, y: u32) -> Option<&T>

where Buffer: AsRef<[T]>,

Get a reference to a single sample.

This more restrictive than the method based on std::ops::Index but guarantees to properly check all bounds and not panic as long as Buffer::as_ref does not do so.

let flat = RgbImage::new(480, 640).into_flat_samples();

// Get the blue channel at (10, 10).
assert!(flat.get_sample(1, 10, 10).is_some());

// There is no alpha channel.
assert!(flat.get_sample(3, 10, 10).is_none());

For cases where a special buffer does not provide AsRef<[T]>, consider encapsulating bounds checks with min_length in a type similar to View. Then you may use in_bounds_index as a small speedup over the index calculation of this method which relies on index_ignoring_bounds since it can not have a-priori knowledge that the sample coordinate is in fact backed by any memory buffer.

pub fn get_mut_sample<T>( &mut self, channel: u8, x: u32, y: u32, ) -> Option<&mut T>

where Buffer: AsMut<[T]>,

Get a mutable reference to a single sample.

This more restrictive than the method based on std::ops::IndexMut but guarantees to properly check all bounds and not panic as long as Buffer::as_ref does not do so. Contrary to conversion to ViewMut, this does not require that samples are packed since it does not need to convert samples to a color representation.

WARNING: Note that of course samples may alias, so that the mutable reference returned here can in fact modify more than the coordinate in the argument.

let mut flat = RgbImage::new(480, 640).into_flat_samples();

// Assign some new color to the blue channel at (10, 10).
*flat.get_mut_sample(1, 10, 10).unwrap() = 255;

// There is no alpha channel.
assert!(flat.get_mut_sample(3, 10, 10).is_none());

For cases where a special buffer does not provide AsRef<[T]>, consider encapsulating bounds checks with min_length in a type similar to View. Then you may use in_bounds_index as a small speedup over the index calculation of this method which relies on index_ignoring_bounds since it can not have a-priori knowledge that the sample coordinate is in fact backed by any memory buffer.

pub fn as_view<P>(&self) -> Result<View<&[P::Subpixel], P>, Error>

where P: Pixel, Buffer: AsRef<[P::Subpixel]>,

View this buffer as an image over some type of pixel.

This first ensures that all in-bounds coordinates refer to valid indices in the sample buffer. It also checks that the specified pixel format expects the same number of channels that are present in this buffer. Neither are larger nor a smaller number will be accepted. There is no automatic conversion.

pub fn as_view_with_mut_samples<P>( &mut self, ) -> Result<View<&mut [P::Subpixel], P>, Error>

where P: Pixel, Buffer: AsMut<[P::Subpixel]>,

View this buffer but keep mutability at a sample level.

This is similar to as_view but subtly different from as_view_mut. The resulting type can be used as a GenericImage with the same prior invariants needed as for as_view. It can not be used as a mutable GenericImage but does not need channels to be packed in their pixel representation.

This first ensures that all in-bounds coordinates refer to valid indices in the sample buffer. It also checks that the specified pixel format expects the same number of channels that are present in this buffer. Neither are larger nor a smaller number will be accepted. There is no automatic conversion.

WARNING: Note that of course samples may alias, so that the mutable reference returned for one sample can in fact modify other samples as well. Sometimes exactly this is intended.

pub fn as_view_mut<P>( &mut self, ) -> Result<ViewMut<&mut [P::Subpixel], P>, Error>

where P: Pixel, Buffer: AsMut<[P::Subpixel]>,

Interpret this buffer as a mutable image.

To succeed, the pixels in this buffer may not alias each other and the samples of each pixel must be packed (i.e. channel_stride is 1). The number of channels must be consistent with the channel count expected by the pixel format.

This is similar to an ImageBuffer except it is a temporary view that is not normalized as strongly. To get an owning version, consider copying the data into an ImageBuffer. This provides many more operations, is possibly faster (if not you may want to open an issue) is generally polished. You can also try to convert this buffer inline, see ImageBuffer::from_raw.

pub fn as_slice<T>(&self) -> &[T]

where Buffer: AsRef<[T]>,

View the samples as a slice.

The slice is not limited to the region of the image and not all sample indices are valid indices into this buffer. See image_mut_slice as an alternative.

pub fn as_mut_slice<T>(&mut self) -> &mut [T]

where Buffer: AsMut<[T]>,

View the samples as a slice.

The slice is not limited to the region of the image and not all sample indices are valid indices into this buffer. See image_mut_slice as an alternative.

pub fn image_slice<T>(&self) -> Option<&[T]>

where Buffer: AsRef<[T]>,

Return the portion of the buffer that holds sample values.

This may fail when the coordinates in this image are either out-of-bounds of the underlying buffer or can not be represented. Note that the slice may have holes that do not correspond to any sample in the image represented by it.

pub fn image_mut_slice<T>(&mut self) -> Option<&mut [T]>

where Buffer: AsMut<[T]>,

Mutable portion of the buffer that holds sample values.

pub fn try_into_buffer<P>(self) -> Result<ImageBuffer<P, Buffer>, (Error, Self)>

where P: Pixel + 'static, P::Subpixel: 'static, Buffer: Deref<Target = [P::Subpixel]>,

Move the data into an image buffer.

This does not convert the sample layout. The buffer needs to be in packed row-major form before calling this function. In case of an error, returns the buffer again so that it does not release any allocation.

pub fn min_length(&self) -> Option<usize>

Get the minimum length of a buffer such that all in-bounds samples have valid indices.

This method will allow zero strides, allowing compact representations of monochrome images. To check that no aliasing occurs, try check_alias_invariants. For compact images (no aliasing and no unindexed samples) this is width*height*channels. But for both of the other cases, the reasoning is slightly more involved.

Explanation

Note that there is a difference between min_length and the index of the sample ’one-past-the-end`. This is due to strides that may be larger than the dimension below.

Example with holes

Let’s look at an example of a grayscale image with

• width_stride = 1
• width = 2
• height_stride = 3
• height = 2

| x x   | x x m | $
 min_length m ^
                  ^ one-past-the-end $

The difference is also extreme for empty images with large strides. The one-past-the-end sample index is still as large as the largest of these strides while min_length = 0.

Example with aliasing

The concept gets even more important when you allow samples to alias each other. Here we have the buffer of a small grayscale image where this is the case, this time we will first show the buffer and then the individual rows below.

• width_stride = 1
• width = 3
• height_stride = 2
• height = 2

 1 2 3 4 5 m
|1 2 3| row one
    |3 4 5| row two
           ^ m min_length
         ^ ??? one-past-the-end

This time ‘one-past-the-end’ is not even simply the largest stride times the extent of its dimension. That still points inside the image because height*height_stride = 4 but also index_of(1, 2) = 4.

pub fn fits(&self, len: usize) -> bool

Check if a buffer of length len is large enough.

pub fn has_aliased_samples(&self) -> bool

If there are any samples aliasing each other.

If this is not the case, it would always be safe to allow mutable access to two different samples at the same time. Otherwise, this operation would need additional checks. When one dimension overflows usize with its stride we also consider this aliasing.

pub fn is_normal(&self, form: NormalForm) -> bool

Check if a buffer fulfills the requirements of a normal form.

Certain conversions have preconditions on the structure of the sample buffer that are not captured (by design) by the type system. These are then checked before the conversion. Such checks can all be done in constant time and will not inspect the buffer content. You can perform these checks yourself when the conversion is not required at this moment but maybe still performed later.

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

Check that the pixel and the channel index are in bounds.

An in-bound coordinate does not yet guarantee that the corresponding calculation of a buffer index does not overflow. However, if such a buffer large enough to hold all samples actually exists in memory, this property of course follows.

pub fn index(&self, channel: u8, x: u32, y: u32) -> Option<usize>

Resolve the index of a particular sample.

None if the index is outside the bounds or does not fit into a usize.

pub fn index_ignoring_bounds( &self, channel: usize, x: usize, y: usize, ) -> Option<usize>

Get the theoretical position of sample (x, y, channel).

The ‘check’ is for overflow during index calculation, not that it is contained in the image. Two samples may return the same index, even when one of them is out of bounds. This happens when all strides are 0, i.e. the image is an arbitrarily large monochrome image.

pub fn in_bounds_index(&self, channel: u8, x: u32, y: u32) -> usize

Get an index provided it is inbouds.

Assumes that the image is backed by some sufficiently large buffer. Then computation can not overflow as we could represent the maximum coordinate. Since overflow is defined either way, this method can not be unsafe.

pub fn shrink_to(&mut self, channels: u8, width: u32, height: u32)

Shrink the image to the minimum of current and given extents.

This does not modify the strides, so that the resulting sample buffer may have holes created by the shrinking operation. Shrinking could also lead to an non-aliasing image when samples had aliased each other before.

impl<'buf, Subpixel> FlatSamples<&'buf [Subpixel]>

pub fn with_monocolor<P>(pixel: &'buf P, width: u32, height: u32) -> Self

where P: Pixel<Subpixel = Subpixel>, Subpixel: Primitive,

Create a monocolor image from a single pixel.

This can be used as a very cheap source of a GenericImageView with an arbitrary number of pixels of a single color, without any dynamic allocation.

Examples

use image::{flat::FlatSamples, GenericImage, RgbImage, Rgb};

let background = Rgb([20, 20, 20]);
let bg = FlatSamples::with_monocolor(&background, 200, 200);;

let mut image = RgbImage::new(200, 200);
paint_something(&mut image);

// Reset the canvas
image.copy_from(&bg.as_view().unwrap(), 0, 0);

Trait Implementations

impl<Buffer: Clone> Clone for FlatSamples<Buffer>

fn clone(&self) -> FlatSamples<Buffer>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Buffer: Debug> Debug for FlatSamples<Buffer>

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

Formats the value using the given formatter.

impl<Buffer> Index<(u8, u32, u32)> for FlatSamples<Buffer>

where Buffer: Index<usize>,

fn index(&self, (c, x, y): (u8, u32, u32)) -> &Self::Output

Return a reference to a single sample at specified coordinates.

Panics

When the coordinates are out of bounds or the index calculation fails.

type Output = <Buffer as Index<usize>>::Output

The returned type after indexing.

impl<Buffer> IndexMut<(u8, u32, u32)> for FlatSamples<Buffer>

where Buffer: IndexMut<usize>,

fn index_mut(&mut self, (c, x, y): (u8, u32, u32)) -> &mut Self::Output

Return a mutable reference to a single sample at specified coordinates.

Panics

When the coordinates are out of bounds or the index calculation fails.