pbmtoascii

Read a PBM file as input and produce an ASCII output

$ pbmtoascii [path/to/input_file.pbm]

$ pbmtoascii [path/to/input_file.pbm] > [path/to/output_file]

$ pbmtoascii -[1x2|2x4] [path/to/input_file.pbm]

$ pbmtoascii [[-v|-version]]

pbmtoascii [options] [pbmfile]

If pbmfile is not specified, pbmtoascii reads from standard input. Output is always to standard output.

-chars characters
    Specifies the string of characters to use for mapping pixel densities. The first character represents the lightest density, and the last character represents the darkest. The default is ' .:-=+*#%@'.

-invert
    Inverts the black and white representation of the image. Black pixels become white and vice versa, which also inverts the character mapping (e.g., darkest characters for original white areas).

-maxwidth width
    Sets the maximum width of the output ASCII art in characters. The image will be scaled down proportionally to fit this width if necessary.

-maxheight height
    Sets the maximum height of the output ASCII art in lines. The image will be scaled down proportionally to fit this height if necessary.

-compact
    Generates a more compact output by using a 2x1 cell mapping (two pixels wide, one pixel high) instead of the default 2x2. This results in fewer lines but potentially wider output, giving a denser character representation horizontally.

-2x2
    Uses a 2x2 grid of pixels to determine the character. This is the default behavior, providing a balanced resolution.

-8x8
    Uses an 8x8 grid of pixels to determine the character. This option provides a coarser resolution, useful for very large images or when less detail is required. This effectively overrides the default 2x2 character mapping for density calculation.

The pbmtoascii command is a utility from the Netpbm suite that transforms monochrome Portable BitMap (PBM) image files into text-based ASCII art.

It works by analyzing the pixel density within regions of the PBM image and mapping these densities to characters from a predefined or user-specified set. Darker areas of the image are represented by characters that occupy more visual space (e.g., '#', '@'), while lighter areas are represented by sparser characters (e.g., '.', ' ').

This conversion allows graphical images to be viewed in text-only environments, such as terminals, or to be incorporated into text documents. The output is typically directed to standard output, making it easy to pipe to other commands or redirect to a file. pbmtoascii is particularly useful for quick previews of monochrome images or for creating retro-style textual representations.

pbmtoascii strictly operates on Portable BitMap (PBM) format images, which are monochrome (black and white) only. It cannot process grayscale (PGM) or color (PPM/PAM) images directly. If you have a different image format, you must first convert it to PBM using tools like anytopnm or pamtopbm.

The quality of the ASCII art output is inherently limited by the resolution of the input image and the character set used. Very detailed images may appear blocky or lose significant information when converted to ASCII art, especially with coarse character mapping options like -8x8. The visual fidelity is also dependent on the display font and terminal settings.

The command determines which character to use based on the average intensity of a small grid of pixels (a 'cell') in the input PBM image. By default, it uses a 2x2 pixel cell. The brighter the cell, the lighter (closer to the beginning) the character from the -chars string is chosen. The darker the cell, the darker (closer to the end) the character. The -compact, -2x2, and -8x8 options modify the size of this cell and thus the resolution of the output ASCII art.

pbmtoascii is frequently used as part of a pipeline of Netpbm commands. For example, to convert a JPEG image to ASCII art, you might use: djpeg image.jpg | ppmtopbm | pbmtoascii. This piping capability makes it very flexible within shell scripts and command-line workflows, allowing complex image manipulations by chaining simple, single-purpose tools.

pbmtoascii is an integral part of the Netpbm package, a widely-used toolkit for graphics manipulation on Unix-like systems. The Netpbm project originated in 1988 as PBMplus by Jef Poskanzer, and has since undergone continuous development and maintenance by various contributors. pbmtoascii was one of the early utilities, reflecting the toolkit's focus on fundamental image format conversions and transformations. Its continued presence in the Netpbm suite highlights its utility for simple, text-based image representation, a common need in command-line environments and for generating specific visual effects.

pbm(5), netpbm(1), anytopnm(1), pamtopbm(1), pamtoascii(1)