Image To Dingbat Symbol Art Converter

async function processImage(originalImg, symbols = "●★♠♥♦♪♫☀☁☂✔✘❤☘⚘⚙⚓⚡", cellSize = 12, backgroundColor = "white", symbolRenderColor = "black", invertMapping = 0, fontSizeRatio = 0.8) {
    // Validate and sanitize inputs
    cellSize = Math.max(1, Number(cellSize) || 12);
    fontSizeRatio = Math.max(0.1, Math.min(2.0, Number(fontSizeRatio) || 0.8)); // Font size relative to cell, capped.
    invertMapping = Number(invertMapping) === 1 ? 1 : 0; // Ensure it's 0 or 1
    symbols = String(symbols); // Ensure symbols is a string

    const numSymbols = symbols.length;

    const outputCanvas = document.createElement('canvas');
    const outputCtx = outputCanvas.getContext('2d');

    // Determine grid dimensions based on original image size and cell size
    // Ensure at least one cell column/row even if image is smaller than cellSize or zero-sized
    const numCols = Math.max(1, Math.floor(originalImg.width / cellSize));
    const numRows = Math.max(1, Math.floor(originalImg.height / cellSize));

    outputCanvas.width = numCols * cellSize;
    outputCanvas.height = numRows * cellSize;

    // Draw background color first
    outputCtx.fillStyle = backgroundColor;
    outputCtx.fillRect(0, 0, outputCanvas.width, outputCanvas.height);

    // If no symbols are provided or image has no dimensions, return canvas with only background
    if (numSymbols === 0 || originalImg.width === 0 || originalImg.height === 0) {
        if (numSymbols === 0) {
            console.warn("Image To Dingbat Symbol Art Converter: No symbols provided. Returning canvas with background only.");
        }
        if (originalImg.width === 0 || originalImg.height === 0) {
            console.warn("Image To Dingbat Symbol Art Converter: Input image has zero width or height. Returning canvas with background only.");
        }
        return outputCanvas;
    }
    
    // Create a small temporary canvas to draw a scaled-down version of the image.
    // This scaled-down version will be used for sampling pixel colors efficiently.
    const samplingCanvas = document.createElement('canvas');
    const samplingCtx = samplingCanvas.getContext('2d');
    samplingCanvas.width = numCols;
    samplingCanvas.height = numRows;

    // It's good practice to ensure image smoothing is on for better quality downscaling,
    // though it's typically enabled by default in modern browsers.
    // samplingCtx.imageSmoothingEnabled = true; 
    // samplingCtx.imageSmoothingQuality = "high"; // "low", "medium", "high" - browser support varies

    // Draw the original image onto the small sampling canvas.
    // This effectively scales the image down to the number of symbol cells.
    samplingCtx.drawImage(originalImg, 0, 0, numCols, numRows);

    // Setup text properties for drawing symbols on the output canvas
    const actualFontSize = cellSize * fontSizeRatio;
    outputCtx.font = `${actualFontSize}px sans-serif`; // Using a generic font family for broad Unicode symbol support
    outputCtx.textAlign = 'center';
    outputCtx.textBaseline = 'middle';

    // Iterate over each cell in the grid
    for (let r = 0; r < numRows; r++) {
        for (let c = 0; c < numCols; c++) {
            // Get the color data of the corresponding pixel from the sampling canvas
            const imageData = samplingCtx.getImageData(c, r, 1, 1);
            const data = imageData.data; // [R, G, B, A]
            
            const R_val = data[0];
            const G_val = data[1];
            const B_val = data[2];
            // const A_val = data[3]; // Alpha is available but not used in brightness calculation here

            // Calculate brightness (luminance) of the pixel.
            // Using standard NTSC conversion formula. Range: 0 (black) to 255 (white).
            const brightness = 0.299 * R_val + 0.587 * G_val + 0.114 * B_val;

            // Normalize brightness to a factor between 0.0 and 1.0
            let brightnessFactor = brightness / 255.0;

            // Invert mapping if requested:
            // Default: dark areas of image use symbols from start of 'symbols' string.
            // Inverted: light areas of image use symbols from start of 'symbols' string.
            if (invertMapping === 1) {
                brightnessFactor = 1.0 - brightnessFactor;
            }
            
            // Map the brightness factor to an index in the 'symbols' string
            let symbolIdx = Math.floor(brightnessFactor * numSymbols);
            // Clamp the index to be within the valid range [0, numSymbols - 1]
            // This handles the case where brightnessFactor is 1.0, making symbolIdx equal to numSymbols.
            symbolIdx = Math.min(symbolIdx, numSymbols - 1);
            
            const selectedSymbol = symbols[symbolIdx];
            
            // Determine the color for rendering the symbol
            if (symbolRenderColor.toLowerCase() === "average") {
                // Use the average color of the cell (which is R_val, G_val, B_val from the sampled pixel)
                outputCtx.fillStyle = `rgb(${R_val}, ${G_val}, ${B_val})`;
            } else {
                // Use the fixed color specified in symbolRenderColor parameter
                outputCtx.fillStyle = symbolRenderColor;
            }
            
            // Calculate the center coordinates of the current cell to draw the symbol
            const cellCenterX = c * cellSize + cellSize / 2;
            const cellCenterY = r * cellSize + cellSize / 2;

            // Draw the selected symbol
            outputCtx.fillText(selectedSymbol, cellCenterX, cellCenterY);
        }
    }
    
    return outputCanvas;
}