pnmcolormap

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

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

$ pnmcolormap [[-splits|-splitspread]] [n_colors] [path/to/input.pnm] > [path/to/output.ppm]

$ pnmcolormap [[-so|-sort]] [path/to/input.pnm] > [path/to/output.ppm]

pnmcolormap [-colors N] [-transparent] [-transparent-color color] [-transparent-max value] [-transparent-luminance value] [-transparent-threshold value] [-mapfile filename] [-exact] [-verbose] [pnmfile]

-colors N
    Specifies the maximum number of colors (N) to include in the output colormap. The default value is 256.

-transparent
    Instructs pnmcolormap to consider transparent pixels. It attempts to make the most common transparent color one of the chosen colormap colors, but excludes transparent pixels from the color quantization process itself.

-transparent-color color
    Defines the exact color to be treated as transparent. This is useful when the image has transparent pixels, and you want to ensure a specific color is handled as the transparent one. If not specified, pnmcolormap tries to deduce it.

-transparent-max value
    Sets the maximum value an alpha channel sample can have for a pixel to be considered transparent. The default is 0.

-transparent-luminance value
    Specifies the minimum luminance a pixel must have to be considered transparent.

-transparent-threshold value
    Defines the maximum alpha channel threshold for considering a pixel transparent.

-mapfile filename
    Provides an external colormap file to use. Instead of analyzing the input image for colors, pnmcolormap will select a colormap from this specified file.

-exact
    When used with -mapfile, this option forces pnmcolormap to use all colors from the provided mapfile, even if some of them are not present in the input image. Without -exact, only colors from the mapfile that are actually present in the input image are used.

-verbose
    Enables verbose output, printing more information about the colormap generation process to standard error.

pnmfile
    The input PNM image file. If omitted, pnmcolormap reads the image data from standard input.

pnmcolormap is a utility from the Netpbm image processing toolkit. It reads a PNM (Portable Anymap) image from standard input or a specified file and outputs a colormap. This colormap is itself a PNM image, typically consisting of a single row of pixels representing the chosen colors.

The primary purpose of pnmcolormap is to determine a reduced set of colors that best represents the original image, often used for color quantization. It employs an algorithm to select the optimal N colors from the input image, minimizing the perceived color distance between the original and quantized image.

This command is frequently used in conjunction with pnmquant or ppmquant. pnmcolormap generates the palette, and then pnmquant applies that palette to the image, converting it to an indexed color format. It also offers options for handling transparent pixels, allowing the generated colormap to account for transparency.

By generating a specific colormap, pnmcolormap provides fine-grained control over color reduction, which is crucial for optimizing images for formats that support limited color palettes, such as GIF or indexed PNG.

The algorithm employed by pnmcolormap aims to minimize color distance, but the resulting colormap may not always be perceptually optimal for all types of images or specific visual preferences. Processing very large images with a vast number of unique colors can be computationally intensive and may require significant memory resources. The transparent options, while powerful, can sometimes be complex and may require experimentation to achieve the desired effect.

The core algorithm used by pnmcolormap for selecting colors is a variation of the median cut algorithm, a popular technique for color quantization that recursively subdivides color space to find the most representative colors.

The output of pnmcolormap is a PNM image (PBM, PGM, or PPM depending on the input image's type), specifically structured as a list of colors. Typically, this output image will have only one row of pixels, with each pixel representing one color in the generated colormap.

pnmcolormap is an integral part of the Netpbm suite, a collection of graphics utilities with a rich history rooted in the Unix environment. Netpbm evolved from Jef Poskanzer's pbmplus package, first released in the late 1980s. As image formats and processing needs became more sophisticated, tools like pnmcolormap were developed to provide more generalized and advanced capabilities for tasks such as color reduction and palette optimization, moving beyond simpler quantization methods to offer more control over the generated colormaps, particularly for indexed color formats like GIF or PNG.

pnmquant(1), ppmquant(1), pnm(5), netpbm(1)