Copy Netpbm Images into PAM Format with pamtopam

You will convert a PBM, PGM, PPM or existing PAM image into a PAM stream, save it safely, and check that the output is really a PAM image. The examples use the locally installed Netpbm 11.5.2, provided by package netpbm 2:11.05.02-1.1build1.

Allow about ten minutes. You need a shell, a readable Netpbm image, and permission to write the destination directory. The normal workflow is unprivileged. Do not use sudo unless filesystem permissions genuinely require it.

1. Check the installed command

Confirm which executable your shell will run and record the Netpbm version:

$ command -v pamtopam
/usr/bin/pamtopam
$ pamtopam --version
pamtopam: Using libnetpbm from Netpbm Version: Netpbm 11.5.2

The version command also prints build information and then exits. Exact extra lines vary with the package build. This guide concerns the behaviour documented by the installed manual: pamtopam reads standard input and writes standard output.

2. Convert an image by using standard input and output

Pass the source with shell redirection and choose a new destination. This example leaves the source untouched:

$ pamtopam < /path/to/source.ppm > /path/to/output.pam

Although the file name says .ppm, the command can read PBM, PGM, PPM or PAM input. The output is a PAM image in all four cases. pamtopam does not resize, recolour or otherwise enhance the picture. It translates the Netpbm image representation into PAM and sends the result to standard output.

There are no pamtopam-specific command-line options. In particular, do not invent an output option or an input filename position. The common libnetpbm options may be recognised by the installed program, but they are not needed for this copy operation.

$ pamtopam < /path/to/source.ppm > /path/to/output.pam
$ printf 'exit status: %s\n' "$?"
exit status: 0

3. Verify the result is PAM

Use file for a quick format check:

$ file /path/to/output.pam
/path/to/output.pam: Netpbm PAM image file, size = 640 x 480

The dimensions and wording depend on the input and your file version. The useful evidence is that the result is identified as a Netpbm PAM image and retains the expected dimensions.

For a script or a closer inspection, read the beginning of the output. PAM files start with the magic number P7 followed by a header:

$ head -n 8 /path/to/output.pam
P7
WIDTH 640
HEIGHT 480
DEPTH 3
MAXVAL 255
TUPLTYPE RGB
ENDHDR

Do not assume that every output header has exactly these values. A greyscale source can produce depth 1 and a different tuple type; a higher-precision source can have another maximum value. Check the fields against what the source image actually contains.

4. Keep a failed conversion from destroying the old file

Shell redirection opens and truncates its destination before pamtopam starts. That makes this command risky when /path/to/output.pam already contains a useful image:

$ pamtopam < /path/to/source.ppm > /path/to/output.pam

If the source is corrupt or unreadable, the old destination may already have been replaced by an incomplete file. Use a temporary name in the same directory, verify it, then rename it:

$ pamtopam < /path/to/source.ppm > /path/to/output.pam.new
$ file /path/to/output.pam.new
/path/to/output.pam.new: Netpbm PAM image file, size = 640 x 480
$ mv /path/to/output.pam.new /path/to/output.pam

5. Diagnose input and output failures

For an input error, check the path and readability without changing anything:

$ ls -l /path/to/source.ppm
$ test -r /path/to/source.ppm && echo readable
readable

A message such as bad magic number means the first bytes do not identify a PBM, PGM, PPM or PAM image. It can also mean that a text file, compressed file or unrelated binary was supplied. Do not fix that by renaming the file. Identify its real format first, then use the appropriate converter or decompress it before invoking pamtopam.

When the command exits non-zero, treat the output as untrusted. Check the status and inspect the temporary file before using it in another image tool:

$ pamtopam < /path/to/source.ppm > /path/to/output.pam.new
$ status=$?
$ printf 'pamtopam status: %s\n' "$status"
pamtopam status: 0
$ test "$status" -eq 0 && file /path/to/output.pam.new

Do not run this conversion as root to hide a permissions problem. Check directory permissions and ownership instead. If the output directory is managed by a service or shared with other users, agree on its ownership and replacement policy before changing files there.

6. Know when pamtopam is the wrong tool

pamtopam is a narrow format adapter, not a general image editor. Use it when the next program specifically needs a true PAM image. If you need a more general PAM or PNM translation, the manual points to pamchannel. If the next program accepts the original PBM, PGM or PPM directly, passing the original may be simpler and avoids a conversion step.

The output is binary image data even though its PAM header is readable text. Do not edit it in a text editor, pipe it through a command that changes whitespace, or assume that copying the header alone copies the image. Keep the original input until the consumer has accepted the converted file.