Convert PBM Files to GEM IMG with pbmtogem

You will finish with a GEM .img file made from a PBM bitmap, plus a quick check that the output is a real, non-empty GEM image. The examples use Netpbm 11.5.2, installed here as Debian package netpbm 2:11.05.02-1.1build1.

Allow about ten minutes. You need a readable PBM file, the pbmtogem command, and write access to the directory where the output will go. This is an ordinary user-level conversion. It does not need sudo, and it does not alter the input.

1. Check the installed command

Confirm which executable your shell will run and record the Netpbm build:

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

Your path and build date may differ. The version output is useful when a conversion behaves differently on another host. Ask for the command's short help if you need a reminder of the local installation:

$ pbmtogem --help
pbmtogem: Use 'man pbmtogem' for help.

2. Inspect the PBM before converting it

Use a read-only check to confirm that the source exists and is recognised as a bitmap:

$ test -r /path/to/source.pbm && echo readable
readable
$ file /path/to/source.pbm
/path/to/source.pbm: Netpbm image data, size = 640 x 480, bitmap, rawbits

The dimensions and the words describing the encoding will vary. A PBM is a black-and-white bitmap, not a greyscale or colour image. If file cannot identify the source, stop and inspect its header rather than feeding an unrelated image format to pbmtogem.

Keep the original file. The converter reads it, but it does not provide an undo operation for a destination that you overwrite.

3. Write the GEM image to a new destination

Pass the PBM path as the only positional argument and redirect standard output to a new file:

$ pbmtogem /path/to/source.pbm > /path/to/output.img
$ test -s /path/to/output.img && echo "GEM output is non-empty"
GEM output is non-empty

pbmtogem writes the compressed GEM image to standard output. It has no command-line options specific to the conversion; the installed manpage says it also accepts options common to libnetpbm programs. The simplest and clearest invocation therefore has one input path and a shell redirection.

Shell redirection truncates an existing destination before the program starts. That is a destructive mistake if output.img already contains a good image. Choose a new name, or use a temporary destination and replace the old file only after verification:

$ pbmtogem /path/to/source.pbm > /path/to/output.img.new
$ test -s /path/to/output.img.new
$ mv /path/to/output.img.new /path/to/output.img

The final mv changes the destination directory and may replace an existing file. Do not run it until the new output has passed the checks below. If conversion fails, leave the original destination alone and remove the incomplete .new file after checking that it is the one you created.

4. Verify the output format and dimensions

Use file for a format-level check. For an 8 by 4 sample bitmap, the installed command produced:

$ file /tmp/sample.img
/tmp/sample.img: GEM Image data 8 x 4, 1 planes, 372 x 372 pixelsize, pattern size 1

Your output may show different dimensions and pixel-size details. Check that it says GEM Image data, that the image dimensions match the PBM, and that the file is non-empty. A successful process exit only says that the command completed; it does not tell you whether you selected the intended input.

If gemtopbm is installed, a round trip gives a stronger smoke test. It reads the GEM file and writes a PBM to standard output:

$ gemtopbm /path/to/output.img > /tmp/output-roundtrip.pbm
$ file /tmp/output-roundtrip.pbm
/tmp/output-roundtrip.pbm: Netpbm image data, size = 640 x 480, rawbits, bitmap
$ head -2 /tmp/output-roundtrip.pbm
P4
640 480

The round-tripped PBM may use a different PBM encoding from the source. Compare the dimensions and inspect the image with a suitable viewer if visual fidelity matters. The manpage records one limitation: pbmtogem cannot compress repeated lines, so a source with repeated rows may produce a larger GEM file than you expect.

5. Convert standard input when a pipeline is useful

The input path is optional, so you can pipe a PBM into the command. This keeps the source in the pipeline and still writes the GEM data to a named file:

$ cat /path/to/source.pbm | pbmtogem > /path/to/output.img
$ file /path/to/output.img
/path/to/output.img: GEM Image data 640 x 480, 1 planes, 372 x 372 pixelsize, pattern size 1

For a normal file, passing the path directly is easier to audit because the input is visible in the command. Use a pipeline when the preceding command genuinely produces PBM data. Do not put diagnostic text from that command into the same stream, because pbmtogem expects PBM input.

6. Diagnose failures without changing the source

A missing or unreadable input usually means the path or permissions are wrong. Check it without elevation:

$ ls -l /path/to/source.pbm
$ test -r /path/to/source.pbm && echo readable

If the destination is empty or absent after a failed conversion, do not treat that as a usable image. Check the exit status immediately after the conversion and keep the source for another attempt:

$ pbmtogem /path/to/source.pbm > /path/to/output.img.new
$ status=$?
$ printf 'pbmtogem exit status: %s\n' "$status"
pbmtogem exit status: 0

Status 0 is necessary but not sufficient, which is why test -s and file follow it. If the input is not a valid PBM, correct the upstream conversion or source file instead of adding sudo. Elevated privileges do not repair an invalid image and can create an output owned by root that you cannot conveniently replace later.