pamdepth

Read a PBM image, set its maxval and save it to a file

$ pamdepth [maxval] [path/to/image.pbm] > [path/to/file.pbm]

pamdepth [-depth N] [-maxval M] [-dither | -nodither] [-floyd | -nofloyd] [-red | -green | -blue | -black] [-verbose] [pamfile]

-depth N
    Sets the new depth of the output image. N specifies the number of samples per tuple (e.g., 1 for grayscale, 3 for RGB).

-maxval M
    Sets the new maximum sample value for each component in the output image. M must be greater than or equal to 1. This effectively controls the bit depth (e.g., maxval 255 is 8-bit).

-dither
    Enables dithering when the maxval is reduced, improving visual quality by dispersing quantization errors. Floyd-Steinberg is the default dithering algorithm.

-nodither
    Disables dithering, resulting in a direct truncation of sample values if maxval is reduced.

-floyd
    Explicitly enables Floyd-Steinberg dithering. This is the default dithering algorithm when maxval is reduced and dithering is enabled.

-nofloyd
    Same as -nodither; disables Floyd-Steinberg dithering.

-red
    Converts the image to grayscale (depth 1) using only the red component of the input image.

-green
    Converts the image to grayscale (depth 1) using only the green component of the input image.

-blue
    Converts the image to grayscale (depth 1) using only the blue component of the input image.

-black
    Converts the image to a solid black image (depth 1).

-verbose
    Prints informative messages about the conversion process to standard error.

[pamfile]
    The path to the input PAM image file. If omitted, pamdepth reads from standard input.

pamdepth is a utility from the Netpbm toolkit, designed to modify the characteristics of a Portable Arbitrary Map (PAM) image. It precisely adjusts the depth (number of samples per pixel, e.g., 1 for grayscale, 3 for RGB, 4 for RGBA) and the maxval (maximum sample value for each component, e.g., 255 for 8-bit color).

Its primary use cases include reducing file size by lowering maxval (e.g., converting 16-bit to 8-bit), preparing images for displays with limited color depths, or converting color images to grayscale. When reducing maxval, pamdepth can employ dithering techniques, particularly Floyd-Steinberg dithering (which is the default when reduction occurs), to minimize quantization errors and preserve visual detail by distributing errors across neighboring pixels. The command reads the PAM image from standard input or a specified file and writes the modified image to standard output. It also offers specific options to extract individual color channels or create a black image, effectively changing the image's depth to 1.

Loss of Information: When reducing the maxval or depth of an image, pamdepth inherently involves a loss of information. While dithering can mitigate visible artifacts, the original data cannot be fully recovered.

Performance with Dithering: Dithering operations, especially on large images, can be computationally intensive and may take longer than simple truncation.

Output Format: The output is always a PAM image. If other formats are required, a subsequent Netpbm conversion tool (e.g., pamtoppm) must be used.

pamdepth is designed to work as a filter in a Unix pipeline. It reads the input image from standard input (stdin) by default, or from a specified file path. The resulting modified image is then written to standard output (stdout). This allows for chaining multiple Netpbm commands together for complex image manipulation tasks. For example, cat image.png | pngtopam | pamdepth -maxval 15 | pamtopng > output.png.

pamdepth is a part of the Netpbm package, a venerable suite of graphics utilities dating back to the late 1980s/early 1990s. Initially, Netpbm focused on PBM (Portable Bitmap), PGM (Portable Graymap), and PPM (Portable Pixmap) formats.

The PAM (Portable Arbitrary Map) format and associated tools like pamdepth were introduced later (around the early 2000s) to provide a more flexible and extensible format that could handle arbitrary depths, alpha channels, and other image characteristics not easily represented by the older PNM formats. pamdepth superseded the more limited pnmdepth by offering greater control over both maxval and depth, and by supporting the more modern PAM format which Netpbm tools now predominantly use for internal processing. Its development reflects the ongoing evolution of image processing needs, moving towards more flexible and robust ways to manipulate pixel data.

pam(5), pnmdepth(1), pamditherbw(1), pnmreduce(1), netpbm(1)