Image Text Alphabet Copier

/**
 * "Copies" an image by converting it into text art using a specified alphabet.
 * Each part of the image is represented by a character from the alphabet that
 * best corresponds to its brightness.
 *
 * @param {HTMLImageElement} originalImg The original image element to process.
 * @param {string} [alphabet=' .,:;+*?%S#@'] A string of characters ordered from lightest visual weight to heaviest. Used to represent image brightness.
 * @param {number} [fontSize=8] The font size of the characters, which also determines the resolution (cell size) of the text art.
 * @param {string} [fontColor='#000000'] The color of the text characters.
 * @param {string} [backgroundColor='#ffffff'] The background color of the output canvas.
 * @returns {HTMLCanvasElement} A canvas element displaying the generated text art.
 */
function processImage(originalImg, alphabet = ' .,:;+*?%S#@', fontSize = 8, fontColor = '#000000', backgroundColor = '#ffffff') {
    // 1. Create canvases: one for the source image to read pixel data from,
    // and one for the final result.
    const resultCanvas = document.createElement('canvas');
    const sourceCanvas = document.createElement('canvas');
    const resultCtx = resultCanvas.getContext('2d');
    // Add a performance hint for frequent pixel reading.
    const sourceCtx = sourceCanvas.getContext('2d', {
        willReadFrequently: true
    });

    // Use a default alphabet if the provided one is invalid or empty.
    if (!alphabet || alphabet.length === 0) {
        alphabet = ' .,:;+*?%S#@';
    }

    // 2. Set canvas dimensions to the intrinsic size of the original image.
    const imgWidth = originalImg.naturalWidth;
    const imgHeight = originalImg.naturalHeight;
    resultCanvas.width = imgWidth;
    resultCanvas.height = imgHeight;
    sourceCanvas.width = imgWidth;
    sourceCanvas.height = imgHeight;

    // 3. Prepare the result canvas.
    // Fill with the specified background color.
    resultCtx.fillStyle = backgroundColor;
    resultCtx.fillRect(0, 0, resultCanvas.width, resultCanvas.height);

    // Set font properties for drawing the characters.
    // A monospace font is crucial for maintaining a consistent grid.
    resultCtx.fillStyle = fontColor;
    resultCtx.font = `${fontSize}px 'Courier New', Courier, monospace`;
    resultCtx.textAlign = 'center';
    resultCtx.textBaseline = 'middle';

    // 4. Draw the original image onto the source canvas to enable pixel data access.
    sourceCtx.drawImage(originalImg, 0, 0);

    // 5. Define the grid size. Each character will represent a square cell of pixels.
    // The cell size is determined by the font size.
    const cellSize = Math.max(1, Math.floor(fontSize));
    const cols = Math.floor(imgWidth / cellSize);
    const rows = Math.floor(imgHeight / cellSize);

    // 6. Iterate over each cell of the grid.
    for (let y = 0; y < rows; y++) {
        for (let x = 0; x < cols; x++) {
            // Define the rectangular region of the source image for the current cell.
            const startX = x * cellSize;
            const startY = y * cellSize;

            // Extract the pixel data for this cell from the source canvas.
            const imageData = sourceCtx.getImageData(startX, startY, cellSize, cellSize);
            const data = imageData.data;

            // Calculate the average brightness of the cell.
            let totalBrightness = 0;
            const pixelCount = data.length / 4;

            for (let i = 0; i < data.length; i += 4) {
                const r = data[i];
                const g = data[i + 1];
                const b = data[i + 2];
                // Using the standard luminosity formula for grayscale conversion (perceptual brightness).
                const brightness = 0.299 * r + 0.587 * g + 0.114 * b;
                totalBrightness += brightness;
            }

            const avgBrightness = totalBrightness / pixelCount;

            // Map the average brightness to a character from the alphabet.
            // The alphabet is assumed to be ordered from lightest to darkest character.
            // A dark area in the image (low brightness) should map to a dark/dense character (high index).
            const darkness = (255 - avgBrightness) / 255; // Normalize darkness to a 0.0 - 1.0 scale
            const charIndex = Math.min(alphabet.length - 1, Math.floor(darkness * alphabet.length));
            const char = alphabet[charIndex];

            // 7. Draw the chosen character onto the result canvas, centered within its cell.
            if (char) {
                const drawX = startX + cellSize / 2;
                const drawY = startY + cellSize / 2;
                resultCtx.fillText(char, drawX, drawY);
            }
        }
    }

    // 8. Return the final canvas element containing the text art.
    return resultCanvas;
}