BMP Image Encoder/Decoder

Common errors

• TypeError: Cannot read properties of undefined (reading 'decode')

  cause This error typically occurs in CommonJS environments when attempting to call `bmp.decode` (or `bmp.encode`) after importing `bmp-ts` without accessing the default export.
  fix In CommonJS, explicitly use `.default`: `const bmp = require('bmp-ts').default;`.

• TypeError: bmp.decode is not a function

  cause This can happen in ESM if `import * as bmp from 'bmp-ts';` is used, treating the module as a namespace object, when `decode` is a property of the default export, not a named export.
  fix Use `import bmp from 'bmp-ts';` to import the default export directly.

• Property 'data' is missing in type '{ data: Buffer; bitPP: number; width: number; height: number; }' but required in type 'BmpDataInput'.

  cause A TypeScript compilation error indicating that the object passed to `bmp.encode` is missing required properties or has incorrect types.
  fix Ensure the object passed to `bmp.encode` strictly conforms to the `BmpDataInput` interface, including `data` (Buffer), `width` (number), `height` (number), and `bitPP` (number).

• The image data is not correctly decoded and appears flipped vertically.

  cause This is a known issue for bottom-up BMP images in versions prior to `v1.0.5`.
  fix Upgrade `bmp-ts` to version `1.0.5` or newer. If upgrading isn't possible, manual image data manipulation might be required to flip the image vertically after decoding.

Warnings

• breaking Version 1.0.0 introduced breaking changes to the API. Users upgrading from pre-1.0 versions will need to adapt their code to the new interface, which standardized the `decode` and `encode` methods.
  Fix: Review the new API usage in the README or package documentation for correct method signatures and object structures.
• gotcha The `encode` function in `bmp-ts` currently does not support any compression methods. All output BMP files generated by encoding will be uncompressed, which can result in larger file sizes.
  Fix: Be aware that encoded files will be larger. If compressed BMPs are required, external tools or post-processing will be necessary.
• gotcha CommonJS users must access the default export of `bmp-ts` via `.default` (e.g., `require('bmp-ts').default`). Directly using `require('bmp-ts')` will not expose the `decode` and `encode` methods directly, leading to runtime errors.
  Fix: Always append `.default` when importing `bmp-ts` in CommonJS environments: `const bmp = require('bmp-ts').default;`
• gotcha Prior to version 1.0.5, `bmp-ts` had a bug that caused decoding errors or incorrect image data when processing bottom-up BMP images.
  Fix: Upgrade to `bmp-ts@1.0.5` or a newer version to ensure correct decoding of all BMP image orientations.
• gotcha Versions prior to 1.0.4 experienced issues with CommonJS module resolution, which could prevent the package from being imported correctly in certain Node.js environments.
  Fix: Update to `bmp-ts@1.0.4` or a later version to resolve CommonJS import problems and ensure proper module loading.

Install

• npm install bmp-ts npm
• yarn add bmp-ts yarn
• pnpm add bmp-ts pnpm

Imports

• bmp
  wrong:

  import { decode, encode } from 'bmp-ts';

  correct:

  import bmp from 'bmp-ts';

  The primary `bmp` object is a default export, containing `decode` and `encode` methods.
• bmp (CommonJS)
  wrong:

  const bmp = require('bmp-ts');

  correct:

  const bmp = require('bmp-ts').default;

  In CommonJS, the default export must be explicitly accessed via `.default`.
• BmpData (Type)

  import type { BmpData, BmpHeader } from 'bmp-ts';

  TypeScript types for the decoded image data and header are available for explicit import.

Quickstart

Demonstrates how to decode an existing BMP file and encode a new BMP image from raw pixel data using `bmp-ts`.

import bmp from 'bmp-ts';
import * as fs from 'fs';

// --- Decoding a BMP image ---
// Ensure 'example.bmp' exists in the execution directory for this to run.
// You can replace this with any Buffer containing BMP data.
try {
  const bmpBuffer = fs.readFileSync('example.bmp'); 
  const decodedBmpData = bmp.decode(bmpBuffer, { toRGBA: true });
  console.log('Decoded BMP Header:', decodedBmpData.header);
  console.log('Decoded BMP Data length:', decodedBmpData.data.length);
  console.log('Decoded BMP dimensions:', decodedBmpData.header.width, 'x', decodedBmpData.header.height);
} catch (error) {
  console.error('Error decoding example.bmp:', error);
}

// --- Encoding a new BMP image ---
// Create a dummy image buffer (e.g., a 10x10 white image with alpha)
const width = 10;
const height = 10;
const pixelData = Buffer.alloc(width * height * 4, 255); // RGBA white pixels

const bmpDataToEncode = {
  data: pixelData,
  bitPP: 32, // 32-bit RGBA
  width: width,
  height: height
  // Optional: other BMP header fields can be specified here.
};

const encodedRawData = bmp.encode(bmpDataToEncode);
fs.writeFileSync('./output.bmp', encodedRawData.data);
console.log('Encoded 10x10 32-bit white BMP saved to output.bmp');