Convert PNG Images Safely with pngtopnm

You will finish with a reproducible way to convert a PNG into a Netpbm PNM file, check the result, and choose what happens to transparency. The command is installed as part of Netpbm 11.5.2 on the system used for this guide. Allow about ten minutes. You need a shell, a readable PNG file, and enough disk space for the uncompressed output.

pngtopnm is a compatibility name rather than the preferred new interface. Netpbm introduced pngtopam in version 10.44, and from version 10.48 pngtopnm is an alias for it. The older name remains useful in scripts and existing instructions, but new work should normally use pngtopam, especially when you need a PAM file containing an alpha channel.

1. Check the installed command

Start by confirming which executable is being used and which Netpbm release it reports:

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

The version output contains build details as well as the release. Your path or release may differ. If the command is missing, install the Netpbm package through your distribution's normal package-management process. That is an administrative action and is deliberately not included as a copy-and-paste command here.

2. Convert a PNG to PNM

Use an explicit input path and redirect standard output to a new destination. Replace the example paths with your own files:

$ pngtopnm /path/to/input.png > /tmp/output.pnm
$ pnmfile /tmp/output.pnm
/tmp/output.pnm: PPM raw, 16 by 16  maxval 255

When you omit an option, the foreground image is written and transparency information is discarded. The output subtype depends on the input: black and white becomes PBM, greyscale becomes PGM, and colour becomes PPM. A PNM file is uncompressed, so check the available space before converting a large image.

The redirection creates or replaces /tmp/output.pnm. This is the first destructive boundary in the workflow: do not point it at an original image or an important existing output. If you need to undo this example, remove only the generated file after checking its path:

$ test /tmp/output.pnm && rm -- /tmp/output.pnm

The rm command is irreversible for that pathname. The safer recovery is to choose a fresh output name for each trial.

3. Verify conversion and failure handling

Inspect the PNM header without opening it in an image viewer:

$ pnmfile /tmp/output.pnm
/tmp/output.pnm: PPM raw, 16 by 16  maxval 255

The exact dimensions and subtype come from your image. A valid PNM header begins with P1 through P6; the common raw colour result is P6. For a script, test the converter before using the output:

if pngtopnm -- /path/to/input.png > /tmp/output.pnm; then
    pnmfile /tmp/output.pnm
else
    status=$?
    printf 'pngtopnm failed with status %s\n' "$status" >&2
    exit "$status"
fi

The double hyphen separates the options from the input name. It is useful when a path begins with a hyphen, although an absolute path is usually clearer. If conversion fails, do not pass the partial file to another program. Write to a temporary name in the same directory, validate it, and then rename it only if the next stage requires an atomic hand-off.

4. Choose how transparency is handled

There are three relevant modes in the legacy command. They are mutually exclusive:

• With no mode, write only the foreground image. Transparency is lost.
• --alpha writes the transparency channel or mask as PBM or PGM. The main image is not written.
• --mix composites the foreground against a background and writes the result as PNM.

For a PNG with an alpha channel, extract that channel separately when another tool needs a mask:

$ pngtopnm --alpha /path/to/input.png > /tmp/mask.pgm
$ pnmfile /tmp/mask.pgm
/tmp/mask.pgm: PGM raw, 16 by 16  maxval 255

The subtype may be PBM when the transparency is only on or off. Do not expect this command to produce one file containing both colour and alpha. That is the job of the newer pngtopam --alphapam option:

$ pngtopam --alphapam /path/to/input.png > /tmp/with-alpha.pam
$ head -n 7 /tmp/with-alpha.pam
P7
WIDTH 16
HEIGHT 16
DEPTH 4
MAXVAL 255
TUPLTYPE RGB_ALPHA
ENDHDR

Only use this expected header for an RGBA PNG. A greyscale image produces GRAYSCALE_ALPHA and a different depth. If you need to retain transparency for later Netpbm processing, prefer this PAM route on current Netpbm.

5. Composite against a known background

--mix uses the PNG's bKGD chunk when present. If the image has no such chunk, the default background is white. Set it explicitly when the colour matters:

$ pngtopnm --mix --background=rgb:01/ff/80 /path/to/input.png > /tmp/composited.ppm
$ pnmfile /tmp/composited.ppm
/tmp/composited.ppm: PPM raw, 16 by 16  maxval 255

The colour syntax is handled by Netpbm's colour parser. The three hexadecimal components above are red, green and blue. --background requires --mix on current releases. Supplying it alone is an error, so keep the pair together in scripts.

Do not use compositing as a reversible way to preserve an alpha channel. Once the foreground has been mixed with a background, the original transparency cannot be recovered from that PPM alone. Keep the source PNG if you may need another background later.

6. Handle gamma and metadata deliberately

By default, Netpbm ignores the PNG's image-gamma information and treats the samples as suitable for Netpbm output. The --gamma=value option asks the PNG library to apply gamma handling, but it also applies a display-oriented screen-gamma transformation. That can change pixel values in ways that are surprising in a data pipeline. Use it only when you have a defined colour requirement and have compared the result with a known reference.

To inspect the input while converting, add --verbose. It reports image dimensions, colour type and PNG chunks on standard error while the PNM remains on standard output. To write PNG text chunks to a separate file, use --text=/path/to/metadata.txt. To print the PNG time chunk, use --time. These options do not put PNG metadata into the PNM pixels.

$ pngtopnm --verbose /path/to/input.png > /tmp/output.pnm 2> /tmp/pngtopnm.log
$ sed -n '1,12p' /tmp/pngtopnm.log
pngtopnm: reading a 16 x 16 image, 8 bits
pngtopnm: truecolor+alpha, not interlaced, base filter

Keep diagnostic output separate from binary image data. Mixing standard error into the redirected PNM with 2>&1 can corrupt the file.