{"id":15088,"library":"bmp-ts","title":"BMP Image Encoder/Decoder","description":"bmp-ts is a pure TypeScript library designed for encoding and decoding BMP image files. It currently stands at version 1.0.9, with a release cadence focused on addressing bug fixes and minor enhancements. The library distinguishes itself by offering comprehensive support for all common BMP bit depths, including 1-bit, 4-bit, 8-bit, 16-bit, 24-bit, and 32-bit images. It provides granular control over BMP header properties during the encoding process and offers an optional `toRGBA` conversion during decoding for compatibility with other image processing libraries. While it supports various compression methods for decoding, a key limitation is the lack of compression support during encoding, meaning output files will always be uncompressed.","status":"active","version":"1.0.9","language":"javascript","source_language":"en","source_url":"https://github.com/hipstersmoothie/bmp-ts","tags":["javascript","bmp","1bit","4bit","8bit","16bit","24bit","32bit","encoder","typescript"],"install":[{"cmd":"npm install bmp-ts","lang":"bash","label":"npm"},{"cmd":"yarn add bmp-ts","lang":"bash","label":"yarn"},{"cmd":"pnpm add bmp-ts","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary `bmp` object is a default export, containing `decode` and `encode` methods.","wrong":"import { decode, encode } from 'bmp-ts';","symbol":"bmp","correct":"import bmp from 'bmp-ts';"},{"note":"In CommonJS, the default export must be explicitly accessed via `.default`.","wrong":"const bmp = require('bmp-ts');","symbol":"bmp (CommonJS)","correct":"const bmp = require('bmp-ts').default;"},{"note":"TypeScript types for the decoded image data and header are available for explicit import.","symbol":"BmpData (Type)","correct":"import type { BmpData, BmpHeader } from 'bmp-ts';"}],"quickstart":{"code":"import bmp from 'bmp-ts';\nimport * as fs from 'fs';\n\n// --- Decoding a BMP image ---\n// Ensure 'example.bmp' exists in the execution directory for this to run.\n// You can replace this with any Buffer containing BMP data.\ntry {\n  const bmpBuffer = fs.readFileSync('example.bmp'); \n  const decodedBmpData = bmp.decode(bmpBuffer, { toRGBA: true });\n  console.log('Decoded BMP Header:', decodedBmpData.header);\n  console.log('Decoded BMP Data length:', decodedBmpData.data.length);\n  console.log('Decoded BMP dimensions:', decodedBmpData.header.width, 'x', decodedBmpData.header.height);\n} catch (error) {\n  console.error('Error decoding example.bmp:', error);\n}\n\n// --- Encoding a new BMP image ---\n// Create a dummy image buffer (e.g., a 10x10 white image with alpha)\nconst width = 10;\nconst height = 10;\nconst pixelData = Buffer.alloc(width * height * 4, 255); // RGBA white pixels\n\nconst bmpDataToEncode = {\n  data: pixelData,\n  bitPP: 32, // 32-bit RGBA\n  width: width,\n  height: height\n  // Optional: other BMP header fields can be specified here.\n};\n\nconst encodedRawData = bmp.encode(bmpDataToEncode);\nfs.writeFileSync('./output.bmp', encodedRawData.data);\nconsole.log('Encoded 10x10 32-bit white BMP saved to output.bmp');","lang":"typescript","description":"Demonstrates how to decode an existing BMP file and encode a new BMP image from raw pixel data using `bmp-ts`."},"warnings":[{"fix":"Review the new API usage in the README or package documentation for correct method signatures and object structures.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Be aware that encoded files will be larger. If compressed BMPs are required, external tools or post-processing will be necessary.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always append `.default` when importing `bmp-ts` in CommonJS environments: `const bmp = require('bmp-ts').default;`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to `bmp-ts@1.0.5` or a newer version to ensure correct decoding of all BMP image orientations.","message":"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.","severity":"gotcha","affected_versions":"<1.0.5"},{"fix":"Update to `bmp-ts@1.0.4` or a later version to resolve CommonJS import problems and ensure proper module loading.","message":"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.","severity":"gotcha","affected_versions":"<1.0.4"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"In CommonJS, explicitly use `.default`: `const bmp = require('bmp-ts').default;`.","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.","error":"TypeError: Cannot read properties of undefined (reading 'decode')"},{"fix":"Use `import bmp from 'bmp-ts';` to import the default export directly.","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.","error":"TypeError: bmp.decode is not a function"},{"fix":"Ensure the object passed to `bmp.encode` strictly conforms to the `BmpDataInput` interface, including `data` (Buffer), `width` (number), `height` (number), and `bitPP` (number).","cause":"A TypeScript compilation error indicating that the object passed to `bmp.encode` is missing required properties or has incorrect types.","error":"Property 'data' is missing in type '{ data: Buffer; bitPP: number; width: number; height: number; }' but required in type 'BmpDataInput'."},{"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.","cause":"This is a known issue for bottom-up BMP images in versions prior to `v1.0.5`.","error":"The image data is not correctly decoded and appears flipped vertically."}],"ecosystem":"npm"}