Image AI Alphabet Translator

/**
 * Translates an image into a visual representation using a customizable "AI alphabet" character set.
 * This is achieved by mapping the brightness of image regions to characters.
 *
 * @param {Image} originalImg The original javascript Image object to process.
 * @param {number} resolution The size in pixels of each square block to analyze. A smaller number means more detail and more characters. Default is 8.
 * @param {string} fontColor The color of the characters in a CSS color format (e.g., '#00FF41', 'lime', 'rgb(0,255,65)'). Default is a matrix green.
 * @param {string} backgroundColor The background color of the output canvas. Default is black.
 * @param {string} characterSet A string of characters used for the brightness mapping, from darkest to brightest.
 * @param {string} invert A string ('true' or 'false') to determine if the brightness mapping should be inverted (dark areas get bright characters). Default is 'false'.
 * @param {string} fontFamily A web-safe font family to use for the characters. Monospaced fonts work best.
 * @returns {HTMLCanvasElement} A new canvas element with the "translated" image.
 */
function processImage(originalImg, resolution = 8, fontColor = '#00FF41', backgroundColor = '#000000', characterSet = ' ·∙∶+*#█', invert = 'false', fontFamily = 'monospace') {
  // --- 1. Parameter validation and setup ---
  const blockSize = Math.max(1, Number(resolution));
  const shouldInvert = invert.toString().toLowerCase() === 'true';

  // --- 2. Create the output canvas and context ---
  const canvas = document.createElement('canvas');
  const ctx = canvas.getContext('2d');
  canvas.width = originalImg.width;
  canvas.height = originalImg.height;

  // --- 3. Create a temporary canvas for image data sampling ---
  // This helps avoid issues with tainted canvases and provides a clean workspace.
  const tempCanvas = document.createElement('canvas');
  tempCanvas.width = originalImg.width;
  tempCanvas.height = originalImg.height;
  const tempCtx = tempCanvas.getContext('2d', {
    willReadFrequently: true
  });
  tempCtx.drawImage(originalImg, 0, 0);

  // --- 4. Prepare the output canvas for drawing ---
  ctx.fillStyle = backgroundColor;
  ctx.fillRect(0, 0, canvas.width, canvas.height);

  ctx.fillStyle = fontColor;
  ctx.font = `${blockSize}px ${fontFamily}`;
  ctx.textAlign = 'center';
  ctx.textBaseline = 'middle';

  // --- 5. Process the image in blocks ---
  const numCols = Math.ceil(canvas.width / blockSize);
  const numRows = Math.ceil(canvas.height / blockSize);

  for (let y = 0; y < numRows; y++) {
    for (let x = 0; x < numCols; x++) {
      const startX = x * blockSize;
      const startY = y * blockSize;

      // Ensure the block dimensions do not exceed the image boundaries
      const blockWidth = Math.min(blockSize, canvas.width - startX);
      const blockHeight = Math.min(blockSize, canvas.height - startY);

      if (blockWidth <= 0 || blockHeight <= 0) continue;

      // Get pixel data for the current block
      const imageData = tempCtx.getImageData(startX, startY, blockWidth, blockHeight);
      const data = imageData.data;
      let totalBrightness = 0;
      let pixelCount = 0;

      // Calculate the average brightness of the block
      for (let i = 0; i < data.length; i += 4) {
        // Only consider pixels that are not fully transparent
        if (data[i + 3] > 0) {
          const r = data[i];
          const g = data[i + 1];
          const b = data[i + 2];
          // Use the luminosity formula for a more accurate grayscale representation
          const brightness = 0.2126 * r + 0.7152 * g + 0.0722 * b;
          totalBrightness += brightness;
          pixelCount++;
        }
      }

      const avgBrightness = pixelCount > 0 ? totalBrightness / pixelCount : 0;
      const finalBrightness = shouldInvert ? 255 - avgBrightness : avgBrightness;

      // Map the brightness (0-255) to a character from the character set
      const charIndex = Math.floor((finalBrightness / 255) * (characterSet.length - 1));
      const char = characterSet.charAt(charIndex);

      // Draw the character in the center of the block
      const drawX = startX + blockWidth / 2;
      const drawY = startY + blockHeight / 2;
      ctx.fillText(char, drawX, drawY);
    }
  }

  // --- 6. Return the final canvas element ---
  return canvas;
}