ppmquant

View documentation for pnmquant

$ tldr pnmquant

$ tldr pnmremap

ppmquant [options] numcolors [inputfile]

numcolors
    The required integer argument specifying the maximum number of colors for the output image. This value must be between 1 and 65536, inclusive.

-floyd / -fs
    Use Floyd-Steinberg error diffusion dithering. This technique helps to reduce banding artifacts and improve the perceived color depth when quantizing to a smaller palette.

-nofs
    Disable dithering. This results in a sharper image but may introduce noticeable banding or posterization effects, especially with significant color reduction.

-randomdither
    Apply random noise dithering. This is an alternative dithering method to Floyd-Steinberg.

-norandomdither
    Disable random noise dithering.

-mapfile=mapfile
    Quantize colors to the specific color map defined in mapfile instead of generating a new palette. The number of colors in mapfile overrides numcolors.

-mapformat=format
    Specifies the format of the -mapfile. Valid formats include ppm, xpm, xbm, pgm, and pbm.

-gamma=value
    Apply gamma correction with the specified value to the image before quantization. This can affect how colors are perceived and grouped during the quantization process.

-pmfile=file
    Use a predefined palette from file for quantization. This implies a fixed palette and generally disables dithering.

-nice
    Generate a 'nicer' palette. This option attempts to preserve visual quality by potentially using fewer than the requested numcolors if it results in a more visually appealing color set.

-verbose
    Output progress and diagnostic information to standard error, providing insights into the quantization process.

-extrainfo
    Print additional detailed information about the quantization process, such as color distribution statistics.

-meancut
    Force the use of the mean-cut algorithm for palette generation instead of the default median-cut algorithm. The mean-cut algorithm divides color space boxes at the mean of the color components.

-nopa
    Do not generate a Netpbm format image with an embedded palette. The output will be a plain PPM image where each pixel's color is directly mapped to the closest color in the generated palette.

-sort=order
    Sort the colors in the output colormap according to the specified order. Common orders include rgb, gray, hue, saturation, value, and freq (frequency).

ppmquant is a command-line utility from the Netpbm suite that quantizes a Portable Pixmap (PPM) image to a specified maximum number of colors. It reads a PPM image from standard input (or a specified file) and writes a new PPM image with a reduced color palette to standard output.

The primary purpose of color quantization is to reduce the file size of an image, adapt it for displays with limited color depth (e.g., 256-color monitors), or prepare it for conversion to palettized image formats like GIF or indexed PNGs. By default, ppmquant employs a median-cut algorithm to determine the optimal color palette. It can also apply dithering techniques, such as Floyd-Steinberg, to minimize banding artifacts that may arise from significant color reduction, thus preserving visual quality.

While ppmquant operates on PPM images, its `numcolors` argument specifies the maximum number of colors. The actual output image might have fewer colors if the original image contains fewer unique colors, or if the -nice option is used.

Dithering significantly enhances visual quality after color reduction but can slightly increase file size due to less repetitive pixel data.

For specific color requirements, providing a fixed palette via -mapfile or -pmfile offers more control than relying solely on the algorithmic quantization.

If no inputfile is specified, ppmquant reads the PPM image from standard input. The quantized PPM image is always written to standard output. This design facilitates piping ppmquant with other Netpbm utilities for complex image processing workflows.

The numcolors argument effectively transforms a full-color PPM image into an indexed-color image, albeit still represented in the PPM format. The generated palette is embedded within the output PPM header, and pixels are then mapped to the closest colors in this new, smaller palette.

By default, ppmquant uses the median-cut algorithm, which recursively divides the color space into smaller rectangular boxes until the desired number of colors is met. The -meancut option provides an alternative, using the mean of the color components for division, which can sometimes yield different results.

ppmquant is a long-standing component of the Netpbm project, which originated from the `pbmplus` package in the late 1980s. Its development was driven by the necessity to efficiently manage and display true-color images on hardware with limited color capabilities. The underlying median-cut color quantization algorithm, a core feature, has been a standard technique for decades. ppmquant has consistently served as a robust command-line utility for color reduction, adapting to evolving image processing needs within the versatile Netpbm toolkit.

pnmquant(1), pnmhistmap(1), pnmcolormap(1), ppmtogif(1), ppmtojpeg(1)