feat: add bmp encoding (#462)

close: #460

Author: EscapedGibbon

package.json

@@ -47,6 +47,7 @@
   "dependencies": {
     "bresenham-zingl": "^0.1.1",
     "colord": "^2.9.3",
+    "fast-bmp": "^2.0.1",
     "fast-jpeg": "^2.0.1",
     "fast-png": "^6.2.0",
     "image-type": "^4.1.0",

src/save/__tests__/encodeBmp.test.ts

@@ -0,0 +1,37 @@
+import { encodeBmp } from '../encodeBmp';
+
+test('encode 5x5 mask', () => {
+  const image = testUtils.createGreyImage([
+    [0, 0, 0, 0, 0],
+    [0, 255, 255, 255, 0],
+    [0, 255, 0, 255, 0],
+    [0, 255, 255, 255, 0],
+    [255, 0, 255, 0, 255],
+  ]);
+  const mask = image.threshold({ threshold: 0.5 });
+  const result = testUtils.loadBuffer('formats/bmp/5x5.bmp');
+  const buffer = encodeBmp(mask).buffer;
+  expect(buffer).toEqual(result.buffer);
+});
+test('encode 6x4 mask', () => {
+  const image = testUtils.createGreyImage([
+    [255, 255, 255, 255, 255, 255],
+    [0, 0, 0, 0, 0, 0],
+    [255, 255, 255, 255, 255, 255],
+    [0, 0, 0, 0, 0, 0],
+  ]);
+  const mask = image.threshold({ threshold: 0.5 });
+  const result = testUtils.loadBuffer('formats/bmp/6x4.bmp');
+  const buffer = encodeBmp(mask).buffer;
+  expect(buffer).toEqual(result.buffer);
+});
+test('encode 10x2 mask', () => {
+  const image = testUtils.createGreyImage([
+    [255, 255, 255, 0, 0, 255, 0, 255, 0, 255],
+    [255, 0, 255, 0, 255, 0, 0, 255, 255, 255],
+  ]);
+  const mask = image.threshold({ threshold: 0.5 });
+  const result = testUtils.loadBuffer('formats/bmp/10x2.bmp');
+  const buffer = encodeBmp(mask).buffer;
+  expect(buffer).toEqual(result.buffer);
+});

src/save/encode.ts

@@ -1,12 +1,15 @@
 import { Image } from '../Image';
+import { Mask } from '../Mask';
 
+import { encodeBmp } from './encodeBmp';
 import { encodeJpeg, EncodeJpegOptions } from './encodeJpeg';
 import { encodePng, EncodePngOptions } from './encodePng';
 
 export const ImageFormat = {
   PNG: 'png',
   JPG: 'jpg',
   JPEG: 'jpeg',
+  BMP: 'bmp',
 } as const;
 // eslint-disable-next-line @typescript-eslint/no-redeclare
 export type ImageFormat = (typeof ImageFormat)[keyof typeof ImageFormat];
@@ -19,7 +22,9 @@ export interface EncodeOptionsJpeg {
   format: 'jpg' | 'jpeg';
   encoderOptions?: EncodeJpegOptions;
 }
-
+export interface EncodeOptionsBmp {
+  format: 'bmp';
+}
 const defaultPng: EncodeOptionsPng = { format: 'png' };
 
 /**
@@ -29,13 +34,15 @@ const defaultPng: EncodeOptionsPng = { format: 'png' };
  * @returns The encoded image.
  */
 export function encode(
-  image: Image,
-  options: EncodeOptionsPng | EncodeOptionsJpeg = defaultPng,
+  image: Image | Mask,
+  options: EncodeOptionsBmp | EncodeOptionsPng | EncodeOptionsJpeg = defaultPng,
 ): Uint8Array {
   if (options.format === 'png') {
     return encodePng(image, options.encoderOptions);
   } else if (options.format === 'jpg' || options.format === 'jpeg') {
     return encodeJpeg(image, options.encoderOptions);
+  } else if (options.format === 'bmp') {
+    return encodeBmp(image);
   } else {
     throw new RangeError(`invalid format: ${options.format}`);
   }

src/save/encodeBmp.ts

@@ -0,0 +1,39 @@
+//@ts-expect-error ts package not ready yet
+import * as bmp from 'fast-bmp';
+
+import { Image } from '../Image';
+import { Mask } from '../Mask';
+
+/**
+ * Creates a BMP buffer from a mask.
+ * @param mask - The mask instance.
+ * @returns The buffer.
+ */
+export function encodeBmp(mask: Mask | Image) {
+  if (!(mask instanceof Mask)) {
+    throw new TypeError('Image bmp encoding is not implemented.');
+  }
+  const compressedBitMask = new Uint8Array(Math.ceil(mask.size / 8));
+  let destIndex = 0;
+  for (let index = 0; index < mask.size; index++) {
+    if (index % 8 === 0 && index !== 0) {
+      destIndex++;
+    }
+    if (destIndex !== compressedBitMask.length - 1) {
+      compressedBitMask[destIndex] <<= 1;
+      compressedBitMask[destIndex] |= mask.getBitByIndex(index);
+    } else {
+      compressedBitMask[destIndex] |= mask.getBitByIndex(index);
+      compressedBitMask[destIndex] <<= 7 - (index % 8);
+    }
+  }
+
+  return bmp.encode({
+    width: mask.width,
+    height: mask.height,
+    components: 1,
+    bitDepth: 1,
+    channels: 1,
+    data: compressedBitMask,
+  });
+}

src/save/encodeJpeg.ts

@@ -1,6 +1,7 @@
 import { encode } from 'jpeg-js';
 
 import { Image } from '../Image';
+import { Mask } from '../Mask';
 
 export interface EncodeJpegOptions {
   /**
@@ -17,11 +18,13 @@ export interface EncodeJpegOptions {
  * @returns The buffer.
  */
 export function encodeJpeg(
-  image: Image,
+  image: Image | Mask,
   options: EncodeJpegOptions = {},
 ): Uint8Array {
   const { quality = 50 } = options;
-
+  if (!(image instanceof Image)) {
+    throw new TypeError('Mask JPG/JPEG encoding is not supported.');
+  }
   if (image.colorModel !== 'RGBA') {
     image = image.convertColor('RGBA');
   }

src/save/encodePng.ts

@@ -1,6 +1,7 @@
 import { encode, PngEncoderOptions } from 'fast-png';
 
 import { Image } from '../Image';
+import { Mask } from '../Mask';
 
 export type EncodePngOptions = PngEncoderOptions;
 
@@ -11,9 +12,23 @@ export type EncodePngOptions = PngEncoderOptions;
  * @returns The buffer.
  */
 export function encodePng(
-  image: Image,
+  image: Image | Mask,
   options?: EncodePngOptions,
 ): Uint8Array {
+  if (!(image instanceof Image)) {
+    throw new TypeError('Mask PNG encoding is not supported.');
+  }
+  if (image.bitDepth !== 8 && image.bitDepth !== 16) {
+    image = image.convertBitDepth(8);
+  }
+  if (
+    image.colorModel !== 'RGB' &&
+    image.colorModel !== 'RGBA' &&
+    image.colorModel !== 'GREY' &&
+    image.colorModel !== 'GREYA'
+  ) {
+    image = image.convertColor('GREY');
+  }
   const { bitDepth: depth, ...other } = image.getRawImage();
   return encode(
     {

src/save/write.ts

@@ -4,7 +4,12 @@ import url from 'node:url';
 
 import { Image, Mask } from '..';
 
-import { encode, EncodeOptionsJpeg, EncodeOptionsPng } from './encode';
+import {
+  encode,
+  EncodeOptionsBmp,
+  EncodeOptionsJpeg,
+  EncodeOptionsPng,
+} from './encode';
 
 export interface WriteOptions {
   /**
@@ -15,6 +20,7 @@ export interface WriteOptions {
 
 export type WriteOptionsPng = WriteOptions & EncodeOptionsPng;
 export type WriteOptionsJpeg = WriteOptions & EncodeOptionsJpeg;
+export type WriteOptionsBmp = WriteOptions & EncodeOptionsBmp;
 
 /**
  * Write an image to the disk.
@@ -56,6 +62,20 @@ export async function write(
   image: Image | Mask,
   options: WriteOptionsJpeg,
 ): Promise<void>;
+
+/**
+ * Write an image to the disk as BMP.
+ * When the `bmp` format is specified, the file's extension doesn't matter.
+ * @param path - Path or file URL where the image should be written.
+ * @param image - Image to save.
+ * @param options - Encode options for bmp images.
+ * @returns A promise that resolves when the image is written.
+ */
+export async function write(
+  path: string | URL,
+  image: Mask,
+  options?: WriteOptionsBmp,
+): Promise<void>;
 /**
  * Asynchronously write an image to the disk.
  * @param path - Path where the image should be written.
@@ -65,7 +85,7 @@ export async function write(
 export async function write(
   path: string | URL,
   image: Image | Mask,
-  options?: WriteOptionsPng | WriteOptionsJpeg | WriteOptions,
+  options?: WriteOptionsBmp | WriteOptionsPng | WriteOptionsJpeg | WriteOptions,
 ): Promise<void> {
   if (typeof path !== 'string') {
     path = url.fileURLToPath(path);
@@ -90,14 +110,11 @@ export async function write(
 export function writeSync(
   path: string | URL,
   image: Image | Mask,
-  options?: WriteOptionsPng | WriteOptionsJpeg | WriteOptions,
+  options?: WriteOptionsBmp | WriteOptionsPng | WriteOptionsJpeg | WriteOptions,
 ): void {
   if (typeof path !== 'string') {
     path = url.fileURLToPath(path);
   }
-  if (image instanceof Mask) {
-    image = image.convertColor('GREY');
-  }
   const toWrite = getDataToWrite(path, image, options);
   if (options?.recursive) {
     const dir = nodePath.dirname(path);
@@ -115,12 +132,17 @@ export function writeSync(
  */
 function getDataToWrite(
   destinationPath: string,
-  image: Image,
-  options?: WriteOptionsPng | WriteOptionsJpeg | WriteOptions,
+  image: Image | Mask,
+  options?: WriteOptionsBmp | WriteOptionsPng | WriteOptionsJpeg | WriteOptions,
 ): Uint8Array {
   if (!options || !('format' in options)) {
     const extension = nodePath.extname(destinationPath).slice(1).toLowerCase();
     if (extension === 'png' || extension === 'jpg' || extension === 'jpeg') {
+      if (image instanceof Mask) {
+        image = image.convertColor('GREY');
+      }
+      return encode(image, { ...options, format: extension });
+    } else if (extension === 'bmp') {
       return encode(image, { ...options, format: extension });
     } else {
       throw new RangeError(

test/TestImagePath.ts

@@ -34,6 +34,9 @@ export type TestImagePath =
   | 'featureMatching/polygons/polygon2.png'
   | 'featureMatching/polygons/polygonRotated10degrees.png'
   | 'featureMatching/polygons/polygonRotated180degrees.png'
+  | 'formats/bmp/10x2.bmp'
+  | 'formats/bmp/6x4.bmp'
+  | 'formats/bmp/5x5.bmp'
   | 'formats/grey6.jpg'
   | 'formats/grey8.png'
   | 'formats/grey12.jpg'