Convert PAM Images to PNG Without Losing Transparency

You will finish with a repeatable command for converting a Netpbm image to PNG, including a PAM image with an alpha channel. The examples were checked with Netpbm package version 2:11.05.02-1.1build1, whose installed pamtopng accepts PBM, PGM, PPM and PAM input.

Allow about ten minutes. You need a shell, pamtopng and a readable input image. These are ordinary user commands: no root access or service restart is needed. The guide writes new output files, so choose an output path you control and do not overwrite an original until you have checked the result.

1. Check the installed tool

Confirm that the command and package are the ones you expect:

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

The manpage is the useful interface reference here. It permits a minimum unique option abbreviation, double hyphens, and whitespace in place of an equals sign. Prefer full option names in scripts, because abbreviations can become ambiguous after an upgrade.

Checkpoint: make sure the input is actually a Netpbm file before converting it:

$ pamfile /path/to/input.pam
/path/to/input.pam: PAM ...

The details after the colon depend on the file. If pamfile reports another Netpbm type, that is still valid input. If the file is not Netpbm data, use an appropriate importer first rather than guessing at its header.

2. Convert a normal image to PNG

Give the input filename as the final argument and redirect standard output to a new PNG:

$ pamtopng /path/to/input.pam > /path/to/output.png
$ file /path/to/output.png
/path/to/output.png: PNG image data, ...

With no input filename, pamtopng reads standard input. That makes it useful in a pipeline:

$ pamfile /path/to/input.ppm
$ pamtopng < /path/to/input.ppm > /path/to/output.png
$ identify /path/to/output.png
/path/to/output.png PNG ...

Do not use > on the original file. The shell truncates the destination before the converter can read it, which can destroy the source. If a conversion fails, inspect the error and write to a different temporary or recovery path; do not repeatedly retry against a damaged original.

3. Check maxval before troubleshooting PNG output

pamtopng supports only input maxval values of 1, 3, 15, 255 and 65535. A file with another maxval is rejected. Inspect the header with pamfile; for a PAM file, the MAXVAL line is also visible with a read-only command such as:

$ sed -n '1,12p' /path/to/input.pam
P7
WIDTH 640
HEIGHT 480
DEPTH 4
MAXVAL 255
TUPLTYPE RGB_ALPHA
ENDHDR

If the maxval is unsupported, normalise a copy with pamdepth, then feed that copy to pamtopng:

$ pamdepth 255 /path/to/input.pam > /tmp/input-255.pam
$ pamtopng /tmp/input-255.pam > /tmp/output.png
$ file /tmp/output.png
/tmp/output.png: PNG image data, ...

This changes the sample precision in the copy. It does not alter the source. Use a destination under /tmp or another directory with enough space, and remove temporary files later according to your local retention policy.

When conversion requires scaling, the PNG colour components are written at 8 or 16 bits and pamtopng records the original bit depth in an sBIT chunk. That metadata describes the conversion; it does not make an unsupported maxval acceptable without conversion first.

4. Preserve a PAM alpha channel

The practical reason to prefer pamtopng over the older pnmtopng is PAM transparency. A PAM with tuple type RGB_ALPHA becomes a PNG with an alpha channel. Verify the result with an image inspector:

$ pamtopng /path/to/rgba.pam > /tmp/rgba.png
$ file /tmp/rgba.png
/tmp/rgba.png: PNG image data, ..., 8-bit/color RGBA, non-interlaced
$ identify -verbose /tmp/rgba.png | grep -E 'Type:|Alpha:'
  Type: TrueColorAlpha
    Alpha:

Exact dimensions, byte counts and the verbose alpha statistics vary with the input. The useful check is that the output is RGBA or otherwise reports an alpha channel. A plain PPM has no alpha channel, so converting it cannot create transparency that was not present in the input.

pamtopng always produces a colour PNG from a colour PAM, even when every pixel happens to be grey. If file size or a greyscale PNG matters, convert the input to a greyscale Netpbm type with the relevant Netpbm tool before running pamtopng, and check that doing so does not discard transparency you need.

5. Add colour and transparency metadata deliberately

Use -transparent when every pixel of one exact colour should be fully transparent. The value uses Netpbm colour syntax:

$ pamtopng -transparent=rgb:ff/00/0d input.ppm > output-transparent.png
$ identify -verbose output-transparent.png | grep -E 'Type:|Alpha:'
  Type: PaletteAlpha
    Alpha:

Unlike some behaviour associated with pnmtopng, pamtopng does not choose a nearby colour when the requested colour is absent. Check the image's actual samples if the result appears unchanged. Use -background=white to add a background colour chunk for later transparency conversions; it is metadata for consumers, not a command to flatten the image.

For true PPM or PGM input, -gamma=.45 records the usual Netpbm gamma information. Use another value only when the source really uses another transfer function. -srgbintent takes one of perceptual, relativecolorimetric, saturation or absolutecolorimetric and records an sRGB rendering intent.

The -chroma value contains eight numbers, in the order white, red, green and blue, with each colour represented by its CIE-1931 X and Y chromaticities. Quote it so the shell passes one argument:

$ pamtopng -chroma='0.3127 0.3290 0.6400 0.3300 0.3000 0.6000 0.1500 0.0600' input.ppm > output-colour.png

Do not copy those numbers as a universal calibration. They are an example of the syntax; use values supplied for your real source.

6. Choose interlace and metadata files with care

-interlace writes Adam7 interlacing. It can improve progressive display over a slow connection, but pamtopng then holds the entire image in memory instead of one raster row at a time. For large images, leave it off unless progressive display is a real requirement. This option was added in Netpbm 10.86, so it is present in the installed version.

PNG text chunks come from files, not from arbitrary extra command-line words. -text=FILE writes uncompressed tEXt chunks, -ztxt=FILE writes compressed zTXt chunks, and -itxt=FILE writes iTXt entries with language and translated-key fields. The file format is line-oriented: an entry starts in column one, continuation lines start with whitespace, and the key comes first.

$ cat > /tmp/png-text.txt <<'EOF'
Title PNG conversion test
Description
 A PNG made from a PAM image
EOF
$ pamtopng -text=/tmp/png-text.txt input.pam > output-with-text.png
$ identify -verbose output-with-text.png | grep -A2 -i 'properties:'

The here-document writes only a temporary metadata file. Review any text before embedding it in an image: PNG metadata is easy to copy elsewhere and can disclose names, paths or internal project details.