Supports decoding and encoding in all bit depths (1, 4, 8, 16, 24, 32). Compatible with the browser and Node.js.

Install

npm install @wokwi/bmp-ts

Usage

Decoding

decode will return an object that includes all the header properties of the bmp image file and the data. See header definition below.

import bmp from '@wokwi/bmp-ts';
import fs from 'fs';
const bmpBuffer = fs.readFileSync('bit24.bmp');
const bmpData = bmp.decode(bmpBuffer);

Options

• toRGBA - switch the output to big endian RGBA, making it compatible with other libraries like pngjs

import bmp from '@wokwi/bmp-ts';
import fs from 'fs';
const bmpBuffer = fs.readFileSync('bit24.bmp');
const bmpData = bmp.decode(bmpBuffer, { toRGBA: true });

Supported Compression Methods

Currently compression is only supported during decoding. The following methods are implemented:

• NONE - Most common
• BI_RLE8 - Can be used only with 8-bit/pixel bitmap
• BI_RLE4 - Can be used only with 4-bit/pixel bitmaps
• BI_BIT_FIELDS - Huffman 1D - BITMAPV2INFOHEADER: RGB bit field masks, BITMAPV3INFOHEADER+: RGBA
• BI_ALPHA_BIT_FIELDS - RGBA bit field masks - only Windows CE 5.0 with .NET 4.0 or later

Encoding

To encode an image all you need is a buffer with the image data, the height and the width. You can specify the bit depth of the output image by modifying bitPP. If you do not provide a value, the output image defaults to 24-bit.

All header fields are valid options to encode and will be encoded into the header.

import bmp from '@wokwi/bmp-ts';
import fs from 'fs';
const bmpData = {
  data, // Buffer
  bitPP: 1 | 4 | 8 | 16 | 24 | 32, // The number of bits per pixel
  width, // Number
  height // Number
};

// Compression is not supported
const rawData = bmp.encode(bmpData);
fs.writeFileSync('./image.bmp', rawData.data);

Header

| Property | Type | Purpose | | --------------- | ------- | ------------------------------------------------------------------------------------------------------ | | fileSize | number | The size of the BMP file in bytes | | reserve1 | number | Reserved; actual value depends on the application that creates the image | | reserve2 | number | Reserved; actual value depends on the application that creates the image | | offset | number | The offset, i.e. starting address, of the byte where the bitmap image data (pixel array) can be found. | | headerSize | number | The size of this header (12 bytes) | | width | number | The bitmap width in pixels (unsigned 16-bit) | | height | number | The bitmap height in pixels (unsigned 16-bit) | | planes | number | The number of color planes, must be 1 | | bitPP | number | The number of bits per pixel | | compress | number | The compression method being used. See the supported compression methods | | rawSize | number | The image size. This is the size of the raw bitmap data; a dummy 0 can be given for BI_RGB bitmaps. | | hr | number | The horizontal resolution of the image. (pixel per metre, signed integer) | | vr | number | The vertical resolution of the image. (pixel per metre, signed integer) | | colors | number | The number of colors in the color palette, or 0 to default to 2n | | importantColors | number | The number of important colors used, or 0 when every color is important; generally ignored | | palette | Color[] | The colors used to render the image. only used for 1, 4, and 8 bitPP images | | data | Byte[] | The data in ABGR |

Color

The color palette is returned when decoding a 1, 4, or 8 bit image.

Color Format:

{
  "red": 255,
  "green": 255,
  "blue": 255,
  "quad": 255
}

To encode to 4 or 8 bit a color palette must be provided. 1 bit defaults to black and white but you can override this via palette.

const rawData = bmp.encode({
  data,
  bitPP: 8,
  width,
  height,
  palette: [
    { red: 255, green: 255, blue: 255, quad: 0 },
    { red: 255, green: 255, blue: 0, quad: 0 },
    { red: 255, green: 0, blue: 255, quad: 0 },
    { red: 255, green: 0, blue: 0, quad: 0 },
    { red: 0, green: 255, blue: 255, quad: 0 },
    { red: 0, green: 255, blue: 0, quad: 0 },
    { red: 0, green: 0, blue: 255, quad: 0 },
    { red: 0, green: 0, blue: 0, quad: 0 }
  ]
});

fs.writeFileSync('./image.bmp', rawData.data);