Photo Black And White Floyd-Steinberg Dithering For Acrylic Engraving

/**
 * Converts an image to a 1-bit black and white dithered version using the Floyd-Steinberg algorithm,
 * suitable for laser engraving on materials like acrylic.
 *
 * @param {HTMLImageElement} originalImg The original image object to process.
 * @returns {HTMLCanvasElement} A new canvas element containing the black and white dithered image.
 */
function processImage(originalImg) {
    // 1. Create a canvas and draw the original image onto it.
    const canvas = document.createElement('canvas');
    // Using { willReadFrequently: true } can optimize performance for repeated getImageData calls.
    const ctx = canvas.getContext('2d', { willReadFrequently: true });
    const width = originalImg.width;
    const height = originalImg.height;
    canvas.width = width;
    canvas.height = height;

    ctx.drawImage(originalImg, 0, 0, width, height);

    // 2. Get image data and prepare a grayscale buffer.
    const imageData = ctx.getImageData(0, 0, width, height);
    const data = imageData.data;

    // We use a Float32Array to store grayscale values with high precision,
    // which is important for accumulating the diffused error accurately.
    const grayData = new Float32Array(width * height);

    for (let i = 0; i < data.length; i += 4) {
        const r = data[i];
        const g = data[i + 1];
        const b = data[i + 2];
        // Convert to grayscale using the standard luminance formula (Rec. 601).
        const grayValue = 0.299 * r + 0.587 * g + 0.114 * b;
        grayData[i / 4] = grayValue;
    }

    // 3. Apply the Floyd-Steinberg dithering algorithm.
    for (let y = 0; y < height; y++) {
        for (let x = 0; x < width; x++) {
            const index = y * width + x;
            const oldPixel = grayData[index];
            
            // Quantize the pixel to the nearest color in our 1-bit palette (black=0, white=255).
            const newPixel = oldPixel < 128 ? 0 : 255;
            
            // Set the current pixel to its new black or white value.
            grayData[index] = newPixel;
            
            // Calculate the quantization error.
            const quantError = oldPixel - newPixel;

            // Diffuse the error to neighboring pixels that have not yet been processed.
            // Check boundaries to avoid writing outside the image buffer.
            
            // To the right:
            if (x + 1 < width) {
                grayData[index + 1] += quantError * (7 / 16);
            }
            // Below and to the left:
            if (y + 1 < height && x - 1 >= 0) {
                grayData[index + width - 1] += quantError * (3 / 16);
            }
            // Directly below:
            if (y + 1 < height) {
                grayData[index + width] += quantError * (5 / 16);
            }
            // Below and to the right:
            if (y + 1 < height && x + 1 < width) {
                grayData[index + width + 1] += quantError * (1 / 16);
            }
        }
    }

    // 4. Write the final 1-bit pixel data back to the canvas.
    for (let i = 0; i < grayData.length; i++) {
        const finalValue = grayData[i];
        const dataIndex = i * 4;
        data[dataIndex] = finalValue;     // Red
        data[dataIndex + 1] = finalValue; // Green
        data[dataIndex + 2] = finalValue; // Blue
        data[dataIndex + 3] = 255;        // Alpha (fully opaque)
    }

    ctx.putImageData(imageData, 0, 0);

    return canvas;
}