pgmnorm

View documentation for the current command

$ tldr pnmnorm

pgmnorm [-b blackval] [-w whiteval] [-m maxval] [-s] [-d] [pgmfile]

-b blackval
    Specifies the input pixel value that should become black (0) in the output. By default, the darkest pixel in the input image determines the black point.

-w whiteval
    Specifies the input pixel value that should become white (the output maxval) in the output. By default, the brightest pixel in the input image determines the white point.

-m maxval
    Sets the maximum pixel value for the output PGM image. If not specified, the input image's maximum value is used.

-s
    Activates "spread" mode. Instead of clipping values outside the specified black and white points, pgmnorm stretches the values between blackval and whiteval to fill the entire output range [0, maxval].

-d
    Enables diagnostic output, printing information about the black and white points found or used, and the mapping equation.

pgmfile
    The path to the input PGM image file. If omitted, pgmnorm reads image data from standard input.

pgmnorm is a Netpbm utility that normalizes the contrast of a Portable Graymap (PGM) image. It achieves this by mapping a specified "black point" to the output image's darkest value (0) and a "white point" to its lightest value (maximum pixel value). By default, pgmnorm determines these points from the darkest and lightest pixels present in the input image. This process effectively stretches the image's tonal range to utilize the full available grayscale spectrum, often improving visual clarity in images that appear washed out or too dark. It can also handle specific value mapping and output maximum value adjustment.

pgmnorm operates exclusively on PGM (Portable Graymap) image files. For other image formats, they must first be converted to PGM using appropriate Netpbm tools (e.g., anytoppm followed by ppmtopgm).
The -s (spread) option can significantly alter the image's appearance by stretching a narrow range of pixel values to fill the entire dynamic range, potentially losing detail in areas outside the specified blackval and whiteval if not used carefully.

pgmnorm reads a PGM image from pgmfile if specified, or from standard input otherwise. The processed PGM image is written to standard output. This allows for easy piping with other Netpbm utilities. For example: cat image.pgm | pgmnorm -s | pgmtopng > output.png.

pgmnorm calculates a linear transformation from the input pixel values to the output pixel values. The transformation maps blackval to 0 and whiteval to the output maxval. Pixels darker than blackval are set to 0, and pixels brighter than whiteval are set to maxval. When the -s option is used, values outside the [blackval, whiteval] range are scaled into the output range rather than being clipped.

pgmnorm is an integral part of the Netpbm project, a long-standing suite of graphics manipulation programs dating back to the early 1990s (originally PBMPlus). Netpbm tools are designed to be simple, efficient, and composable, often used together via Unix pipes. pgmnorm serves a fundamental role in image preprocessing, particularly for enhancing the visual quality of grayscale images by adjusting their contrast, making it a widely used tool within scripts and workflows dealing with scientific imaging, scanned documents, or general image analysis where tonal range optimization is crucial.

pgm(5), pgmhist(1), pnmgamma(1), pnmremap(1), netpbm(1)