ppmtoascii

Convert a PPM image to an ASCII image, combining an area of 1x2 pixels into a character

$ ppmtoascii [path/to/input.ppm] > [path/to/output.txt]

$ ppmtoascii -2x4 [path/to/input.ppm] > [path/to/output.txt]

ppmtoascii [-chars characters] [-invert] [-maxwidth width] [-maxheight height] [-monochrome] [-verbose] [ppmfile]

-chars characters
    Specifies the sequence of ASCII characters to use, ordered from darkest to brightest. For example, " .:-=+*#%@".

-invert
    Inverts the character mapping, so dark pixels are represented by lighter characters and vice-versa.

-maxwidth width
    Scales the output ASCII art to a maximum specified column width.

-maxheight height
    Scales the output ASCII art to a maximum specified row height.

-monochrome
    Uses only two characters (space and '#') for black and white representation, ignoring other character set options.

-verbose
    Prints progress and debugging information to standard error during processing.

ppmfile
    The input image file in PPM, PGM, or PBM format. If omitted, ppmtoascii reads from standard input.

ppmtoascii is a utility from the Netpbm suite that transforms a raster image into text-based ASCII art. It reads images in PPM (Portable Pixmap) format, but can also handle PGM (Portable Graymap) and PBM (Portable Bitmap). The conversion process involves mapping the brightness level of each pixel to a corresponding ASCII character. Typically, a sequence of characters from darkest to brightest (e.g., ' ', '.', ':', '@') is used to represent the various shades, effectively rendering the image using text characters.

This command is particularly useful for viewing images in text-only environments, creating stylized text representations, or for educational purposes demonstrating image processing concepts. Users can customize the character set used for the conversion and scale the output dimensions to fit terminal constraints or specific display needs.

ASCII art inherently has significantly lower resolution and color depth compared to the original image, as it converts all color information into luminance values. The visual quality of the output depends heavily on the terminal font, line spacing, and the chosen character set. Scaling operations can sometimes distort the aspect ratio if not applied carefully, especially when only one dimension (maxwidth or maxheight) is specified.

While named ppmtoascii, it can directly process PGM and PBM files in addition to PPM. For other image formats (like JPEG, PNG, GIF), they must first be converted to a Netpbm format using specialized tools such as jpegtopnm, pngtopnm, or anytopnm, and then piped as input. For example: jpegtopnm image.jpg | ppmtoascii.

By default, ppmtoascii sends its ASCII art output to standard output (stdout). This makes it straightforward to redirect the output to a file (e.g., ppmtoascii image.ppm > image.txt), or to pipe it to another command for further processing or viewing (e.g., ppmtoascii image.ppm | less or ppmtoascii image.ppm | lp).

ppmtoascii is a core utility within the Netpbm project, which originated from Jef Poskanzer's Portable Bitmap (PBM) tools in the late 1980s. The Netpbm toolkit is renowned for its modular design, allowing simple utilities to be chained together using Unix pipes. ppmtoascii exemplifies this philosophy, focusing on the singular task of converting images to ASCII art, making it a reliable and widely adopted tool for text-based image representation over decades.

netpbm(1), anytopnm(1), jpegtopnm(1), pngtopnm(1), asciiview(1), jp2a(1)