Replace pnmdepth with pamdepth for Reliable Netpbm Scaling

You will convert a Netpbm image to a new maximum sample value with the installed pamdepth command, while preserving the image's colours as closely as integer rounding allows. On this machine, pnmdepth is an obsolete compatibility name for pamdepth, from Netpbm 11.5.2.

Allow about ten minutes. You need Netpbm, a PNM, PBM, PGM, PPM or PAM file, and enough disk space for a second copy of the output. The examples use ordinary user permissions and write to standard output. They do not alter the input file.

1. Confirm the replacement and version

The local pnmdepth(1) manual says that the command was replaced by pamdepth in Netpbm 10.32. It also records a historical broken alias in that release. Do not build a new workflow around the old name when the replacement is available.

$ command -v pamdepth
/usr/bin/pamdepth
$ command -v pnmdepth
/usr/bin/pnmdepth
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ readlink -f /usr/bin/pnmdepth
/usr/bin/pamdepth

The exact package revision can differ between systems. The useful checks are that pamdepth exists and that the old command resolves to the same implementation or is otherwise known to work.

2. Check the input header before changing it

pamdepth takes a new maximum value and an optional input file:

$ pamdepth newmaxval [netpbmfile]

Inspect the first part of a file before choosing the target. The header tells you the format, dimensions and current maximum value. This read-only command is safe for an ordinary user:

$ sed -n '1,4p' input.pgm
P2
640 480
255
0 17 42 255

For a raw binary file, the samples start after the header and may not be printable. Use a Netpbm inspection tool available on your system, or examine only the header with care. Do not assume that a file ending in .ppm is necessarily a particular Netpbm encoding.

newmaxval is the largest sample value in the output, not the number of levels. For five-bit samples, use 31, giving values from 0 through 31. Using 32 creates 33 possible values and is an off-by-one error.

3. Convert to a smaller depth without overwriting the source

Choose a separate output path first. This example converts an existing PGM to an eight-bit maximum and leaves the input untouched:

$ pamdepth 255 input.pgm > output.pgm
$ printf 'output header:\n'
$ sed -n '1,3p' output.pgm
output header:
P5
640 480
255

The output format is usually the same as the input. The command writes the transformed image to standard output, so the shell redirection is what creates output.pgm. A non-zero exit status means you should treat that output as untrusted and inspect or remove it before retrying.

Reducing the maximum value reduces colour resolution and therefore loses information. The program rescales samples to retain the same colours as closely as the new integer range permits, but it cannot recover distinctions that the smaller range cannot represent.

$ test -s output.pgm && printf 'output exists and is non-empty\n'
output exists and is non-empty
$ cmp -s input.pgm output.pgm; printf 'cmp status: %s\n' "$?"
cmp status: 1

A different file is expected after a conversion. If the output is empty or the command failed, remove only the failed output with rm -- output.pgm and keep the original. That removal is destructive, so verify the path before running it.

4. Convert a sample stream you can verify

A small ASCII PGM makes the scaling rule visible. Here, samples 0 and 3 are changed to 0 and 15 when the target maximum is 15:

$ printf 'P2\n2 1\n3\n0 3\n' | pamdepth 15 | od -An -t u1 -N 12
  80  53  10  50  10  49  32  49  53  10   0  15

The output begins with P5, because Netpbm normally writes a raw binary PGM, followed by the dimensions and new maximum. The final two bytes shown are the two one-byte samples, 0 and 15. Byte positions and header whitespace can vary, so use a Netpbm reader for general validation rather than depending on a byte-for-byte layout.

This also demonstrates why a target below 256 is useful when a downstream program only understands the older one-byte-per-sample PNM convention. It is a compatibility choice, not a universal quality recommendation. Confirm the receiving program's limits before converting production images.

5. Keep format changes and depth changes separate

pamdepth is broader than the old pnmdepth. It can process arbitrary PAM images and multi-image streams, while the old program handled PNM images and ignored all but the first image in a stream. That makes the replacement safer for current Netpbm workflows, but it does not mean every consumer accepts every output format.

PBM input is a special case. Changing the depth of a black-and-white image requires a grayscale representation, so PBM input becomes PGM. A PAM image with a black-and-white tuple type similarly becomes a grayscale PAM tuple. This happens even when the requested maximum is 1.

$ printf 'P1\n2 1\n0 1\n' | pamdepth 1 | sed -n '1,3p'
P5
2 1
1

If a receiving tool requires PBM specifically, do not rely on pamdepth to preserve that format. Perform a separately verified format conversion with an appropriate Netpbm tool, then inspect the result.

6. Handle files and streams safely

With no filename, pamdepth reads standard input. This is useful in pipelines, but it also makes accidental input easy to miss. Make the source explicit when reproducibility matters:

$ pamdepth 31 input.pam > output.pam
$ printf 'pamdepth status: %s\n' "$?"
pamdepth status: 0

The program supports multi-image streams. If you need only one image, split or select it before the conversion with a tool that understands your stream format. Do not assume that redirecting a stream to one filename means there was only one image.

For a batch job, write to a temporary file in the same directory, validate it, then rename it over the original only after you have a recovery copy. Renaming over the input is an irreversible state change from the point of view of this guide. Keep the original until the converted file has passed the consumer's checks.

No elevated privileges are needed for the examples. Use sudo only if the input or output directory is deliberately restricted, and check the path and ownership first. Privilege does not make a bad target maximum or an incompatible output format safe.

7. Diagnose the common failures

• Command not found: check command -v pamdepth and the installed Netpbm package. Do not recreate the obsolete alias blindly.
• Invalid or missing input: confirm the file path, permissions and Netpbm header. A shell redirection can create an empty output even when the reader failed.
• Unexpected banding: you may have reduced the maximum too far. Restore the source and choose a larger target; do not repeatedly convert the already reduced output.
• Consumer rejects the result: check whether it requires PBM, a one-byte maximum below 256, a single image, or a particular PAM tuple type. Depth conversion does not satisfy all format constraints.
• Only the first image changed: check whether an old pnmdepth implementation or another pipeline component is being used. The current pamdepth processes multi-image streams.