Struct KnownSizeMerger

pub struct KnownSizeMerger<P, Container>
where
    P: Pixel,
    <P as Pixel>::Subpixel: Sync,
    Container: DerefMut<Target = [P::Subpixel]> + Sync,
{ /* private fields */ }

A known size merger that allows you to paste images onto a canvas. This merger is useful when you already know the size of all the images being pushed onto the canvas. This merger has multiple implementations, one for any container type and one for Vec specifically.

Type Parameters

• P - The pixel type of the underlying image.
• Container - The underlying image buffer type. This must be dereferenceable to a slice of the underlying image’s subpixels.

Example

use image_merger::{Merger, KnownSizeMerger, Image, Rgb};

let mut merger: KnownSizeMerger<Rgb<u8>, _> = KnownSizeMerger::new((100, 100), 5, 10, None);
let image = Image::new(100, 100);
merger.bulk_push(&[&image, &image, &image, &image, &image]);

Implementations

impl<P, Container> KnownSizeMerger<P, Container>

where P: Pixel + Sync, <P as Pixel>::Subpixel: Sync, Container: DerefMut<Target = [P::Subpixel]> + Sync,

pub fn new_from_raw( image_dimensions: (u32, u32), images_per_row: u32, total_images: u32, padding: Option<Padding>, container: Container, ) -> Option<Self>

Constructs a new KnownSizeMerger from a raw image buffer. This is useful if you need to use a specific container type that is not Vec. Typically, you only need to use new to create a KnownSizeMerger unless you need to use a specific container type.

Arguments

• image_dimensions - The dimensions of the images being pasted (images must be a uniform size)
• images_per_row - The number of images per row.
• total_images - The total number of images to be in the final canvas.
• padding - The padding between images, or None for no padding.
• container - The container to use for the underlying canvas. This container must be big enough to hold all the potential images that will be pasted to the canvas.

Returns

• Some - If the merger was successfully created.
• None - If the merger could not be created. This will happen if the container is not large enough to fit all the images.

Example

use image_merger::{KnownSizeMerger, Rgb};

let container = vec![0 as u8; 100 * 100 * 5 * 10 * 3];
let merger: KnownSizeMerger<Rgb<u8>, _> = KnownSizeMerger::new_from_raw((100, 100), 5, 10, None, container).expect("Could not create merger!");

pub fn get_num_images(&self) -> u32

Returns the number of images that have been pasted to the canvas.

pub fn get_image_dimensions(&self) -> (u32, u32)

Returns the dimensions, (x, y), of the images being pasted to the canvas.

pub fn remove_image_raw( &mut self, index: u32, container: Container, ) -> Option<()>

Removes an image from the canvas at the given index. Indices start at 0 and work left to right, top to bottom. Most of the time you will not need to use this function, and rather, can use the remove_image method instead. This method is useful if you need to manually manage a specific Container type that is not Vec.

Arguments

• index - The index of the image to remove.
• container - The container to use to replace the image. The container must be the same size as the image being removed, thus, the container must be the same size as the image dimensions.

Returns

• Some - If the image was successfully removed.
• None - If the image could not be removed. This will happen if the container is not large enough to fit the image.

impl<P> KnownSizeMerger<P, Vec<P::Subpixel>>

where P: Pixel + Sync, <P as Pixel>::Subpixel: Sync,

pub fn new( image_dimensions: (u32, u32), images_per_row: u32, total_images: u32, padding: Option<Padding>, ) -> Self

Constructs a new KnownSizeMerger. By default, this will create an underlying canvas with Vec as the container type. If you need to use a different container type, you can use the new_from_raw method.

Arguments

• image_dimensions - The dimensions of the images being pasted (images must be a uniform size)
• images_per_row - The number of images per row.
• total_images - The total numbr of images to be in the final canvas.
• padding - The padding between images, or None for no padding.

Examples found in repository

examples/known_size_merger.rs (lines 23-28)

fn main() -> () {
    // Generate a image we can paste to our canvas. In a real application, this may be an opened
    // image file or buffer of some sort. For the sake of example, the constants IMAGE_WIDTH and IMAGE_HEIGHT
    // will represent our known image dimensions.
    let known_image = generate_known_image();

    // Create an instane of our merger, this is what will manage the merging of our images. It takes one generic
    // parameter, T, which denotes the type of pixel the canvas and pasted images have.
    let mut merger: KnownSizeMerger<Rgba<u8>, _> = KnownSizeMerger::new(
        (IMAGE_WIDTH, IMAGE_HEIGHT),
        IMAGES_PER_ROW,
        TOTAL_IMAGES,
        None,
    );

    // Let's go through and paste our images onto the canvas, we can do this one of two ways:
    // 1. We can paste the images one at a time in a loop, using the "push()" method, or:
    // 2: We can use the "bulk_push()" method to paste multiple images at once.
    // For this example, we'll use the "bulk_push()" method.
    let images: Vec<&BufferedImage<Rgba<u8>>> = vec![&known_image; TOTAL_IMAGES as usize];
    merger.bulk_push(&images);

    // Finally, we can get the canvas and save it - we should have a red image with 10000 pixels.
    let canvas = merger.get_canvas();
    canvas.save("examples/known_size_merger.png").unwrap();
}

pub fn remove_image(&mut self, index: u32)

Removes an image from the canvas at a given index. Indexing starts at 0 and works left to right, top to bottom.

Arguments

• index - The index of the image to remove.

Trait Implementations

impl<P, Container> Merger<P, Container> for KnownSizeMerger<P, Container>

where P: Pixel + Sync, <P as Pixel>::Subpixel: Sync, Container: DerefMut<Target = [P::Subpixel]> + Sync,

fn get_canvas(&self) -> &Image<P, ImageBuffer<P, Container>>

Returns a reference to the underlying canvas.

fn into_canvas(self) -> Image<P, ImageBuffer<P, Container>>

Consumes the underlying merger and returns the canvas.

fn push(&mut self, image: &Image<P, ImageBuffer<P, Container>>)

Allows the merger to push an image to the canvas. This can be used in a loop to paste a large number of images without having to hold all them in memory.

fn bulk_push(&mut self, images: &[&Image<P, ImageBuffer<P, Container>>])

Allows the merger to bulk push N images to the canvas. This is useful for when you have a large number of images to paste. The downside is that you have to hold all of the images in memory at once, which can be a problem if you have a large number of images.