Skip to content

jimp-dev/bmp-ts

Repository files navigation

bmp-ts

A pure typescript bmp encoder and decoder.

Codecov code style: prettier

Supports decoding and encoding in all bit depths (1, 4, 8, 16, 24, 32).

Install

npm install 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.

const bmp = require('bmp-ts').default;
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
const bmp = require('bmp-ts').default;
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.

const bmp = require('bmp-ts').default;
const fs = require('fs');
const bmpData = {
  data, // Buffer
  bitPP: 1 | 2 | 4 | 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);