Image Gradient Map Vocoder Tool

/**
 * Applies a gradient map to an image, quantizing the colors into bands,
 * similar to a vocoder's effect on audio. The brightness of each pixel
 * in the original image determines which color from the gradient is used.
 *
 * @param {Image} originalImg The original JavaScript Image object.
 * @param {string} gradientColors A comma-separated string of CSS colors for the gradient (e.g., "#ff0000,yellow,#0000ff").
 * @param {number} bands The number of discrete color bands to use for the effect (posterization level). Higher numbers are smoother.
 * @returns {Promise<HTMLCanvasElement>} A canvas element with the rendered result.
 */
async function processImage(originalImg, gradientColors = '#00d4ff,#003540,#ffc800,#ff3c00,#9e0000', bands = 8) {

    // 1. Set up the main canvas
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d', { willReadFrequently: true });
    
    // Ensure the image is loaded before getting its dimensions
    await originalImg.decode();
    canvas.width = originalImg.naturalWidth;
    canvas.height = originalImg.naturalHeight;

    // 2. Create the gradient lookup table
    // This is a small 256x1 canvas that we draw the full gradient onto.
    // We can then read its pixel data to easily map a brightness value (0-255) to a color.
    const gradCanvas = document.createElement('canvas');
    gradCanvas.width = 256;
    gradCanvas.height = 1;
    const gradCtx = gradCanvas.getContext('2d');

    const gradient = gradCtx.createLinearGradient(0, 0, 256, 0);
    const colors = gradientColors.split(',').map(c => c.trim()).filter(Boolean);

    if (colors.length === 0) {
        colors.push('#000000', '#ffffff'); // Fallback to black and white
    } else if (colors.length === 1) {
        colors.push(colors[0]); // A single color means a solid map
    }
    
    colors.forEach((color, i) => {
        const position = i / (colors.length - 1);
        gradient.addColorStop(position, color);
    });

    gradCtx.fillStyle = gradient;
    gradCtx.fillRect(0, 0, 256, 1);
    const gradientMap = gradCtx.getImageData(0, 0, 256, 1).data;

    // 3. Process the source image
    ctx.drawImage(originalImg, 0, 0);
    const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
    const data = imageData.data;
    const numBands = Math.max(2, Math.min(256, parseInt(bands, 10) || 8));

    for (let i = 0; i < data.length; i += 4) {
        const r = data[i];
        const g = data[i + 1];
        const b = data[i + 2];

        // Calculate luminance (perceived brightness)
        const luminance = Math.round(0.299 * r + 0.587 * g + 0.114 * b);

        // Apply "vocoder" banding/quantization effect.
        // First, find which band the luminance falls into (from 0 to numBands-1).
        const bandIndex = Math.floor((luminance / 256) * numBands);
        
        // Then, map that band index to an index on our 256-color gradient map.
        // This ensures that only `numBands` distinct colors from the gradient are ever used.
        const mapIndex = Math.min(255, Math.floor(bandIndex * (255 / (numBands - 1))));
        
        // Look up the new color from our pre-calculated gradient map.
        const newR = gradientMap[mapIndex * 4];
        const newG = gradientMap[mapIndex * 4 + 1];
        const newB = gradientMap[mapIndex * 4 + 2];

        // Replace the original pixel's color.
        data[i] = newR;
        data[i + 1] = newG;
        data[i + 2] = newB;
        // The alpha channel (data[i + 3]) is left untouched.
    }

    // 4. Write the modified pixel data back to the canvas and return it.
    ctx.putImageData(imageData, 0, 0);
    return canvas;
}