Image To Binary Converter For Optimized Storage

/**
 * Converts an image to a binary (black and white) representation using different modes.
 * The "lossy" mode uses simple thresholding, while the "lossless" mode uses Floyd-Steinberg
 * dithering to create a higher quality monochrome image that better preserves details and tones.
 * Despite the name "lossless", dithering is still a lossy process in terms of original color data,
 * but it provides a superior visual representation compared to simple thresholding.
 *
 * @param {Image} originalImg The original JavaScript Image object.
 * @param {string} mode The conversion mode. Can be 'lossy' (simple threshold) or 'lossless' (dithering). Defaults to 'lossy'.
 * @param {number} binaryThreshold The brightness threshold (0-255) to determine black or white. Defaults to 128.
 * @returns {HTMLCanvasElement} A canvas element displaying the binary image.
 */
async function processImage(originalImg, mode = 'lossy', binaryThreshold = 128) {
  // Create a canvas and get its 2D context.
  const canvas = document.createElement('canvas');
  const ctx = canvas.getContext('2d');

  // Set canvas dimensions to match the original image.
  const w = originalImg.naturalWidth;
  const h = originalImg.naturalHeight;
  canvas.width = w;
  canvas.height = h;

  // Draw the image onto the canvas to access its pixel data.
  ctx.drawImage(originalImg, 0, 0, w, h);
  const imageData = ctx.getImageData(0, 0, w, h);
  const data = imageData.data;

  // Sanitize input parameters
  mode = (mode === 'lossless' || mode === 'lossy') ? mode : 'lossy';
  binaryThreshold = typeof binaryThreshold === 'number' ? Math.max(0, Math.min(255, binaryThreshold)) : 128;


  if (mode === 'lossy') {
    // Lossy Mode: Simple Thresholding
    // Each pixel is converted to black or white based on a simple brightness threshold.
    // This is fast but can lose significant detail.
    for (let i = 0; i < data.length; i += 4) {
      // Calculate grayscale value using the luminance formula for better results
      const gray = data[i] * 0.299 + data[i + 1] * 0.587 + data[i + 2] * 0.114;
      const value = gray < binaryThreshold ? 0 : 255;
      data[i] = value;
      data[i + 1] = value;
      data[i + 2] = value;
      // Alpha channel (data[i + 3]) is left untouched (fully opaque).
    }
  } else {
    // "Lossless" Mode: Floyd-Steinberg Dithering
    // This creates the illusion of more gray levels by diffusing the quantization error
    // of each pixel to its neighbors. It produces a much more detailed result.

    // 1. Create a floating-point array to hold the grayscale values and propagated errors.
    const grayData = new Float32Array(w * h);
    for (let i = 0; i < data.length; i += 4) {
      const gray = data[i] * 0.299 + data[i + 1] * 0.587 + data[i + 2] * 0.114;
      grayData[i / 4] = gray;
    }

    // 2. Process each pixel and diffuse the error.
    for (let y = 0; y < h; y++) {
      for (let x = 0; x < w; x++) {
        const index = y * w + x;
        const oldPixel = grayData[index];
        const newPixel = oldPixel < binaryThreshold ? 0 : 255;
        const quantError = oldPixel - newPixel;

        // Update the original image data with the new black or white pixel.
        data[index * 4] = newPixel;
        data[index * 4 + 1] = newPixel;
        data[index * 4 + 2] = newPixel;

        // Distribute the error to neighboring pixels that haven't been processed yet.
        // Right
        if (x + 1 < w) {
          grayData[y * w + (x + 1)] += quantError * 7 / 16;
        }
        // Bottom-left
        if (x - 1 >= 0 && y + 1 < h) {
          grayData[(y + 1) * w + (x - 1)] += quantError * 3 / 16;
        }
        // Bottom
        if (y + 1 < h) {
          grayData[(y + 1) * w + x] += quantError * 5 / 16;
        }
        // Bottom-right
        if (x + 1 < w && y + 1 < h) {
          grayData[(y + 1) * w + (x + 1)] += quantError * 1 / 16;
        }
      }
    }
  }

  // Put the modified image data back onto the canvas.
  ctx.putImageData(imageData, 0, 0);

  // Return the canvas element.
  return canvas;
}