pnmquant

Generate an image using only n_colors or less colors as close as possible to the input image

$ pnmquant [n_colors] [path/to/input.pnm] > [path/to/output.pnm]

pnmquant [-nofs] [-floyd] [-fs] [-meangray] [-mapfile mapfile] {N | -colors=N} [pnmfile]

-nofs
    Disables Floyd-Steinberg error diffusion. Each pixel is mapped directly to the closest color in the target palette, which can result in banding or posterization.

-floyd or -fs
    Enables Floyd-Steinberg error diffusion (dithering). This is the default behavior. It spreads quantization errors to neighboring pixels, creating the illusion of more colors and reducing banding.

-meangray
    Converts the image to grayscale by averaging the R, G, and B components for each pixel before quantization. This is not typical color quantization but a specific grayscale conversion method.

-mapfile mapfile
    Uses the colors from the specified mapfile as the target palette for quantization. The mapfile must be a PNM image. The number of colors in the map file implicitly defines the target number of colors.

N
    Specifies the maximum number of colors (N) to reduce the image to. This is a required argument and can be provided as a number directly or using the -colors= option.

-colors=N
    An alternative way to specify the maximum number of colors (N) to reduce the image to, identical in function to providing N directly.

pnmfile
    The input PNM image file. If not specified, pnmquant reads the image from standard input.

pnmquant is a Netpbm command-line utility used to reduce the number of colors in a PNM (Portable Anymap) image. This process, known as color quantization, is essential for converting high-color images (e.g., 24-bit truecolor) into images with a limited palette (e.g., 8-bit, 256 colors).

The primary use cases include preparing images for display on hardware with limited color capabilities, reducing file sizes for web or embedded systems, or converting images to formats like GIF or PNG-8 that support indexed color. pnmquant employs various algorithms, most notably error diffusion (dithering) like Floyd-Steinberg, to minimize visual artifacts when mapping original colors to a smaller palette. Without dithering, colors are simply mapped to the nearest available color, which can lead to banding or posterization effects.

The quality of the quantized image is highly dependent on the chosen number of colors (N) and whether dithering is used. Too few colors without dithering can lead to significant loss of detail and color banding. Dithering can introduce noise but generally improves perceived image quality at low color depths. The -meangray option performs a simple average for grayscale, which might not be perceptually optimal for all images.

pnmquant reads a PNM image from standard input if no pnmfile is specified. The quantized image is written to standard output in PNM format. This allows for easy piping with other Netpbm utilities.

When a map file is not provided, pnmquant intelligently selects the N most representative colors from the input image to form the new palette. This process is optimized to retain as much visual information as possible given the color constraint.

pnmquant is part of the Netpbm project, a toolkit for manipulating graphic images. Netpbm originated from the PBMPLUS package by Jef Poskanzer in the late 1980s, which became a foundational suite for image processing on Unix-like systems. pnmquant has been a core utility for color reduction since the early days of the toolkit.

pnm(5), pnmcolormap(1), pnmdepth(1), pnmgamma(1)