Convert GEM Images to PNM with gemtopnm

gemtopnm turns an old GEM .img file into a Netpbm image other tools can actually open. A one-plane file becomes PBM, a four-plane 16-colour file becomes PPM, and the result lands on standard output, so you redirect it to a file and check what turned up. Budget about ten minutes if the input is ready to go.

This guide covers Netpbm 11.5.2, installed here as Debian package netpbm version 2:11.05.02-1.1build1. The local manual page is dated 30 April 2000, so check your own version before trusting an option word for word.

1. Confirm the command and the input

An ordinary shell account is all this needs: reading the input and writing the output only touches paths your shell can already reach.

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

Then check that the input file is actually there before committing to a conversion:

$ ls -l /path/to/image.img
$ test -r /path/to/image.img && echo readable
readable

2. Convert a GEM file to a new PNM file

Redirect standard output with > to a destination you do not need yet:

$ gemtopnm /path/to/image.img > converted.pnm
$ test -s converted.pnm && echo 'conversion produced data'
conversion produced data

The output filename you choose does not decide the format: that comes from the input's plane count. Use file, or peek at the first two bytes, to see which one you got:

$ file converted.pnm
converted.pnm: Netpbm image data, bitmap, 800 x 600
$ head -c 2 converted.pnm
P4

Your dimensions and file wording will differ. P4 means a binary PBM, P6 means a binary PPM. The header is readable text, but everything after it is binary, so do not treat the whole file as text.

3. Feed it through a pipeline

Give no filename and gemtopnm reads standard input instead. Handy when another command produces the GEM data, or a script already has it flowing:

$ cat /path/to/image.img | gemtopnm > converted.pnm
$ head -c 2 converted.pnm
P6

The same output rule applies: whatever runs before the pipe must leave the GEM bytes alone, and the final redirect must point somewhere disposable. For a plain file on disk, passing the path directly beats piping it through cat for no reason.

4. Inspect a file without writing image output

Add -d when you want a description of the file's contents instead of converted pixels:

$ gemtopnm -d /path/to/image.img

What comes back depends on the file. Treat this as inspection, not conversion: do not save its output as though it were PBM or PPM. Want to keep a diagnostic for later? Send it to its own text file, never to the image destination:

$ gemtopnm -d /path/to/image.img > image-details.txt
$ sed -n '1,20p' image-details.txt

5. Protect an existing output file

A shell redirect with > truncates the destination before gemtopnm even runs. If converted.pnm already matters, write to a new name first and move it into place only once the conversion has actually worked:

$ gemtopnm /path/to/image.img > converted.pnm.new
$ test -s converted.pnm.new
$ file converted.pnm.new
$ mv converted.pnm.new converted.pnm

mv changes state in the current directory, but it needs no root access when you own the files. If the conversion fails, leave the old output alone and clear up only the incomplete temporary file:

$ rm converted.pnm.new

6. Diagnose common failures

An error opening the input usually means a wrong path, an unreadable file, or something that just is not a GEM image. Recheck without changing anything:

$ ls -l /path/to/image.img
$ test -r /path/to/image.img && echo readable || echo 'not readable'

If the command succeeds but the format is not what you expected, look at the input's actual GEM layout. The converter only distinguishes one-plane black-and-white from four-plane 16-colour: it will not resize, repair or reinterpret an arbitrary file, and a .img extension alone proves nothing about its contents.

In scripts, check the exit status right after conversion, then confirm the output is non-empty and has the magic number you expect. A clean exit is useful evidence, not a visual check, so view the image with a trusted tool or pass it to another Netpbm converter once you know what it is.