Build a Motif UIL Icon from a PNM Image with pamtouil

pamtouil turns a PNM or PAM image into a Motif UIL source file with an exported icon and its colour table. It is niche toolkit glue you need once every few years and forget the details of every time. Expect roughly five minutes, no root access, and the installed Debian Netpbm 11.5.2 build. 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.

2. Create or choose a small PNM image

For a repeatable first run, create a tiny plain PPM file in a temporary directory. This one 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 your actual temporary path. Already have a PGM, PPM, or PAM file? Use its path instead, and keep the input and output paths distinct until you have checked the result.

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 land on standard error, while the UIL source goes 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 creates a file but does not touch the input. If you picked 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 everywhere it should:

$ 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' );

Keep going far enough to find demo_rgb and demo_icon. The colour names come from the RGB database Netpbm uses, and an input colour that is not an exact database match gets 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,

5. Use filenames or a pipeline deliberately

• No -name? pamtouil derives the prefix from the input filename without its extension, so badge.ppm produces identifiers beginning with badge. Convenient for one-off conversions, but a rename can quietly change a build.
• Standard input gets 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 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 check the destination file separately.

6. Handle transparency and common failures

A PAM image may carry grayscale or colour data, with or without a transparency channel. Where transparency exists, 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: wrong input path, unsupported format, or output redirected somewhere unexpected. Check 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: pick a fresh destination for the next attempt, or remove the known partial file once you have confirmed its path. No service restart, privilege escalation, or policy change belongs in this workflow.