Build a Windows ICO from PAM Images with pamtowinicon

You will convert one or more Netpbm PAM images into a Windows icon file, keep the images in a predictable order, and check the result without overwriting a useful file. Allow about fifteen minutes if the PAM input already exists. The examples use Netpbm 11.5.2, installed here as Debian package version 2:11.05.02-1.1build1.

You need a shell, the netpbm package, and an input PAM file. The converter writes binary ICO data to standard output. That detail drives the workflow: redirect output to a new file, then inspect the file with an image-aware command. No step needs elevated privileges unless your input or destination directory is deliberately restricted.

1. Check the installed command

Confirm which executable will run and record the local implementation version:

$ command -v pamtowinicon
/usr/bin/pamtowinicon
$ pamtowinicon --version
pamtowinicon: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pamtowinicon: Built from source dated 2024-03-31 09:09:47

The command's version output includes build details and is written as diagnostic text. Do not redirect it into the icon. The manual says that options may use one or two hyphens, and that an option name can be separated from its value with whitespace or an equals sign. Full option names are clearer in scripts.

2. Check the PAM images and channel meaning

pamtowinicon reads a multi-image PAM file. A PAM file can contain several complete images one after another, with no padding between them. Each image has a header followed by its raster. Use pamfile when it is installed to see the images before conversion:

$ pamfile /path/to/input.pam
PAM file: 64 by 64 by 4 maxval 255
PAM file: 128 by 128 by 4 maxval 255

The exact wording can vary by Netpbm release, but the useful facts are the dimensions and depth. The converter interprets depth as follows:

• Depth 1 is an opaque greyscale image.
• Depth 2 is greyscale with a transparency channel.
• Depth 3 is an opaque colour image.
• Depth 4 is colour with a transparency channel.
• Depth 5 is colour with a transparency channel and a separate Windows AND mask.

The PAM tuple type does not control this interpretation. Depth does. If a file claims RGB_ALPHA but has depth 3, fix the producing step or the PAM header before relying on its transparency. Keep a copy of the original while investigating malformed input.

3. Convert a multi-image PAM file to ICO

Choose a new destination and redirect standard output there:

$ pamtowinicon /path/to/input.pam > /path/to/icon.ico

Every input image becomes one image in the ICO, in the same order. A successful command normally prints nothing because the icon itself is binary standard output. Check the exit status immediately if you are writing a script:

$ printf '%s\n' "$?"
0

A zero status says that conversion completed. It does not prove that the source dimensions or visual content are what you intended, so continue with file inspection.

4. Verify the icon and its image count

Use file for a quick structural check. For the two-image, 2 by 2 RGBA test input used on this machine, the installed command produced:

$ file /tmp/pamtowinicon.ico
/tmp/pamtowinicon.ico: MS Windows icon resource - 2 icons, 2x2, 32 bits/pixel, 2x2, 32 bits/pixel

Your dimensions and bit depth will differ. Look for a Windows icon resource, the expected number of icons, and the expected dimensions. A further check with an image viewer or Windows application is worthwhile when transparency matters. Do not treat a text editor or head as an image validator: an ICO contains binary headers, pixel data and possibly embedded PNG data.

For more detail, add -verbose. It keeps the icon on standard output but reports each encoding decision on standard error:

$ pamtowinicon -verbose /path/to/input.pam > /path/to/icon.ico
pamtowinicon: Image  0: encoding as BMP
pamtowinicon: Image  0:   64 x  64 x 4, 256 colors, alpha channel
pamtowinicon: Image  1: encoding as BMP

The wording and colour count depend on the input. The useful distinction is whether each image was encoded as BMP or PNG and whether an alpha channel was found.

5. Choose PNG encoding for larger images

By default, the threshold is 128. Images with a resolution at or above that threshold are encoded as PNG by running pnmtopng; smaller images use the traditional BMP form. Set a different threshold when the icon set has a deliberate size or compatibility policy:

$ pamtowinicon -pngthreshold=64 /path/to/input.pam > /path/to/icon.ico
$ pamtowinicon -pngthreshold 64 /path/to/input.pam > /path/to/icon-64.ico

Here, resolution means the image dimensions as understood by the program, not the file's byte size. Test the resulting ICO on the consumers that matter to you. When PNG encoding is selected for a five-channel PAM, the separate AND mask is discarded because PNG already carries transparency. Do not choose this mode if that mask has behaviour your target software needs.

6. Handle transparency and the AND mask

For a two- or four-channel input without an explicit AND mask, the program derives the mask from transparency: a transparency sample below maxval is treated as opaque in the AND mask, while a sample at the maximum is transparent. An input with no transparency channel is treated as fully opaque.

Windows uses the AND mask for more than simple alpha. It can affect such things as the icon while it is being dragged. If the background appears inverted or otherwise wrong in older BMP-based handling, try:

$ pamtowinicon -truetransparent /path/to/input.pam > /path/to/icon-transparent.ico

This makes pixels outside the opaque area black. It changes the generated icon, so compare both files in the target environment. The option does not alter the PAM input.

7. Avoid destroying an existing icon

Shell redirection with > truncates its destination before pamtowinicon starts. Do not point it at the only copy of a working icon. Write a temporary sibling and replace the old file only after verification:

$ pamtowinicon /path/to/input.pam > /path/to/icon.ico.new
$ file /path/to/icon.ico.new
$ mv -- /path/to/icon.ico.new /path/to/icon.ico

The final mv is the state-changing step. If conversion or verification fails, leave the original alone and remove the incomplete .new file once you have confirmed its path. If the replacement is wrong, restore a backup or rename the old file back before deleting anything. Do not use sudo merely because the output is an icon; use elevated access only when filesystem permissions require it.