Convert PBM Images to Sun Icons with the Legacy pbmtoicon Alias

You will convert a PBM bitmap into a Sun icon, check that the output is really a Sun icon, and keep the original image intact. On this machine the command comes from Netpbm 11.5.2, and /usr/bin/pbmtoicon is a symbolic link to pbmtosunicon.

Allow about ten minutes. You need a shell, the Netpbm package, and a readable PBM file. The examples only read an image and write a new output file, so they do not need sudo. This guide does not edit system icons or install anything.

1. Confirm which command you have

pbmtoicon is retained for compatibility. Netpbm replaced it with pbmtosunicon in release 10.53, first released in December 2010. Check the installed package and the alias before putting the old name into a script:

$ command -v pbmtoicon
/usr/bin/pbmtoicon
$ readlink -f /usr/bin/pbmtoicon
/usr/bin/pbmtosunicon
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ pbmtoicon --help
pbmtoicon: Use 'man pbmtoicon' for help.

The help response is a reminder that this is an old compatibility name, not evidence that conversion failed. The dedicated manpage has no conversion options of its own. Its synopsis shows one optional positional argument, although it calls that argument iconfile; in the installed alias, that argument is the input PBM file, as it is for pbmtosunicon.

2. Inspect the PBM before converting it

Keep the source image somewhere safe and check that it is readable. file gives a quick format and dimension check; it does not alter the image:

$ INPUT='/path/to/input.pbm'
$ test -r "$INPUT" && echo 'input is readable'
input is readable
$ file "$INPUT"
/path/to/input.pbm: Netpbm image data, size 128 x 64, ASCII bitmap

Replace the placeholder with your real path. Quote it even when it currently contains no spaces. A PBM is a black-and-white bitmap, not a general colour image. If file reports a PGM, PPM or unrelated format, convert it to PBM with an appropriate Netpbm tool first rather than guessing what pbmtoicon will do.

For a repeatable test without an existing image, create a small temporary PBM. This changes only a file under /tmp:

$ TEST_PBM=$(mktemp /tmp/pbmtoicon-test.XXXXXX.pbm)
$ printf 'P1\n8 4\n0 1 0 1 0 1 0 1\n1 0 1 0 1 0 1 0\n0 0 1 1 0 0 1 1\n1 1 0 0 1 1 0 0\n' > "$TEST_PBM"
$ file "$TEST_PBM"
/tmp/pbmtoicon-test.XXXXXX.pbm: Netpbm image data, size 8 x 4, ASCII bitmap

3. Write a new Sun icon

Pass the PBM path as the optional argument and redirect standard output to a new destination. The command writes the Sun icon to standard output, so the shell redirection is what creates the output file:

$ OUTPUT='/path/to/output.icon'
$ pbmtoicon "$INPUT" > "$OUTPUT"
$ file "$OUTPUT"
/path/to/output.icon: Sun rasterfile, ...

The exact description from file can vary with its version, but it should identify a Sun rasterfile or Sun icon rather than a PBM. The output is a Sun-format icon. The command does not resize the picture, add colour or choose a modern desktop icon format.

$ TEMP_OUTPUT='/path/to/output.icon.new'
$ pbmtoicon "$INPUT" > "$TEMP_OUTPUT"
$ file "$TEMP_OUTPUT"
$ cp --preserve=all "$OUTPUT" "$OUTPUT.bak"
$ mv "$TEMP_OUTPUT" "$OUTPUT"
$ file "$OUTPUT"
/path/to/output.icon: Sun rasterfile, ...

If conversion fails, remove the incomplete .new file after checking its path. The old output remains in place. If the replacement is wrong, restore the backup with mv "$OUTPUT.bak" "$OUTPUT". That restore is the undo path; do not delete the backup until you have inspected the replacement.

4. Use standard input when that fits a pipeline

With no input filename, the alias reads the PBM from standard input and still writes the icon to standard output. This makes it suitable for a controlled pipeline:

$ pbmtoicon < "$INPUT" > "$OUTPUT"
$ test -s "$OUTPUT" && echo 'icon output is non-empty'
icon output is non-empty

Using an explicit input path is easier to review, especially in scripts. In either form, check the exit status before treating the output as usable:

$ if pbmtoicon "$INPUT" > "$TEMP_OUTPUT"; then
>   echo 'conversion succeeded'
> else
>   status=$?
>   echo "conversion failed with status $status" >&2
> fi
conversion succeeded

Do not use a failed or empty output as a replacement for a known-good icon. A successful exit status means the converter completed; it does not prove that the bitmap looks the way you intended.

5. Verify by converting the icon back

Netpbm's sunicontopnm reads the result. Its output can be sent through pnmtoplainpnm to make the pixels and dimensions easy to inspect:

$ sunicontopnm "$OUTPUT" | pnmtoplainpnm
P1
16 4
0000010101010000
0000101010100000
0000001100110000
0000110011000000

Sun icon storage rounds each row to whole 16-bit words. That is why the eight-pixel test image becomes a 16-pixel PBM when decoded: the extra pixels are padding. With a real image, compare the decoded dimensions and visible pattern with the source rather than expecting every byte to match a PBM file. If the reverse conversion cannot read the result, keep the source and the previous output, then investigate the command and paths.

Remove only temporary test files when you are finished. Do not remove an original PBM or the backup until the icon has been opened by the program that will consume it.

6. Know the boundary of the old name

The historical pbmtoicon interface is for producing Sun icons from PBM input. The replacement command, pbmtosunicon, is the name to use in new documentation and scripts because it says which icon format is involved. It also has newer functionality, including support for converting a depth-8 Sun icon to a PGM image on the reverse side of the tool family. That does not turn pbmtoicon into a generic icon converter.

Do not confuse the generated icon with a file that an ordinary Linux desktop necessarily uses. Sun raster icons are an old interchange format. If a modern application expects PNG, SVG or an icon theme directory, use the format and packaging rules documented by that application after you have verified this conversion.