Convert a PBM Bitmap into a Sun Icon with pbmtosunicon

You will turn a monochrome PBM image into a Sun icon file that SunView and related tools can read. The command writes the icon to standard output, so you can save it beside the source, inspect its header and convert it back for a basic check. Allow about ten minutes for a small, known-good PBM file.

This guide uses the installed Netpbm 11.5.2 package. The pbmtosunicon(1) manual page is dated 30 January 2011, so the version check below matters if you are comparing another host.

1. Check the command and the PBM input

Use an ordinary user account. Converting an image does not need sudo, and running the converter as root will not make an invalid PBM valid. The input may be a file or standard input.

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

The version output includes build details after the first line on this machine. Your package may format those lines differently. The useful check is that the command exists and reports a Netpbm version.

A PBM is a one-bit image. For a quick test, create a small plain PBM in a temporary or working path that you control:

$ mkdir -p /tmp/sunicon-example
$ printf 'P1\n4 3\n0 1 0 1\n1 0 1 0\n0 0 1 1\n' > /tmp/sunicon-example/test.pbm
$ file /tmp/sunicon-example/test.pbm
/tmp/sunicon-example/test.pbm: Netpbm image data, size 4 x 3, ASCII bitmap

In a real workflow, replace the example path with your existing .pbm file. Keep the original readable until the output has been checked.

2. Convert the PBM into a Sun icon

Redirect standard output to a new destination. The converter does not choose an output filename for you.

$ pbmtosunicon /tmp/sunicon-example/test.pbm > /tmp/sunicon-example/test.icon
$ printf 'exit=%s\n' "$?"
exit=0
$ wc -c /tmp/sunicon-example/test.icon
99 /tmp/sunicon-example/test.icon

The exact byte count depends on the image dimensions. A zero exit status means that this conversion completed. It does not prove that the source contained the picture you intended, so continue to inspect the result.

Sun icons produced by this program use a textual header followed by hexadecimal data. Read only the header and a little data when checking it:

$ sed -n '1,4p' /tmp/sunicon-example/test.icon
/* Format_version=1, Width=16, Height=3, Depth=1, Valid_bits_per_item=16
 */
        0x0140,0x0280,0x00c0

The installed converter stores the width in 16-pixel units. A four-pixel input therefore produces a Sun icon whose header says Width=16, with unused bits completing each row. For a 17-pixel input, the installed 11.5.2 command reports Width=32. Do not mistake this format padding for a resize operation.

3. Use standard input when the PBM is in a pipeline

The optional pbmfile argument can be omitted. This is useful when another tool emits PBM data or when you want to avoid making an intermediate input copy.

$ cat /tmp/sunicon-example/test.pbm | pbmtosunicon > /tmp/sunicon-example/from-stdin.icon
$ cmp /tmp/sunicon-example/test.icon /tmp/sunicon-example/from-stdin.icon
$ printf 'exit=%s\n' "$?"
exit=0

cmp prints nothing when the files are identical. The pipe is ordinary shell behaviour, not a special pbmtosunicon option. If the producer fails, inspect its exit status separately; a converter result alone cannot explain an upstream failure.

4. Round-trip the icon to verify its structure

Netpbm's companion sunicontopnm reads a Sun icon and writes a Netpbm image. Use it as a structural check, not as a promise that a viewer will display every historical Sun icon exactly as expected.

$ sunicontopnm /tmp/sunicon-example/test.icon > /tmp/sunicon-example/roundtrip.pbm
$ printf 'exit=%s\n' "$?"
exit=0
$ head -n 2 /tmp/sunicon-example/roundtrip.pbm
P4
16 3

The reverse converter emits raw PBM here, and the width reflects the padded Sun icon width. That is expected for the four-pixel demonstration input. For a production file, compare the dimensions and inspect the round-tripped image with a Netpbm viewer or another trusted image tool.

5. Avoid overwriting an existing icon

Shell redirection with > truncates its destination before the converter starts. Do not point it at the only copy of a useful icon unless replacement is intentional.

$ pbmtosunicon /path/to/source.pbm > /path/to/new.icon.tmp
$ test -s /path/to/new.icon.tmp
$ mv /path/to/new.icon.tmp /path/to/output.icon

The temporary file is replaced into place only after the command has succeeded and produced non-empty output. If conversion or the size check fails, leave the existing output.icon alone and remove the incomplete temporary file with rm -- /path/to/new.icon.tmp after checking its path. That removal is irreversible, so verify the filename before running it.

6. Diagnose the common failures

If the command reports that it cannot open the input, check the path and permissions without changing them:

$ ls -l /path/to/source.pbm
$ test -r /path/to/source.pbm && echo readable
readable

If it reports a PBM parsing error, inspect the magic number and dimensions. Raw PBM begins with P4; plain PBM begins with P1. Both are valid forms described by pbm(5). A missing or malformed width, height or raster is an input problem, not a reason to add arbitrary flags.

The manual defines no options specific to pbmtosunicon. It accepts common libnetpbm options, but the conversion itself is selected by the input and output streams. In particular, --version is useful for identifying the installed build, while --help on this package only points back to the manual page. Do not invent an output filename option or pass a destination as a second positional argument.

There is no service to restart and no system configuration to edit. If a downstream application rejects the generated file, keep the original PBM, inspect the Sun header, and try the round-trip check before changing permissions or invoking elevated privileges.