API Documentation

package

microbmp

A small Python module for BMP image processing.

  • Author: Quan Lin
  • License: MIT

It supports BMP image of 1/2/4/8/24-bit colour depth.

  • Loading supports compression method:
    • 0(BI_RGB, no compression)
    • 1(BI_RLE8, RLE 8-bit/pixel)
    • 2(BI_RLE4, RLE 4-bit/pixel)
  • Saving only supports compression method 0(BI_RGB, no compression).
Examples 
>>> from microbmp import MicroBMP
>>> img_24b_2x2 = MicroBMP(2, 2, 24)  # Create a 2(width) by 2(height) 24-bit image.
>>> img_24b_2x2.palette  # 24-bit image has no palette.
>>> img_24b_2x2.parray  # Pixels are arranged horizontally (top-down) in RGB order.
bytearray(b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')
>>> img_24b_2x2[1, 1] = 255, 255, 255  # Access 1 pixel (R, G, B): img[x, y]
>>> img_24b_2x2[0, 1, 0] = 255  # Access 1 primary colour of 1 pixel (Red): img[x, y, c]
>>> img_24b_2x2[1, 0, 1] = 255  # (Green)
>>> img_24b_2x2[0, 0, 2] = 255  # (Blue)
>>> img_24b_2x2.save("img_24b_2x2.bmp")
70
>>> new_img_24b_2x2 = MicroBMP().load("img_24b_2x2.bmp")
>>> new_img_24b_2x2.palette
>>> new_img_24b_2x2.parray
bytearray(b'\x00\x00\xff\x00\xff\x00\xff\x00\x00\xff\xff\xff')
>>> print(new_img_24b_2x2)
BMP image, RGB, 24-bit, 2x2 pixels, 70 bytes
>>> img_1b_3x2 = MicroBMP(3, 2, 1)  # Create a 3(width) by 2(height) 1-bit image.
>>> img_1b_3x2.palette  # Each colour is in the order of (R, G, B)
[bytearray(b'\x00\x00\x00'), bytearray(b'\xff\xff\xff')]
>>> img_1b_3x2.parray  # Each bit stores the colour index in HLSB format.
bytearray(b'\x00')
>>> " ".join([f"{bin(byte)[2:]:0>8}" for byte in img_1b_3x2.parray])
'00000000'
>>> img_1b_3x2[1, 0] = 1  # Access 1 pixel (index): img[x, y]
>>> img_1b_3x2[1, 1] = 1
>>> img_1b_3x2[2, 1] = 1
>>> img_1b_3x2.save("img_1b_3x2.bmp")
70
>>> new_img_1b_3x2 = MicroBMP().load("img_1b_3x2.bmp")
>>> new_img_1b_3x2.palette
[bytearray(b'\x00\x00\x00'), bytearray(b'\xff\xff\xff')]
>>> new_img_1b_3x2.parray
bytearray(b'L')
>>> " ".join([f"{bin(b)[2:]:0>8}" for b in new_img_1b_3x2.parray])
'01001100'
>>> print(new_img_1b_3x2)
BMP image, indexed, 1-bit, 3x2 pixels, 70 bytes
Classes
class

microbmp.MicroBMP(width=None, height=None, depth=None, palette=None)

MicroBMP class.

Parameters
  • width (int, optional) — The width of the image. (default is None)
  • height (int, optional) — The height of the image. (default is None)
  • depth (int, optional) — The colour depth of the image, must be in (1, 2, 4, 8, 24). (default is None)
  • palette (list of bytearray, optional) — The colour palette of indexed images (colour depth of 1, 2, 4, or 8). Images of 24-bit colour depth has no palette (None). Each colour is represented by a 3-element bytearray in RGB order. (default is None)
Attributes
  • BMP_size (int) — The number of bytes the image takes from the file system.
  • DIB_comp (int) — The compression method of the image read from the file system.
  • DIB_depth (int) — The colour depth of the image.
  • DIB_h (int) — The height of the image.
  • DIB_w (int) — The width of the image.
  • load(file_path) — Load image from BMP file.
  • palette (list of bytearray, optional) — The colour palette of indexed images (colour depth of 1, 2, 4, or 8). Images of 24-bit colour depth has no palette (None). Each colour is represented by a 3-element bytearray in RGB order.
  • parray (bytearray) — The pixel array of the image. The first pixel is at the top-left corner of the image (origin). For 1/2/4/8-bit image, the pixels are colour indices arranged in HLSB format. So the high bits are at the leftmost. For 24-bit image, the pixels are arranged horizontally (top-down) in RGB order.
  • read_io(bf_io) — Read image from BytesIO or FileIO.
  • save(file_path, force_40B_DIB=False): — Save image to BMP file.
  • write_io(bf_io, force_40B_DIB=False): — Write image to BytesIO or FileIO.

Notes

  • To get or set the colour index of a pixel of a 1/2/4/8-bit image : img[x, y]
  • To get or set the r, g, b values of a pixel of a 24-bit image : img[x, y]
  • To get or set a primary colour value of a pixel of a 24-bit image : img[x, y, c]
Methods
  • load(file_path) (MicroBMP) — Load image from BMP file.
  • read_io(bf_io) (MicroBMP) — Read image from BytesIO or FileIO.
  • save(file_path, force_40B_DIB) (int) — Save image to BMP file.
  • write_io(bf_io, force_40B_DIB) (int) — Write image to BytesIO or FileIO.
method
read_io(bf_io)

Read image from BytesIO or FileIO.

Parameters
  • bf_io (BytesIO or FileIO) — The input BMP image BytesIO or FileIO.
Returns (MicroBMP)

self.

method
write_io(bf_io, force_40B_DIB=False)

Write image to BytesIO or FileIO.

Parameters
  • bf_io (BytesIO or FileIO) — The output BMP image BytesIO or FileIO.
  • force_40B_DIB (bool, optional) — Force the size of DIB to be 40 bytes or not. (default is False)
Returns (int)

The number of bytes written to the io.

method
load(file_path)

Load image from BMP file.

Parameters
  • file_path (str) — Input file full path.
Returns (MicroBMP)

self.

method
save(file_path, force_40B_DIB=False)

Save image to BMP file.

Parameters
  • file_path (str) — Output file full path.
  • force_40B_DIB (bool, optional) — Force the size of DIB to be 40 bytes or not. (default is False)
Returns (int)

The number of bytes written to the file.