Change Netpbm Bit Depth Safely with pamdepth

You will finish with a repeatable way to change the maximum sample value in a Netpbm image, check the resulting header, and keep the original file untouched while you test it. The examples use pamdepth from Netpbm 11.5.2, installed here as Debian package version 2:11.05.02-1.1build1.

Allow about fifteen minutes. You need a shell, the netpbm package, and a PNM, PAM or PBM-family image to work on. No example needs sudo. Keep a copy of any source image that matters: lowering its depth loses information through rounding, and that cannot be undone from the converted output.

1. Check the installed command

Confirm which executable will run and record the package version. These are ordinary read-only checks:

$ command -v pamdepth
/usr/bin/pamdepth
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ pamdepth --version
pamdepth: Using libnetpbm from Netpbm Version: Netpbm 11.5.2

The command has one required argument, newmaxval, followed optionally by an input filename. With no filename, it reads standard input. It writes the converted image to standard output, so redirect it to a new path while you verify the result.

2. Choose the new maximum value

Netpbm stores a maximum sample value in the image header. A sample of 50 in an image with maxval 100 represents the same relative brightness as a sample of 100 in an image with maxval 200. pamdepth rescales the samples, with possible rounding, rather than simply changing the header.

For five-bit colour or greyscale samples, use maxval 31. There are 32 possible values, from 0 through 31, so 32 is an off-by-one error. A value below 256 is also useful when a legacy reader expects raw PNM samples to fit in one byte.

Reducing a high maxval to a lower one is a lossy operation. Increasing it gives the samples more numeric range but cannot recreate detail that was absent from the source.

3. Convert to a separate output file

Use a small source file first if you are learning the workflow. This creates an ASCII PGM containing two samples, 50 and 100, with an input maxval of 100:

$ cat > input.pgm <<'EOF'
P2
2 1
100
50 100
EOF

The here-document changes the current directory, but it only creates the deliberately named test file. For a real image, substitute its path instead. Convert it to maxval 200 and send the result to a different file:

$ pamdepth 200 input.pgm > output.pgm
$ sed -n '1,3p' output.pgm
P5
2 1
200

The installed program emits raw PGM output here, so the sample bytes follow the three-line header and are not readable as text. The header is the useful first check: the output maxval is 200. A simple file check should identify the dimensions and greyscale format:

$ file input.pgm output.pgm
input.pgm:  Netpbm image data, size = 2 x 1, greymap, ASCII text
output.pgm: Netpbm image data, size = 2 x 1, rawbits, greymap

The input format is normally preserved, but this example demonstrates that the output may be written in a raw form. Do not assume that every converted file remains ASCII just because the source was ASCII.

4. Use standard input and process a stream

For a pipeline, omit the input filename. This converts the image arriving on standard input and writes the result to standard output:

$ cat input.pgm | pamdepth 31 > five-bit.pgm
$ sed -n '1,3p' five-bit.pgm
P5
2 1
31

pamdepth also handles multi-image streams. The following joins two PGM images and converts both. The repeated P5 header in the output shows that the second image was not silently discarded:

$ cat input.pgm input.pgm | pamdepth 31 | sed -n '1,8p'
P5
2 1
31
[binary sample data]
P5
2 1
31
[binary sample data]

Do not use sed to inspect arbitrary binary output beyond a controlled header check. Use an image-aware Netpbm tool or viewer for production files, and make sure a downstream program understands multi-image streams if you pass one through unchanged.

5. Understand format changes for black and white images

Changing the depth of a black and white image is not meaningful, so pamdepth promotes PBM input to PGM. A PAM image with tuple type BLACK_AND_WHITE becomes GRAYSCALE; the alpha variant becomes GRAYSCALE_ALPHA. This promotion happens even when the new maxval is 1.

That behaviour is part of the current Netpbm documentation. The manual also records a compatibility boundary: before Netpbm 10.92, a PAM black and white tuple failed when given a new maxval other than 1, although PBM was still promoted. If a script must run on older Netpbm installations, test this case on each supported version instead of assuming current behaviour.

The output format and PAM tuple type are otherwise usually retained. Verify the header rather than relying on the filename extension, especially when a consumer requires a particular PGM, PPM or PAM variant.

6. Handle errors without guessing

newmaxval must be at least 1. An invalid value fails before producing a usable conversion:

$ pamdepth 0 input.pgm > rejected.pgm
pamdepth: New maxval must be at least 1.  You specified 0
$ printf 'exit status: %s\n' "$?"
exit status: 1

The exact diagnostic can vary slightly with the Netpbm build, but a non-zero status is the signal to stop. Do not replace an existing output file until the command and its exit status have been checked. Shell redirection opens the destination before pamdepth runs, so use a new filename or a temporary directory when preserving an existing result matters.

There are no pamdepth-specific command-line options. It accepts options common to libnetpbm programs, but the conversion itself is controlled by the positional maxval and input stream. If a command copied from elsewhere contains an unfamiliar option, check the local manual before using it.