ppmhist

Generate the histogram for human reading

$ ppmhist [[-nom|-nomap]] [path/to/image.ppm]

$ ppmhist [[-m|-map]] [path/to/image.ppm]

$ ppmhist [[-v|-version]]

ppmhist [options] [ppmfile]

-output=file
    Specifies the output file path for the histogram. Defaults to standard output if not provided.

-bars
    Instructs ppmhist to output a visual histogram image instead of the default text list.

-imagetype=type
    For -bars output, specifies the type of the output image (e.g., ppm for color, pgm for intensity/grayscale). The default is typically ppm.

-sort=key
    Sorts the histogram entries based on a specified key. Common keys include count (frequency), intensity, red, green, or blue.

-verbose
    Prints additional processing information and statistics to standard error.

-width=n
    Sets the width in pixels for the output image when -bars is used.

-height=n
    Sets the height in pixels for the output image when -bars is used.

-bincolors=n
    Groups colors into n bins or categories, effectively reducing the number of distinct colors represented in the histogram. Useful for high-color images.

-relative
    Outputs color counts as percentages of the total pixels, rather than raw pixel counts.

-rgbonly
    Counts only distinct RGB triples. If omitted, colors are typically converted to intensity for counting, which might group different colored pixels with the same intensity value.

-color=colorname
    For the visual histogram output, specifies the color of the bars. The colorname can be an X11 color name or a hexadecimal RGB value.

-background=colorname
    For the visual histogram output, specifies the background color of the image.

ppmhist is a utility from the Netpbm suite designed to analyze the color or intensity distribution of a Portable Pixmap (PPM) image. It reads a PPM image as input and calculates the frequency of each unique color encountered. The command can output this histogram in two primary formats: a plain text list detailing each color and its count, or a visual representation as another Netpbm image (PPM or PGM). This visual output displays the histogram as a bar graph, where bar heights correspond to color frequencies. ppmhist is invaluable for tasks such as understanding the dominant colors in an image, optimizing color palettes, analyzing image compression effectiveness, or preparing images for color correction by revealing their tonal range and color balance. It provides insightful data for various image processing and analysis workflows.

ppmhist expects its input to be in the Netpbm PPM format. If your image is in another format (like JPEG or PNG), you must first convert it using a tool like anytopnm(1). For images with a very high number of distinct colors, the text output can be extremely long and resource-intensive. When using the -bars option for visual output, a low image width might lead to indistinguishable bars if there are too many distinct colors to represent adequately.

ppmhist offers two distinct ways to present the image histogram:

Text Output: By default, ppmhist produces a plain text list. Each line typically shows a color (often as an RGB tuple or color name) followed by the count of pixels with that color, and sometimes its intensity. This mode is highly suitable for scripting, further numerical analysis, or direct human readability of color frequencies.

Visual Histogram (Bars): When the -bars option is used, ppmhist generates a graphical representation of the histogram as a Netpbm image. This image typically displays vertical bars, where each bar represents a specific color or intensity range, and its height corresponds to the frequency of that color/intensity in the original image. This mode is excellent for quick visual assessment of color distribution and identifying dominant hues or tonal ranges.

ppmhist is an integral part of the Netpbm graphics utilities package, which traces its origins back to the PBMplus toolkit developed in the early 1990s. This suite of tools has been a cornerstone of Unix-like systems for manipulating and converting various image formats, particularly the portable "anymap" formats (PPM, PGM, PBM). ppmhist embodies the Netpbm philosophy of simple, modular tools that can be chained together for complex image processing tasks, providing a fundamental capability for analyzing image content since its inception.

ppm(5), pgm(5), pnm(5), anytopnm(1), netpbm(1)