ppmtomap

View documentation for the current command

$ tldr pnmcolormap

ppmtomap [-threshold] [ppmfile]

-threshold
    Forces a simple thresholding method for conversion to monochrome instead of the default Floyd-Steinberg dithering. Pixels are converted to white (1) if their value is greater than or equal to half of the maximum possible pixel value (maxval), and to black (0) otherwise. This method is generally less visually appealing than dithering.

ppmtomap converts a Portable Pixmap (PPM) image into an X11 bitmap (XBM) format.

XBM is a monochrome (black and white) image format commonly used in X Window System applications for icons, cursors, and simple graphics. When converting a color or grayscale PPM image, ppmtomap employs a dithering algorithm, specifically Floyd-Steinberg dithering by default, to simulate shades of gray using only black and white pixels. This technique helps to preserve visual detail that would otherwise be lost in a direct binary conversion.

The command reads the PPM image from standard input by default, or from a specified file, and writes the resulting XBM data to standard output. This design makes it well-suited for use within shell pipelines for image processing tasks.

The output XBM format is strictly monochrome, meaning all color and grayscale information from the original PPM image is lost. While dithering attempts to compensate for this, it cannot perfectly represent the original image's tonality. XBM files are text-based and are primarily intended for small, simple graphics like icons or cursors, not for photographic or complex images due to their inherent limitations and file size for larger resolutions.

ppmtomap adheres to the standard Unix paradigm of reading from standard input and writing to standard output. This allows it to be seamlessly integrated into complex command pipelines. For instance, you can pipe the output of another Netpbm tool (like jpegtoppm) directly into ppmtomap, and then redirect its output to a file or another command.

By default, ppmtomap uses the Floyd-Steinberg dithering algorithm. Dithering is a technique used to create the illusion of color depth in images with a limited color palette (in this case, just black and white). It achieves this by scattering pixels of available colors in a pattern that fools the eye into perceiving intermediate shades. The alternative, simple thresholding (enabled by the -threshold option), merely converts pixels to black or white based on a midpoint, often resulting in a harsh, blocky image with significant loss of detail compared to dithering.

ppmtomap is an integral part of the Netpbm image processing toolkit, which originated from the Pbmplus package developed by Jef Poskanzer in the late 1980s. Netpbm is known for its modular design, where many small utilities perform specific image conversions or manipulations. ppmtomap embodies this philosophy by providing a focused tool for converting the ubiquitous PPM format to the X11 bitmap format, enabling interoperability within the X Window System environment. Its development aligns with the broader history of Unix tools designed for composability and pipeline processing.

ppm(5), xbm(5), ppmtopbm(1), ppmtopgm(1), netpbm(1)