pnmdepth

View documentation for the original command

$ tldr pamdepth

pnmdepth newmaxval [pnmfile]

pnmdepth is a specialized utility within the Netpbm image processing suite. Its primary function is to change the 'maxval' (maximum pixel value) of a PNM image. This 'maxval' determines the pixel depth, indicating the range of intensity values or colors available for each pixel.

For grayscale images (PGM) and color images (PPM), a higher maxval allows for more distinct shades or colors, providing finer gradation. For example, a maxval of 255 means 256 possible values (0-255), while 65535 allows for 65536 values. When you use pnmdepth to decrease the maxval, it scales down the existing pixel values, which can lead to a loss of detail and potentially introduce banding or quantization artifacts. Conversely, increasing the maxval simply scales up the existing values, without adding new information or detail to the image; it merely expands the range.

pnmdepth reads a PNM image (PBM, PGM, or PPM) from standard input and writes the modified image to standard output, making it suitable for use in pipelines with other Netpbm tools.

When decreasing the maxval, pnmdepth performs a simple linear scaling of pixel values. This means that if the original image has a wide range of distinct colors or shades, reducing the maxval will irreversibly quantize these values, potentially leading to a loss of detail, color banding, or posterization effects.

Increasing the maxval does not add any new information or detail to the image; it merely stretches the existing pixel values across a larger range, which can sometimes make existing imperfections more apparent. The input maxval must not exceed 65535.

pnmdepth does not accept any command-line options (flags). Instead, it requires a single mandatory argument: newmaxval. This argument is an integer that specifies the desired maximum pixel value for the output image. It must be a positive integer, typically between 1 and 65535.

The command reads the input PNM image from standard input if no pnmfile is specified. If an optional pnmfile is provided, it reads the image from that file. The transformed image is always written to standard output. This behavior makes pnmdepth highly compatible with Unix pipelines.

Example: To convert an image to a maxval of 255 (standard 8-bit depth for many applications):
cat input.ppm | pnmdepth 255 > output.ppm

pnmdepth is an integral part of the Netpbm project, a venerable toolkit for graphics manipulation that originated from Jef Poskanzer's PBMPlus package in the late 1980s. The Netpbm suite, including pnmdepth, was designed to be highly modular, allowing users to chain simple, single-purpose commands together via pipes to perform complex image transformations. This design philosophy emphasizes simplicity, efficiency, and interoperability within the Unix-like environment. pnmdepth continues to be a fundamental tool for managing pixel depth in image processing workflows, particularly when interfacing with systems or applications that require specific maximum pixel values.

pnm(5), pamdepth(1), pnmscale(1), pnmgamma(1), pbm(5), pgm(5), ppm(5)