pnmhistmap

Draw a histogram of a PNM image

$ pnmhistmap [path/to/input.pnm] > [path/to/output.pnm]

$ pnmhistmap [[-d|-dots]] [path/to/input.pnm] > [path/to/output.pnm]

$ pnmhistmap [[-l|-lval]] [minval] [[-rv|-rval]] [maxval] [path/to/input.pnm] > [path/to/output.pnm]

pnmhistmap [-maxval=value] [-xsize=pixels] [-ysize=pixels] [-greyscale] [-nofill] [-noheader] [pnmfile]

pnmfile
    The path to the input PNM image file. If omitted, pnmhistmap reads the image data from standard input.

-maxval=value
    Specifies the maximum pixel value (maxval) for the output histogram image. This affects the brightness range of the generated map. Defaults to 255.

-xsize=pixels
    Sets the width of the output histogram image in pixels. The default width is typically 256 or a multiple of 256 to align with the 256 bins.

-ysize=pixels
    Sets the height of the output histogram image in pixels. The default height is typically 256.

-greyscale
    Forces the output histogram to be a grayscale (PGM) image, even if the input is a color (PPM) image. This displays the luminance histogram.

-nofill
    By default, the area below the histogram line is filled. This option prevents filling, showing only the line itself.

-noheader
    Suppresses the drawing of the descriptive header text at the top of the output histogram image.

pnmhistmap is a utility from the Netpbm suite that generates a visual histogram of a PNM (Portable Anymap) image. It reads an input image and computes the frequency of pixel values across its intensity or color range. The output is a new PNM image (PGM for grayscale, PPM for color) that graphically represents this histogram.

For grayscale images, it plots the distribution of intensity values. For color images, it typically plots the distribution for each color component (red, green, blue) separately or can be forced to grayscale to show overall luminance. The X-axis of the output histogram represents the pixel value range (from 0 to the image's maxval), divided into 256 bins by default, while the Y-axis indicates the frequency or count of pixels falling into each bin.

This command is invaluable for analyzing image characteristics such as contrast, exposure, and color balance. It's designed to be used in shell pipelines, allowing seamless integration with other Netpbm tools for comprehensive image manipulation and analysis.

While pnmhistmap can process color images, it typically generates separate histograms for each color component (red, green, and blue) unless the -greyscale option is used. It does not produce a true 3D color histogram. The default binning is 256, which covers the typical 0-255 range for 8-bit images, but images with higher maxval will still be mapped to these bins, potentially losing fine detail if not scaled appropriately.

To generate a grayscale histogram map of an image named input.pnm and save it to histogram.pgm:

pnmhistmap -greyscale input.pnm > histogram.pgm

To pipe output from another Netpbm command, for example, creating a histogram from a converted JPEG:

jpegtopnm myimage.jpg | pnmhistmap -xsize=512 -ysize=300 > hist_output.ppm

By default, pnmhistmap divides the input image's pixel value range (from 0 to its maxval) into 256 bins. It then counts how many pixels fall into each bin. The output image's Y-axis (height) is scaled such that the highest frequency bin reaches the top of the graph, making the distribution clearly visible. For color images, this process is applied to each of the red, green, and blue components individually before drawing them on the same map.

pnmhistmap is an integral part of the Netpbm package, which evolved from the original PBMplus toolkit developed by Jef Poskanzer. The Netpbm suite, designed around a philosophy of small, specialized tools that can be chained together via pipes, has been a staple in Unix-like environments for image processing since the late 1980s.

The inclusion of histogram generation tools like pnmhistmap reflects the early recognition of the importance of statistical image analysis for tasks ranging from print preparation to scientific visualization. Its development focused on being robust, efficient, and compatible with the broader Netpbm ecosystem's pipe-based workflow, allowing users to easily analyze and then manipulate image properties based on their histogram distribution.

pnm(5), pgm(5), ppm(5), pnmgamma(1), pnmnorm(1), pnmhisteq(1), netpbm(1)