Programmatic ASCII Art Generation

Building an ASCII Art Generator from Scratch

Understanding how to programmatically generate ASCII art gives you full control over the conversion process. This guide walks through implementations in JavaScript (browser) and Python.

JavaScript Implementation (Browser)

The browser Canvas API provides direct access to pixel data:

function imageToAscii(imageSrc, width, charSet) {
  return new Promise((resolve) => {
    const img = new Image();
    img.onload = () => {
      const canvas = document.createElement('canvas');
      const ctx = canvas.getContext('2d');
      canvas.width = img.width;
      canvas.height = img.height;
      ctx.drawImage(img, 0, 0);

      const data = ctx.getImageData(0, 0, img.width, img.height);
      const cellW = img.width / width;
      const cellH = cellW * 2; // Aspect ratio correction
      const height = Math.floor(img.height / cellH);

      let result = '';
      for (let y = 0; y < height; y++) {
        for (let x = 0; x < width; x++) {
          const brightness = sampleCell(data, x, y, cellW, cellH);
          const charIdx = Math.floor(brightness * (charSet.length - 1));
          result += charSet[charIdx];
        }
        result += '\n';
      }
      resolve(result);
    };
    img.src = imageSrc;
  });
}

function sampleCell(imageData, cx, cy, cellW, cellH) {
  const { data, width } = imageData;
  let total = 0, count = 0;
  const startX = Math.floor(cx * cellW);
  const startY = Math.floor(cy * cellH);
  const endX = Math.min(Math.floor((cx + 1) * cellW), width);
  const endY = Math.min(Math.floor((cy + 1) * cellH), imageData.height);

  for (let y = startY; y < endY; y++) {
    for (let x = startX; x < endX; x++) {
      const idx = (y * width + x) * 4;
      // ITU-R BT.709 luminance
      total += 0.2126 * data[idx] + 0.7152 * data[idx+1] + 0.0722 * data[idx+2];
      count++;
    }
  }
  return count > 0 ? (total / count) / 255 : 1;
}

Python Implementation (Pillow)

from PIL import Image

def image_to_ascii(path, width=80, chars='@#%*+=-:. '):
    img = Image.open(path).convert('L')  # Grayscale
    aspect = img.height / img.width
    height = int(width * aspect * 0.5)   # 0.5 for char aspect ratio
    img = img.resize((width, height))

    pixels = img.getdata()
    result = ''
    for i, pixel in enumerate(pixels):
        brightness = pixel / 255
        char_idx = int(brightness * (len(chars) - 1))
        result += chars[char_idx]
        if (i + 1) % width == 0:
            result += '\n'
    return result

Key Implementation Details

1. Aspect ratio correction: Monospace characters are ~2x taller than wide. Sample cells with a 1:2 width:height ratio.
2. Luminance formula: Use BT.709 weights (0.2126, 0.7152, 0.0722) rather than simple averaging.
3. Cell averaging: Average all pixels in a cell rather than sampling a single pixel to reduce noise.
4. Edge handling: Ensure sampling does not read beyond image boundaries.
5. Performance: For large images, consider downscaling first rather than iterating over every pixel in large cells.

Extending the Generator

• Add color support: Store average RGB per cell and wrap output in colored spans
• Add dithering: Implement Floyd-Steinberg error diffusion for smoother gradients
• Add edge detection: Run a Sobel filter to produce outline-style art
• Add custom fonts: Measure actual character densities for the target font