TinyBMP

Documentation

A small BMP parser primarily for embedded, no-std environments but usable anywhere.

This crate is primarily targeted at drawing BMP images to [embedded_graphics] [DrawTarget]s, but can also be used to parse BMP files for other applications.

Examples

Draw a BMP image to an embedded-graphics draw target

The [Bmp] struct is used together with [embedded_graphics]' [Image] struct to display BMP files on any draw target.

use embedded_graphics::{image::Image, prelude::*};
use tinybmp::Bmp;

// Include the BMP file data.
let bmp_data = include_bytes!("../tests/chessboard-8px-color-16bit.bmp");

// Parse the BMP file.
let bmp = Bmp::from_slice(bmp_data).unwrap();

// Draw the image with the top left corner at (10, 20) by wrapping it in
// an embedded-graphics `Image`.
Image::new(&bmp, Point::new(10, 20)).draw(&mut display)?;

Using the pixel iterator

To access the image data for other applications the [Bmp::pixels] method returns an iterator over all pixels in the BMP file. The colors inside the BMP file will automatically converted to one of the color types in [embedded_graphics].

use embedded_graphics::{pixelcolor::Rgb888, prelude::*};
use tinybmp::Bmp;

// Include the BMP file data.
let bmp_data = include_bytes!("../tests/chessboard-8px-24bit.bmp");

// Parse the BMP file.
// Note that it is necessary to explicitly specify the color type which the colors in the BMP
// file will be converted into.
let bmp = Bmp::<Rgb888>::from_slice(bmp_data).unwrap();

for Pixel(position, color) in bmp.pixels() {
    println!("R: {}, G: {}, B: {} @ ({})", color.r(), color.g(), color.b(), position);
}

Accessing individual pixels

[Bmp::pixel] can be used to get the color of individual pixels. The returned color will be automatically converted to one of the color types in [embedded_graphics].

use embedded_graphics::{pixelcolor::Rgb888, image::GetPixel, prelude::*};
use tinybmp::Bmp;

// Include the BMP file data.
let bmp_data = include_bytes!("../tests/chessboard-8px-24bit.bmp");

// Parse the BMP file.
// Note that it is necessary to explicitly specify the color type which the colors in the BMP
// file will be converted into.
let bmp = Bmp::<Rgb888>::from_slice(bmp_data).unwrap();

let pixel = bmp.pixel(Point::new(3, 2));

assert_eq!(pixel, Some(Rgb888::WHITE));

Note that you currently cannot access invidual pixels when working with RLE4 or RLE8 compressed indexed bitmaps. With these formats the pixel() function will always return None.

Accessing the raw image data

For most applications the higher level access provided by [Bmp] is sufficient. But in case lower level access is necessary the [RawBmp] struct can be used to access BMP header information and the color table. A [RawBmp] object can be created directly from image data by using [from_slice] or by accessing the underlying raw object of a [Bmp] object with [Bmp::as_raw].

Similar to [Bmp::pixel], [RawBmp::pixel] can be used to get raw pixel color values as a u32.

use embedded_graphics::prelude::*;
use tinybmp::{RawBmp, Bpp, Header, RawPixel, RowOrder, CompressionMethod};

let bmp = RawBmp::from_slice(include_bytes!("../tests/chessboard-8px-24bit.bmp"))
    .expect("Failed to parse BMP image");

// Read the BMP header
assert_eq!(
    bmp.header(),
    &Header {
        file_size: 314,
        image_data_start: 122,
        bpp: Bpp::Bits24,
        image_size: Size::new(8, 8),
        image_data_len: 192,
        channel_masks: None,
        row_order: RowOrder::BottomUp,
        compression_method: CompressionMethod::Rgb,
    }
);

// Get an iterator over the pixel coordinates and values in this image and load into a vec
let pixels: Vec<RawPixel> = bmp.pixels().collect();

// Loaded example image is 8x8px
assert_eq!(pixels.len(), 8 * 8);

// Individual raw pixel values can also be read
let pixel = bmp.pixel(Point::new(3, 2));

// The raw value for a white pixel in the source image
assert_eq!(pixel, Some(0xFFFFFFu32));

Minimum supported Rust version

The minimum supported Rust version for tinybmp is 1.81 or greater. Ensure you have the correct version of Rust installed, preferably through https://rustup.rs.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.