Convert Netpbm Images to GIF with pamtogif

pamtogif takes a Netpbm image and writes it out as a GIF, and most of the ways it can surprise you come down to the format's 256-colour ceiling. This guide covers the conversion itself, that colour limit, transparency, comments, and the options most likely to produce an unexpected result. Allow about ten minutes if the input file is ready.

You need the netpbm package and a readable PAM, PPM, PGM or PBM-compatible input. The examples use Netpbm 11.5.2, installed here as Debian package version 2:11.05.02-1.1build1. Behaviour can differ in older releases: pamtogif was introduced in Netpbm 10.37, -aspect in 10.38, and -noclear in 10.82.

1. Check the installed converter

Confirm which executable your shell will run. This is an ordinary, unprivileged check:

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

The version command prints build information and exits. The manual page is the reliable option reference for this installed tool. Do not use sudo for image conversion unless the input or output directory is deliberately restricted by your system administrator.

2. Convert one image without risking an existing file

pamtogif reads the named Netpbm file and writes the GIF to standard output. Redirect that output to a new filename:

$ pamtogif /path/to/input.ppm > /path/to/output.gif

The input is not changed. The shell creates or truncates the destination before pamtogif starts, however, so > can destroy an existing GIF. Choose a new destination or use a temporary file when replacing something valuable:

$ pamtogif /path/to/input.ppm > /path/to/output.gif.new
$ file /path/to/output.gif.new
/path/to/output.gif.new: GIF image data, version 87a, ...
$ mv /path/to/output.gif.new /path/to/output.gif

The last command replaces the old output only after conversion and inspection succeed. If conversion fails, remove the incomplete output.gif.new and the original output remains in place. Do not run the mv until the new file is the one you actually want to keep.

3. Check the GIF format and colour count

A GIF image block has one colour map and can hold at most 256 colours. If the input has more, reduce it before conversion with pnmquant:

$ pnmquant 256 /path/to/input.ppm > /path/to/input-256.ppm
$ pamtogif /path/to/input-256.ppm > /path/to/output.gif
$ file /path/to/output.gif
/path/to/output.gif: GIF image data, version 87a, ...

pnmquant creates a quantised Netpbm image on standard output. Keep that intermediate file until the GIF has been checked. The conversion can also use a colour map generated separately, which avoids building the palette twice when several images share it:

$ pnmcolormap 256 /path/to/input.ppm > /tmp/input-colormap.ppm
$ pamtogif /path/to/input.ppm -mapfile=/tmp/input-colormap.ppm > /path/to/output.gif

A map file is an ordinary PPM image whose distinct colours become the GIF palette. It is not a special palette-only file. The input and map file must have matching colour-component depth. If they might not, use pnmremap with the same map file first, then pass the remapped image to pamtogif. Keep temporary map files in a directory with suitable permissions if the image is sensitive.

4. Choose interlacing and repeatable palette order

Use -interlace when the GIF should be stored as an interlaced image:

$ pamtogif -interlace /path/to/input.ppm > /path/to/interlaced.gif
$ file /path/to/interlaced.gif
/path/to/interlaced.gif: GIF image data, version 87a, ...

Interlacing affects how a decoder receives rows. It does not resize the image or reduce its colour count.

Use -sort when you need a predictable palette order for comparison or analysis:

$ pamtogif -sort /path/to/input.ppm > /path/to/sorted.gif

This sorts colours by red value, then green, then blue. It is not the GIF format's separate flag for a palette ordered by visual importance. Do not use it as a compression switch; it does not promise a smaller file.

5. Handle transparency deliberately

If the Netpbm input has an alpha tuple type such as RGB_ALPHA, pamtogif carries its transparent pixels into the GIF. One palette entry is reserved for transparency, leaving at most 255 opaque colours. Inspect the input first if the distinction matters:

$ pamfile /path/to/input.pam

For a simple colour-key conversion, specify a colour:

$ pamtogif -transparent=white /path/to/input.ppm > /path/to/white-transparent.gif

By default, if that colour is absent, the nearest colour in the image is selected using RGB distance. That can make an almost-white background transparent when you expected no match at all. Require an exact match by adding the extra equals sign:

$ pamtogif -transparent==white /path/to/input.ppm > /path/to/exact-transparent.gif

With the exact form, no pixel becomes transparent if the specified colour is not present. Supplying -transparent also tells the program to ignore alpha information in the input, so do not combine the two approaches accidentally. For alpha-derived transparent pixels, -alphacolor=black selects the foreground colour a viewer may use when it does not show the background through; black is the default.

6. Add metadata only when it is useful

GIF comments are optional and cause GIF89 output. Quote the value when it contains spaces:

$ pamtogif -comment="thumbnail generated from source.ppm" /path/to/input.ppm > /path/to/commented.gif
$ file /path/to/commented.gif
/path/to/commented.gif: GIF image data, version 89a, ...

Transparency also requires GIF89. A plain conversion with neither feature normally produces GIF87. Older readers may not understand GIF89, so add comments or transparency only when the recipient actually needs them.

-aspect=FRACTION records the pixel width-to-height ratio for decoders that use it. The default is square pixels, or 1.0. GIF accepts values from 0.25 to 4, with the installed program also supporting its documented extension up to 4 14/64; values outside the accepted range fail. Most decoders ignore this metadata, so do not use it as a resize operation.

Common traps

If the command cannot open the input, check the path and read permission:

$ ls -l /path/to/input.ppm
$ test -r /path/to/input.ppm && echo readable

If the output is rejected by another program, verify its type and dimensions with file, then inspect it with a trusted image viewer. A zero-length or partial GIF usually means the input was invalid, the destination could not be written fully, or the shell created a new file before the converter reported an error. The safe temporary-file pattern from step 2 lets you recover without restoring the source image.

For unusual compression requirements, -noclear omits GIF clear codes and may produce a larger file. The default is to use clear codes. -nolzw writes an uncompressed GIF stream and is mainly historical; it generally makes the file larger. Neither option fixes a colour-count or transparency mistake.