# bmp-ts

> A pure typescript BMP encoder and decoder

Latest version **1.0.9** (published 2024-03-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install bmp-ts
pnpm add bmp-ts
yarn add bmp-ts
bun add bmp-ts
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.9 |
| Published | 2024-03-24 |
| First published | 2019-09-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 136 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 18 |
| Author | Andrew lisowski |
| Maintainers | alisowski |
| Keywords | bmp, 1bit, 4bit, 8bit, 16bit, 24bit, 32bit, encoder, decoder, image, javascript, js |

## Links

- npm: https://www.npmjs.com/package/bmp-ts
- Repository: https://github.com/hipstersmoothie/bmp-ts
- Homepage: https://github.com/hipstersmoothie/bmp-ts#readme
- Issues: https://github.com/hipstersmoothie/bmp-ts/issues
- npm.io page: https://npm.io/package/bmp-ts

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 1.0.9 (latest) — 2024-03-24
- 1.0.4-canary.f6048cc (canary) — 2020-12-11
- 1.0.8 — 2024-03-23
- 1.0.7 — 2024-03-23
- 1.0.6 — 2024-03-23
- 1.0.5 — 2024-03-23
- 1.0.4 — 2023-07-26
- 1.0.4-canary.c510de9 — 2020-09-07
- 1.0.4-canary.af834ad — 2020-04-05
- 1.0.3 — 2019-10-15
- 1.0.3-canary.4716b39 — 2019-10-15
- 1.0.2 — 2019-09-30
- 1.0.1 — 2019-09-30
- 1.0.1-canary.698cc0c — 2019-09-30
- 1.0.1-canary.fbd7a34 — 2019-09-30
- … 12 more at https://npm.io/package/bmp-ts/versions

## README

<div align="center">
  <img width="200" height="200"
    src="./logo.png">
  <h1>bmp-ts</h1>
  <p>A pure typescript <code>bmp</code> encoder and decoder.</p>
</div

[![Codecov](https://img.shields.io/codecov/c/github/hipstersmoothie/bmp-ts.svg?style=for-the-badge)](https://codecov.io/gh/hipstersmoothie/bmp-ts)
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=for-the-badge)](https://github.com/prettier/prettier)

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

## Install

```sh
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](#header).

```js
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`

```js
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.

```js
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:

```json
{
  "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.

```js
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);
```

---
_Source: https://npm.io/package/bmp-ts · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._