Image To Braille Converter

/**
 * Converts an image into a grid of Braille characters to represent the image as text art.
 * The function processes the image in 2x4 pixel blocks, mapping each block to an 8-dot Braille character.
 *
 * @param {Image} originalImg The original Javascript Image object to be converted.
 * @param {number} [threshold=128] The brightness threshold (0-255) to determine if a dot is "on" or "off". Darker pixels than this value become dots.
 * @param {number} [invert=0] Set to 1 to invert the image's brightness before processing. Useful for dark images on light backgrounds. 0 for normal, 1 for inverted.
 * @param {number} [scale=1] A scaling factor for the image. A smaller scale (e.g., 0.5) results in a smaller output with less detail, while a larger scale (e.g., 2.0) results in a larger, more detailed output.
 * @returns {HTMLElement} A <pre> element containing the Braille character art.
 */
function processImage(originalImg, threshold = 128, invert = 0, scale = 1) {
    // 1. Sanitize and parse parameters
    const numThreshold = Number(threshold);
    const doInvert = Number(invert) === 1;
    const numScale = Math.max(0.01, Number(scale)); // Ensure scale is not zero or negative

    // 2. Setup canvas
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d', {
        willReadFrequently: true
    });

    // 3. Calculate target dimensions based on scale
    // The output character grid size will be (targetWidth / 2) x (targetHeight / 4)
    const scaledWidth = originalImg.width * numScale;
    const scaledHeight = originalImg.height * numScale;

    // Ensure the canvas dimensions are a multiple of 2 (width) and 4 (height)
    // to perfectly fit the 2x4 braille character blocks.
    const targetWidth = Math.floor(scaledWidth / 2) * 2;
    const targetHeight = Math.floor(scaledHeight / 4) * 4;

    // Handle cases where the scaled image is too small
    if (targetWidth < 2 || targetHeight < 4) {
        const errorEl = document.createElement('p');
        errorEl.textContent = 'Image is too small for the selected scale to produce any Braille output. Try increasing the scale.';
        errorEl.style.color = 'red';
        return errorEl;
    }

    canvas.width = targetWidth;
    canvas.height = targetHeight;
    
    // Fill canvas with a white background to handle transparent areas in the source image.
    ctx.fillStyle = 'white';
    ctx.fillRect(0, 0, targetWidth, targetHeight);

    // 4. Draw the image to the canvas to apply scaling and get pixel data
    ctx.drawImage(originalImg, 0, 0, targetWidth, targetHeight);
    const imageData = ctx.getImageData(0, 0, targetWidth, targetHeight);
    const data = imageData.data;

    let brailleString = '';

    // 5. Iterate through the image data in 2x4 pixel blocks
    for (let y = 0; y < targetHeight; y += 4) {
        for (let x = 0; x < targetWidth; x += 2) {

            // This bitmask corresponds to the 8 dots in an 8-dot braille character.
            // A "1" in a bit's position means the dot is "on".
            // Dot 1: 2^0, Dot 2: 2^1, ..., Dot 8: 2^7
            let bitmask = 0;

            // Map pixel positions in the 2x4 block to their corresponding braille dot / bit value
            const dotMap = [
                { dx: 0, dy: 0, bit: 1 },    // Dot 1 (top-left)
                { dx: 0, dy: 1, bit: 2 },    // Dot 2 (mid-left)
                { dx: 0, dy: 2, bit: 4 },    // Dot 3 (bottom-left)
                { dx: 1, dy: 0, bit: 8 },    // Dot 4 (top-right)
                { dx: 1, dy: 1, bit: 16 },   // Dot 5 (mid-right)
                { dx: 1, dy: 2, bit: 32 },   // Dot 6 (bottom-right)
                { dx: 0, dy: 3, bit: 64 },   // Dot 7 (extra bottom-left)
                { dx: 1, dy: 3, bit: 128 },  // Dot 8 (extra bottom-right)
            ];

            for (const dot of dotMap) {
                const px = x + dot.dx;
                const py = y + dot.dy;

                // Calculate the index for the pixel in the ImageData array (R,G,B,A)
                const index = (py * targetWidth + px) * 4;
                const r = data[index];
                const g = data[index + 1];
                const b = data[index + 2];

                // Convert pixel color to grayscale value (0-255)
                let gray = 0.299 * r + 0.587 * g + 0.114 * b;

                // Invert the grayscale value if the 'invert' option is enabled
                if (doInvert) {
                    gray = 255 - gray;
                }

                // If the grayscale value is below the threshold, turn the dot "on"
                // (i.e., add its corresponding bit to the bitmask).
                // This assumes darker colors should form the dots.
                if (gray < numThreshold) {
                    bitmask |= dot.bit;
                }
            }

            // The Unicode Braille Patterns block starts at 0x2800.
            // We add our bitmask to this base to get the code point for the correct character.
            const brailleCharCode = 0x2800 + bitmask;
            brailleString += String.fromCharCode(brailleCharCode);
        }
        brailleString += '\n'; // Add a newline after each row of braille characters
    }

    // 6. Create and style the output element
    const pre = document.createElement('pre');
    pre.textContent = brailleString;

    // Styling is important for the braille characters to form a coherent image
    pre.style.fontFamily = 'monospace';
    pre.style.fontSize = '10px';
    // Line height needs to be tight to connect vertical dots.
    // 'em' is relative to font-size, so this is a good unit.
    pre.style.lineHeight = '0.75em';
    pre.style.letterSpacing = '0';
    pre.style.margin = '0';
    pre.style.padding = '5px';
    pre.style.display = 'inline-block'; // Prevents it from taking full container width
    pre.style.backgroundColor = '#f0f0f0';
    pre.style.border = '1px solid #ccc';
    pre.style.borderRadius = '4px';

    return pre;
}