asciitopgm

Read ASCII data as input and produce a PGM image with pixel values that are an approximation of the "brightness" of the ASCII characters

$ asciitopgm [path/to/input_file] > [path/to/output_file.pgm]

$ asciitopgm [[-v|-version]]

asciitopgm [-text] [-expand] [-compact] [-landscape] [-width=cols] [-height=rows] [ascii_file]

-text
    Inverts the graymap, effectively swapping dark characters with white and light characters with black. This is useful when processing 'text mode' programs or displays where non-space characters are drawn as the foreground.

-expand
    Renders each ASCII character as a larger 16x16 pixel block, resulting in a more zoomed-in or blocky appearance.

-compact
    Renders each ASCII character as a smaller 4x8 pixel block, producing a more compact and potentially harder-to-read image.

-landscape
    Rotates the entire output image 90 degrees clockwise. This can be useful for converting ASCII art that is wider than it is tall into a landscape image.

-width=cols
    Specifies the desired width of the output image in character columns. The image will be scaled horizontally to fit this number of character positions.

-height=rows
    Specifies the desired height of the output image in character rows. The image will be scaled vertically to fit this number of character positions.

ascii_file
    The path to the input ASCII graphics file. If this argument is omitted, asciitopgm will read its input from standard input (stdin).

asciitopgm is a Netpbm command-line utility designed to convert ASCII graphics files into Portable Graymap (PGM) images.

It reads plain ASCII text (either from a specified file or standard input) and renders each character as a block of pixels in the output PGM. By default, characters are mapped to 8x16 pixel blocks, but options are available for 4x8 (with -compact) or 16x16 (with -expand) pixel representations. The utility assigns different shades of gray to various ASCII characters; for instance, dense characters like '@' or '#' typically appear darker, while a space (' ') is rendered as white.

This tool is particularly useful for creating graphical representations of ASCII art, source code, or any plain text for documentation, presentations, or web content. The resulting PGM image can then be viewed directly or easily converted to other image formats using other Netpbm tools.

asciitopgm is a simple utility focused on direct character-to-pixel mapping. It does not perform advanced font rendering, text layout, or support variable-width fonts. It treats each character as a fixed-size block, which might not be suitable for complex typographic needs. It's best suited for character-based art or plain text where visual fidelity to a monospace terminal is desired.

The command expects plain ASCII text as input, typically structured as 'ASCII art' or simple text files. The output is always in the PGM (Portable Graymap) format, a simple, uncompressed image format within the Netpbm suite, which can be easily converted to other popular image formats (like PNG, JPEG) using other Netpbm tools like pgmtoppm and then ppmtojpeg/ppmtopng.

The conversion logic maps different ASCII characters to varying shades of gray. Generally, characters that visually occupy more space or are 'denser' (e.g., '@', '#', '%', '&') are rendered as darker pixels, while characters like ' ' (space), '.', or '-' are rendered as lighter pixels. This mapping creates a visual gradient that mimics the original ASCII art's apparent density.

asciitopgm is an integral part of the Netpbm project, a comprehensive toolkit for manipulating graphic images. Netpbm originated from the `pbmplus` package developed in the late 1980s and early 1990s. The philosophy behind Netpbm, and thus asciitopgm, is to provide small, specialized, and composable command-line tools. This design allows users to chain commands together using pipes to achieve complex image processing tasks, fitting the Unix philosophy of 'do one thing and do it well'. asciitopgm's development and continued inclusion reflect the enduring utility of converting text-based content into standard graphical formats.

pgm(5), ppmtoascii(1), pnm(5), netpbm(1)