ppmtoarbtxt

Convert a PPM image to text as specified by the given template

$ ppmtoarbtxt [path/to/template] [path/to/image.ppm] > [path/to/output_file.txt]

$ ppmtoarbtxt [path/to/template] -hd [path/to/head_template] [path/to/image.ppm] > [path/to/output_file.txt]

$ ppmtoarbtxt [path/to/template] -hd [path/to/tail_template] [path/to/image.ppm] > [path/to/output_file.txt]

$ ppmtoarbtxt [[-v|-version]]

ppmtoarbtxt [options] [ppmfile]

-map string
    Specifies the string of characters to use for mapping pixel brightness. The first character in the string corresponds to the darkest pixels, and the last character to the brightest (unless -invert is used).

-invert
    Inverts the brightness mapping. The first character in the -map string will then correspond to the brightest pixels, and the last to the darkest.

-max value
    Sets the maximum brightness value (0-255) to map to the brightest character in the -map string. Values above this will also map to the brightest character.

-min value
    Sets the minimum brightness value (0-255) to map to the darkest character in the -map string. Values below this will also map to the darkest character.

-gamma value
    Applies gamma correction to the pixel brightness values before mapping. A value of 1.0 (default) means no correction. Values greater than 1.0 lighten the image, while values less than 1.0 darken it.

-bold
    For HTML output (with -html), wraps characters corresponding to pixels brighter than a certain threshold (default 50%) in <b> tags.

-italics
    For HTML output (with -html), wraps characters corresponding to pixels brighter than a certain threshold (default 50%) in <i> tags.

-threshold value
    Used with -bold or -italics, this specifies the brightness percentage (0-100) above which the corresponding HTML tag will be applied. Default is 50.

-html
    Outputs the result as an HTML document rather than plain text. This enables the use of -bold and -italics options.

-plain
    Outputs the result as plain text. This is the default behavior and implicitly disables HTML-specific options.

-width cols
    Scales the output image to fit approximately the specified number of character columns.

-height rows
    Scales the output image to fit approximately the specified number of character rows.

-fontwidth chars
    Specifies the pixel width of a character for scaling calculations when using -width or -height. Default is 6.

-fontheight lines
    Specifies the pixel height of a character for scaling calculations when using -width or -height. Default is 10.

-verbose
    Prints diagnostic information to standard error, which can be useful for debugging.

The ppmtoarbtxt command converts a Netpbm PPM (Portable Pixmap) image into a text-based representation. It calculates the brightness of each pixel and maps it to a character from a user-defined string specified with the -map option. Darker pixels typically map to characters at the beginning of the string, and brighter pixels map to characters towards the end. This utility is versatile for creating custom ASCII art, generating text-based previews, or producing HTML-formatted text images.

The visual quality of the text output is highly dependent on the input image's resolution, the chosen character map, and the font used for display. It is primarily designed for generating character-based representations or low-resolution ASCII art, not for high-fidelity image reproduction. The output characters will generally be much coarser than the original pixels.

The command first converts each pixel's RGB color value into a single brightness (luminosity) value. This value is then normalized to a range. The normalized brightness serves as an index into the character string provided by the -map option. For example, if you provide -map " .:-=+*#%@", the darkest pixels will be mapped to a space (' ') or a period ('.'), while the brightest pixels will be mapped to a hash ('#') or an at-sign ('@'), creating a grayscale effect using characters.

ppmtoarbtxt is a utility within the comprehensive Netpbm toolkit, a long-standing collection of graphics manipulation programs for Unix-like operating systems. Netpbm, originating from the early days of Unix, focuses on small, composable tools that can be chained together. ppmtoarbtxt specifically addresses the need to convert pixel-based images into human-readable text forms, a common practice for low-bandwidth display or artistic ASCII art generation.

netpbm(1), ppm(5), pnm(5), pnmtoascii(1), asciigrey(1)