A pure typescript BMP encoder and decoder for node.js
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is 90 commits ahead of shaozilee:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
lib
test
types
.gitignore
LICENSE
README.md
logo.png
package.json
test.bmp
tsconfig.json
tslint.json
yarn.lock

README.md

bmp-ts

A pure typescript bmp encoder and decoder.

CircleCI 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);