Convert PAM Images to PNG with pamrgbatopng

pamrgbatopng converts a PAM image to PNG, and the name is a fossil.

The tool it names was folded into a newer one years ago, but the old binary still works.

Allow about ten minutes. You need a shell, a readable Netpbm image and the netpbm package. The workflow is unprivileged: do not use sudo unless your input directory or chosen output directory is genuinely inaccessible to your account.

1. Check which command you have

pamrgbatopng is an old name. The manual describes it as replaced by pamtopng, and says the replacement was introduced in Netpbm 10.70. On this machine, the installed package is Netpbm 11.5.2 and the old name is a symbolic link to the new executable:

$ command -v pamrgbatopng
/usr/bin/pamrgbatopng
$ readlink -f /usr/bin/pamrgbatopng
/usr/bin/pamtopng
$ pamrgbatopng --version 2>&1 | head -n 1
pamrgbatopng: Using libnetpbm from Netpbm Version: Netpbm 11.5.2

The version output is useful when comparing machines. The historical pamrgbatopng interface takes an optional input file and writes PNG to standard output. Because the installed name now resolves to pamtopng, this particular version also accepts the newer program's options. Use the documented pamtopng name when you need those extra controls, so a reader can see which interface the command actually depends on.

2. Convert an existing PAM file

Pass the input path as the optional argument and redirect standard output to a new PNG file:

$ pamrgbatopng /path/to/input.pam > /path/to/output.png

There is normally no progress display. A successful command writes the PNG bytes to output.png and returns status zero. Verify both facts immediately:

$ printf 'converter status: %s\n' "$?"
converter status: 0
$ file /path/to/output.png
/path/to/output.png: PNG image data, ...

The exact dimensions and colour description vary with the input, so do not copy the sample file line literally. The result that matters is a non-empty file identified as PNG.

3. Use standard input for a pipeline

With no input filename, the command reads the PAM image from standard input, which is convenient when another Netpbm program produces the image:

$ pam-producing-command | pamrgbatopng > output.png
$ file output.png
output.png: PNG image data, ...

Keep the output redirection outside the pipeline. It makes the destination obvious and leaves the converter's exit status available to a shell script. For a script that must stop when either stage fails, enable pipeline failure handling before running it:

set -o pipefail
pam-producing-command | pamrgbatopng > output.png
status=$?
printf 'pipeline status: %s\n' "$status"

If your producer emits a PPM, PGM or PBM image rather than PAM, the installed pamtopng documentation says those Netpbm formats are accepted too. The name pamrgbatopng is historical; it does not mean the input file must have a particular filename extension.

4. Make a safe test image

You can test the local installation without touching an existing file. This command generates a one-row RGB PAM image in memory and sends it straight to the converter:

$ pamseq -tupletype=RGB 3 255 -min=0,64,128 -max=255,192,255 -step=255,128,127 \
    | pamrgbatopng > /tmp/pamrgbatopng-test.png
$ file /tmp/pamrgbatopng-test.png
/tmp/pamrgbatopng-test.png: PNG image data, 8 x 1, 8-bit/color RGB, non-interlaced

The explicit tuple type matters: a PAM image with three planes but an empty tuple type is not automatically treated as RGB by this installed converter. The test also uses maxval 255, one of the maxvals accepted by pamtopng. The temporary PNG can be viewed or deleted after checking it; nothing in the package or system configuration changes.

5. Do not overwrite a useful result accidentally

$ pamrgbatopng /path/to/input.pam > /path/to/output.png.new
$ file /path/to/output.png.new
/path/to/output.png.new: PNG image data, ...
$ mv -- /path/to/output.png.new /path/to/output.png

Only run the final mv after the verification succeeds. If conversion fails, remove the incomplete output.png.new and the original output stays untouched:

$ rm -- /path/to/output.png.new

6. Diagnose the failures that look like success

An input path error is straightforward:

$ pamrgbatopng /path/to/missing.pam > output.png
pamrgbatopng: Unable to open file '/path/to/missing.pam' for reading. ...

Check the path and permissions without changing anything:

$ ls -l -- /path/to/missing.pam
$ test -r /path/to/input.pam && echo readable

• An unsupported maxval message means the PAM samples use a value the PNG converter cannot consume directly. The installed pamtopng manual lists 1, 3, 15, 255 and 65535 as supported maxvals. Convert the image with an appropriate Netpbm tool such as pamdepth, then retry, rather than guessing at a scale factor. Preserve the source while investigating.
• An unrecognised or empty tuple type message is a description problem in the PAM header, not a reason to rename the file. Inspect the producer and make it emit a meaningful type such as RGB where that is genuinely what the samples contain. Do not label arbitrary three-plane data as RGB merely to silence the error.

Finally, inspect the output dimensions and colour model, not just the exit status. A successful conversion proves the program produced output; it does not prove the producer described the pixels correctly. Keep the original PAM until the PNG has been opened and checked in the application that will use it.