BMP Encoder/Decoder for Node.js

Common errors

• TypeError: bmp.decode is not a function

  cause Attempting to use `import { decode } from 'bmp-js';` or an incorrect CommonJS require pattern, leading to `bmp` not being the module object.
  fix Use the correct CommonJS require syntax to import the module: `const bmp = require('bmp-js');` and then access methods as `bmp.decode(buffer);`.

• Error: ENOENT: no such file or directory, open 'your_file.bmp'

  cause The specified BMP file does not exist at the given path or the path is incorrect.
  fix Verify the file path is correct and the file exists. Use an absolute path if necessary, or ensure the file is in the current working directory of your script.

• TypeError [ERR_INVALID_ARG_TYPE]: The "data" argument must be of type string or an instance of Buffer, TypedArray, or DataView. Received undefined

  cause The object passed to `bmp.encode()` is missing the `data` property, or its value is `undefined`. Alternatively, `width` or `height` properties might be missing or invalid.
  fix Ensure the object passed to `bmp.encode()` contains `data` (a Buffer), `width` (a Number), and `height` (a Number) with valid values, e.g., `bmp.encode({ data: pixelBuffer, width: 100, height: 50 });`.

Warnings

• gotcha The package is in a pre-1.0 state (version 0.1.0) and appears to be unmaintained since its last update. This implies potential lack of security patches, bug fixes, or compatibility updates for newer Node.js versions or evolving BMP specifications. Use with caution in production environments.
  Fix: Evaluate alternatives like `sharp` (which uses native bindings but is actively maintained) or other image processing libraries if active maintenance and modern features are critical.
• breaking The library exclusively uses CommonJS modules (`require`). It does not provide ESM exports, meaning direct `import` statements will fail or lead to unexpected behavior in ESM-only Node.js environments or modern browser module setups.
  Fix: Ensure your project is configured for CommonJS or use dynamic `import()` for ESM environments: `const bmp = await import('bmp-js');` (though still accessing methods via `bmp.default.decode`). The recommended fix for Node.js is to use `const bmp = require('bmp-js');`.
• gotcha While `bmp-js` supports decoding various bit depths (1, 4, 8, 16, 24, 32), its encoding functionality is strictly limited to 24-bit BMPs without compression. Attempting to encode other bit depths or compressed formats is not supported.
  Fix: If you need to encode BMPs with different bit depths or compression, consider using a more feature-rich image processing library.
• gotcha The `data` property returned by `bmp.decode()` represents pixel data in ABGR (Alpha, Blue, Green, Red) byte order, with 4 bytes per pixel. This can be confusing as many image formats use RGBA or BGRA, and standard BMP usually implies BGRA without alpha.
  Fix: When manipulating `bmpData.data`, always account for the ABGR byte order: `data[i]` (Alpha), `data[i+1]` (Blue), `data[i+2]` (Green), `data[i+3]` (Red) for pixel `i/4`.

Install

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

Imports

• bmp
  wrong:

  import bmp from 'bmp-js';

  correct:

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

  The package only provides CommonJS exports. Direct ESM imports like `import bmp from 'bmp-js';` will result in a runtime error or an empty object.
• decode
  wrong:

  import { decode } from 'bmp-js';

  correct:

  const bmp = require('bmp-js');
  const bmpData = bmp.decode(buffer);

  The `decode` function is a method of the default CommonJS export. It is not available as a named ESM export.
• encode
  wrong:

  import { encode } from 'bmp-js';

  correct:

  const bmp = require('bmp-js');
  const outputBuffer = bmp.encode(bmpData);

  The `encode` function is a method of the default CommonJS export. It is not available as a named ESM export.

Quickstart

This example demonstrates how to read a BMP file, decode it using `bmp-js`, access and modify its raw pixel data (ABGR format), and then re-encode the modified data back into a new 24-bit BMP file.

const fs = require('fs');
const bmp = require('bmp-js');

// To run this example, ensure you have a 'bit24.bmp' file
// in the same directory, or create a dummy one.

async function processBmp() {
  try {
    // 1. Decode a BMP file
    const inputBuffer = fs.readFileSync('bit24.bmp');
    const bmpData = bmp.decode(inputBuffer);

    console.log('Decoded BMP properties:');
    console.log(`Width: ${bmpData.width}, Height: ${bmpData.height}`);
    console.log(`Bits Per Pixel: ${bmpData.bitPP}`);
    console.log(`Pixel Data Length: ${bmpData.data.length} bytes`);

    // 2. Modify pixel data (e.g., set top-left pixel to solid red)
    // The `data` property is a byte array ordered by ABGR ABGR ABGR.
    if (bmpData.data.length >= 4) {
      bmpData.data[0] = 0x00; // Alpha (ignored in most BMPs, set to 0)
      bmpData.data[1] = 0x00; // Blue
      bmpData.data[2] = 0x00; // Green
      bmpData.data[3] = 0xFF; // Red
    }

    // 3. Encode modified data back into a 24-bit BMP
    // Note: bmp-js currently only encodes to 24-bit BMP format.
    const outputBmpBuffer = bmp.encode({
      data: bmpData.data,
      width: bmpData.width,
      height: bmpData.height
    });

    fs.writeFileSync('output_modified.bmp', outputBmpBuffer.data);
    console.log('BMP decoded, modified top-left pixel, and re-encoded to output_modified.bmp');

  } catch (error) {
    console.error('Error processing BMP:', error.message);
    if (error.code === 'ENOENT' && error.message.includes('bit24.bmp')) {
      console.warn("Please ensure 'bit24.bmp' exists in the current directory to run this example.");
      console.warn("You can create a dummy 24-bit BMP or download one for testing.");
    }
  }
}

processBmp();