Build a Motif UIL icon from a PNM image with pamtouil

You will turn a PNM or PAM image into a Motif UIL source file containing an exported icon and its colour table. The examples use the installed Debian Netpbm 11.5.2 build, take roughly five minutes, and do not need root access. You need pamtouil, a readable input image, and a destination where you can create a text file.

1. Check the installed command

Confirm which executable will run before you spend time diagnosing an example. This is an ordinary, read-only command:

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

The version output also reports build details on this installation. The command accepts a PNM or PAM image and writes UIL to standard output. It does not install a Motif toolkit or compile the UIL for you.

Checkpoint: if command -v prints nothing, install the Netpbm package using your distribution's normal package process, then repeat this check. Do not use sudo for the conversion itself.

2. Create or choose a small PNM image

For a repeatable first run, create a tiny plain PPM file in a temporary directory. This file has four pixels and uses the portable PNM text format:

$ work_dir=$(mktemp -d)
$ printf 'P3\n2 2\n255\n255 0 0   0 255 0\n0 0 255   255 255 255\n' > "$work_dir/icon.ppm"
$ file "$work_dir/icon.ppm"
/tmp/tmp.example/icon.ppm: Netpbm image data, size = 2 x 2, rawbits, pixmap

Replace the illustrative /tmp/tmp.example part in expected output with the actual temporary path. If you already have a PGM, PPM, or PAM file, use its path instead. Keep the input and output paths distinct until you have checked the result.

Checkpoint: inspect the input before conversion if it came from elsewhere. A valid image should have the expected dimensions and format; a damaged or unexpectedly large file is a reason to stop and investigate.

3. Convert the image and choose the UIL name

Use -name when the generated module, colour table, and icon identifiers should be stable regardless of the input filename. Redirect standard output to a new file:

$ pamtouil -name=demo "$work_dir/icon.ppm" > "$work_dir/demo.uil"
pamtouil: computing colormap...
pamtouil: looking up color names, assigning character codes...
pamtouil: generating UIL...

There are two separate output streams here. The diagnostics are printed on standard error, while the UIL source is redirected into demo.uil. The option may also be written as --name demo; the installed manpage permits two hyphens and whitespace between an option and its value.

This operation creates a file but does not overwrite the input. If you chose an existing output path, stop before running the command and move that file aside first. Recovery is simple when you use a new path: remove only the generated file and rerun the conversion.

4. Verify the generated UIL

Read the first part of the output and check that the requested identifier appears in all the expected places:

$ sed -n '1,80p' "$work_dir/demo.uil"
module demo
version = 'V1.0'
names = case_sensitive
include file 'XmAppl.uil';

value
    Red : color( 'Red' );
    White : color( 'White' );
    Green : color( 'Green' );
    Blue : color( 'Blue' );

Continue far enough to find demo_rgb and demo_icon. The colour names come from the RGB database used by Netpbm. An input colour that is not an exact database match is assigned the closest named colour, so the generated palette is not a lossless record of every source RGB value.

$ grep -E '^(module|  demo_rgb|demo_icon)' "$work_dir/demo.uil"
module demo
  demo_rgb : color_table (
demo_icon : exported icon( color_table = demo_rgb,

Checkpoint: the module and icon names should match the value you supplied to -name. If the file is empty, the redirection hid the useful result: rerun the command without redirection once, then correct the input path or format reported by the diagnostics.

5. Use filenames or a pipeline deliberately

When -name is absent, pamtouil derives the prefix from the input filename without its extension. A file named badge.ppm therefore produces identifiers beginning with badge. This default is convenient for one-off conversions but can make a build change when a file is renamed.

For standard-input data, the default prefix is noname. Supply a name explicitly when the result will be included by another UIL source:

$ cat "$work_dir/icon.ppm" | pamtouil -name=pipedicon > "$work_dir/pipedicon.uil"
$ grep -E '^(module|pipedicon)' "$work_dir/pipedicon.uil"
module pipedicon
pipedicon_icon : exported icon( color_table = pipedicon_rgb,

Do not assume that the first line of diagnostics is the UIL output. In a pipeline, keep the image on standard input and the UIL on standard output, then verify the destination file separately.

6. Handle transparency and common failures

A PAM image may contain grayscale or colour data, with or without a transparency channel. Where transparency is present, pamtouil treats a pixel that is more than half transparent as transparent in the output. Pixels at or below that threshold are not described as transparent by the local manual, so test edge values if that distinction matters to your icon.

The most common failures are mundane: the input path is wrong, the file is not a supported PNM or PAM image, or the output was redirected somewhere unexpected. Check the path and format first:

$ test -r /path/to/input.pam && echo readable
$ file /path/to/input.pam
$ pamtouil -name=check /path/to/input.pam > /tmp/check.uil
$ test -s /tmp/check.uil && echo 'UIL output is non-empty'

A failed conversion can leave a partial output file because the shell creates the redirection target before the program runs. Treat that file as unusable: choose a fresh destination for the next attempt, or remove the known partial file after confirming its path. No service restart, privilege escalation, or policy change is part of this workflow.