TinyBMP

Build Status Crates.io Docs.rs embedded-graphics on Matrix

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.

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

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

// Parse the BMP file. let bmp = Bmp::fromslice(bmpdata).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].

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

// Include the BMP file data. let bmpdata = includebytes!("../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::::fromslice(bmpdata).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].

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

// Include the BMP file data. let bmpdata = includebytes!("../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::::fromslice(bmpdata).unwrap();

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

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

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.

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

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

// Read the BMP header asserteq!( bmp.header(), &Header { filesize: 314, imagedatastart: 122, bpp: Bpp::Bits24, imagesize: Size::new(8, 8), imagedatalen: 192, channelmasks: None, row_order: RowOrder::BottomUp, } );

// Get an iterator over the pixel coordinates and values in this image and load into a vec let pixels: Vec = 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.61 or greater. Ensure you have the correct version of Rust installed, preferably through https://rustup.rs.

License

Licensed under either of

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.