Crate plumers

Expand description

A library providing a uniform interface to several image formats.

How about a quick example?

use plumers::prelude::*;

// A 5x5 GIF, containing pure white and one magenta pixel in the middle.
const GIF: [u8; 38] = [
    0x47, 0x49, 0x46, 0x38, 0x37, 0x61, 0x05, 0x00,
    0x05, 0x00, 0x80, 0x01, 0x00, 0xff, 0x00, 0xff,
    0xff, 0xff, 0xff, 0x2c, 0x00, 0x00, 0x00, 0x00,
    0x05, 0x00, 0x05, 0x00, 0x00, 0x02, 0x05, 0x8c,
    0x8f, 0x06, 0xc9, 0x51, 0x00, 0x3b,
];

let mut img =
    PalettedImage32::load(GIF, Default::default(), AlphaMode::ZeroIsTransparent).unwrap();
assert_eq!(img.nb_frames(), 1);

// Swap the green and blue components of each colour.
for color in img.palette_mut() {
    let (red, green, blue, alpha) = color.decode();
    *color = Rgb32::encode(red, blue, green, alpha);
}

// Also set the top row of pixels to be yellow as well.
// (This shows how to mutate the image in-place.)

// It's possible to create colours directly, if desired. (CSS-like notation is used here.)
assert_eq!(img.palette()[0], Rgb32(0xFFFF00FFu32.swap_bytes()));

let width = img.width();
let mut frame = img.frame_mut(0);
for x in 0..width {
    frame[(x, 0)] = 0; // Index 0 maps to yellow, as asserted above.
}

img.set_format(ImageFormat::Bmp);
img.store("test.bmp").unwrap();

§Elevator pitch

This crate is a wrapper around libplum, so its documentation may come in handy from time to time; this documentation occasionally references it.

libplum is a small (~8000 lines of code), entirely self-contained library, fully supporting the GIF, BMP, PNG, APNG, JPEG, and PNM formats. It does not provide any format-specific APIs, instead opting for a more streamlined, one-size-fits-all API; but it does handle animated formats.

Notably, formats are automatically detected when loading images, which makes loading quite convenient. Images are loaded into a pixel buffer, with a choice of four different pixel formats.

Something quite unique to this library, unlike other format-agnostic designs, is first-class support for colour palettes. This can reduce memory usage, speed up whole-image operations, and let you access this information for some (arguably niche) use cases.

While libplum is written in C, particular care has been put into correctly handling invalid data, and it’s been extensively fuzz-tested. Therefore, it is reasonable to expect it to be memory-safe, yet also quite efficient.

§Getting started

If using this library, you’ll likely want to manipulate images. The first order of business is picking a pixel format, i.e. how the pixels will be stored, and whether you want your image to be paletted.

Do you want palettes?	This type is for you:
Yes	`PalettedImage`
No	`DirectImage`
Sometimes	`DynImage`

Then, obtaining an image; either create one from scratch using one of the new* methods, or load it. (If the image comes from a source you can’t trust, for example if you’re a web service, consider load_limited instead).

Modules§

color: Supported color formats.
image: The meat of this crate.
prelude: For convenient access, one can simply use plumers::prelude::*;.

Enums§

Error: An error that can be generated by libplum.

Type Aliases§

Result: Result<T, plumers::Error>