Convert Sun icons to PBM or PGM with sunicontopnm

You will turn a Sun icon file into a Netpbm PBM or PGM image, then verify the output without changing the original. Allow about ten minutes for a known input and a couple of checks. This guide uses the Netpbm 11.5.2 build installed on this machine; older releases can differ, especially before Netpbm 10.53.

1. Check the installed command and input

Start in a working directory where you can create a new output file. You need the netpbm package and a readable Sun icon. No elevated privileges are needed for a normal conversion.

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

The command accepts one optional input filename. With no filename it reads the icon from standard input, which is useful in a pipeline but easier to misread while troubleshooting. Check the path before converting:

$ test -r /path/to/icon && echo "input is readable"
input is readable

Checkpoint: the command is installed, the version is known, and the input is readable. Keep the original icon until you have inspected the converted image.

2. Convert to a new PBM or PGM file

Use shell redirection because sunicontopnm writes the image to standard output. The input is not modified. The safe pattern below uses a temporary destination, then moves it into place only after a successful conversion:

$ sunicontopnm /path/to/icon > converted.pnm.new
$ test -s converted.pnm.new && mv converted.pnm.new converted.pnm

Do not use sudo unless the source or destination directory genuinely requires it. The command has no option for choosing an output filename, and the output type follows the icon data. A normal-depth icon produces PBM. A Depth=8 icon produces PGM. Even a colour Sun icon is represented as PGM because this converter does not retain a colour palette.

Warning: plain > truncates an existing destination before the converter runs. If converted.pnm is valuable, use the .new pattern above. If a failed run leaves the temporary file, inspect its status and remove only that incomplete file:

$ rm -- converted.pnm.new

That removal is irreversible. It does not affect the original icon or an existing converted.pnm.

3. Check the PNM type and dimensions

Use file for a quick check and inspect the first line of the PNM header. PBM uses the magic number P4; PGM uses P5. The dimensions follow on the next header line.

$ file converted.pnm
converted.pnm: Netpbm image data, size = 16 x 8, rawbits, bitmap
$ head -n 2 converted.pnm
P4
16 8

Your file wording may vary. The useful evidence is a non-empty file, a PBM or PGM type, and dimensions that match the icon's actual raster. Do not use a text editor on the whole file: raw PBM and PGM contain binary pixel data after the header.

Sun icon storage is not the same thing as a modern image filename or extension. In particular, a row can be represented in 16-bit units. Do not assume that an icon made from an 8-pixel source must produce an 8-pixel output. Read the dimensions reported by file or the PNM header, then judge whether they are correct for the source format.

4. Select readable output only when needed

Netpbm normally writes raw, binary PNM. Add the common -plain option when you need an ASCII PBM or PGM for inspection or a text-only hand-off:

$ sunicontopnm -plain /path/to/icon > converted-plain.pnm
$ head -n 4 converted-plain.pnm
P1
16 8
0101010101010101
1010101010101010

The exact pixels and dimensions depend on the icon. Plain output is usually much larger, so keep the default raw format for normal processing. The common -quiet option suppresses informational messages on standard error; it does not change the image data.

Checkpoint: the output header says PBM or PGM, the dimensions are plausible, and you know whether you created raw or plain output.

5. Diagnose the common failures

An error about opening the input usually means the path, permissions or filename is wrong. Recheck without changing anything:

$ ls -l /path/to/icon
$ test -r /path/to/icon && echo "readable"

A premature end-of-file or invalid-input error means the file is not a complete Sun icon in the form this program expects. Do not repair it by guessing bytes or by renaming an unrelated XPM, XBM or desktop icon. The Netpbm manual suggests trying xpmtoppm for XPM input and xbmtopbm for XBM input; those are different formats and need their own converters.

If a colour result appears as greyscale, that is expected for sunicontopnm. If you know the icon palette, the manual identifies pamlookup as the next Netpbm tool to use, but you must supply the correct palette yourself. A successful exit status only says that the file was parsed and written; verify the dimensions and view the image before deleting the source.