ppmtoterm

Convert a PPM image to an ANSI ISO 6429 ASCII image, mapping each pixel to an individual character

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

ppmtoterm [-256colors | -ansi] [-80col] [-bold] [-width N] [-height N] [-gamma F] [-truecolors | -notruecolors] [-maxcolors N] [-char C] [-block] [-dither] [-map file] [-rows N] [-cols N] [-compress] [-noblank] [-fontwidth N] [-fontheight N] [-font file] [-output file] [-help] [-version] [PPMfile]

-256colors
    Uses 256-color ANSI sequences for output.

-ansi
    Uses standard 8-color ANSI sequences (default mode).

-80col
    Forces output to an 80-column width.

-bold
    Employs bold attributes for brighter color simulation.

-width N
    Scales the image to N characters wide.

-height N
    Scales the image to N characters high.

-gamma F
    Applies a gamma correction factor F to colors.

-truecolors
    Utilizes 24-bit true color ANSI sequences (terminal dependent).

-notruecolors
    Disables 24-bit true color output (default).

-maxcolors N
    Limits the number of colors used in the output to N.

-char C
    Specifies character C to use for drawing pixels.

-block
    Uses a block character (e.g., U+2588) for solid pixels.

-dither
    Applies dithering to improve color gradient representation.

-map file
    Uses the color map defined in file.

-rows N
    An alias for -height N.

-cols N
    An alias for -width N.

-compress
    Attempts to use run-length encoding for smaller output.

-noblank
    Prevents printing blank lines to fill terminal height.

-fontwidth N
    Specifies the character font width in pixels.

-fontheight N
    Specifies the character font height in pixels.

-font file
    Loads font metrics from a BDF font file.

-output file
    Redirects output to file instead of standard output.

-help
    Displays the command's help message.

-version
    Shows version information for ppmtoterm.

PPMfile
    Path to the input PPM image file, or reads from standard input if omitted.

ppmtoterm is a versatile utility from the Netpbm package, designed to transform a Portable Pixmap (PPM) image into a series of ANSI escape sequences. These sequences, when printed to a compatible text terminal, enable the display of images using a combination of characters, foreground colors, and background colors. This effectively creates a "graphics mode" within a text-based console, allowing users to view image content without requiring a graphical display server. The command intelligently attempts to render the image by leveraging the specific character set and color capabilities supported by the active terminal. The resulting output is typically sent to standard output, making it easy to pipe to other commands like less -R for viewing or redirect to a file. It's an invaluable tool for displaying visual information in purely command-line or SSH environments.

Terminal compatibility: Output relies heavily on the terminal's ability to interpret ANSI escape sequences, especially 256-color and 24-bit true color.
Font metrics: Accurate display depends on correct font width/height being known or specified, otherwise aspect ratio might be distorted.
Performance: Complex images or large sizes can result in very long output sequences, potentially slow to render.

To view the output of ppmtoterm with a pager like less or more while preserving the ANSI colors and formatting, it's essential to use the -R or -r option (raw mode) respectively. For example: ppmtoterm image.ppm | less -R. Without this option, the escape sequences will be displayed as raw text.

Part of the Netpbm package, which has a long history originating from PBMplus by Jef Poskanzer in 1988. Netpbm is a widely used toolkit for graphics manipulation in command-line environments. ppmtoterm specifically provides a way to render graphical content in text-based terminals, addressing the need for visual output in console environments.

netpbm(1), pbm(5), pgm(5), ppm(5)