Convert a CompuServe RLE Image to PBM with cistopbm

cistopbm is the Netpbm tool for turning an old CompuServe RLE image into a PBM bitmap. This guide gets you a checked, correctly-sized conversion without clobbering anything on the way, using the installed Netpbm 11.5.2 command on Debian or Ubuntu.

Allow about ten minutes when the input file is already sitting there. You need a readable CompuServe RLE file, a shell, and the netpbm package. No elevated privileges are needed to convert in a directory you can write to, and the command never touches the input file.

1. Confirm the installed command

Check the executable and package version before trusting the examples below. These are ordinary read-only commands:

$ command -v cistopbm
/usr/bin/cistopbm
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ cistopbm --version
cistopbm: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
...

The installed manual describes cistopbm as reading a CompuServe RLE file and writing a PBM image, with the command form cistopbm [-i] [cisfile]. Package version and diagnostic text can differ on another distribution, so treat this as a checkpoint rather than a test you copy verbatim.

2. Check the input without changing it

Set a shell variable to the exact input path. Quoting it protects against spaces and shell metacharacters in a file name:

$ input='/path/to/image.cis'
$ test -r "$input" && echo 'input is readable'
input is readable
$ ls -lh -- "$input"
-rw-r--r-- 1 you you 12K Sep 22 10:15 /path/to/image.cis

Replace /path/to/image.cis with your own path; the suffix is only a naming convention. If test -r prints nothing, stop and fix the path or permissions. Don't reach for sudo as a first response: it can hide an ownership problem and is unnecessary when the file is genuinely readable.

Checkpoint: the input exists, is readable, and is not the file you're about to create. Keep it until you've checked the converted PBM.

3. Convert to a new PBM file

cistopbm's normal output route is standard output, so redirect it to a new destination with a name that doesn't already hold anything you'd miss:

$ output='/path/to/image.pbm.new'
$ cistopbm -- "$input" > "$output"
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ file -- "$output"
/path/to/image.pbm.new: Netpbm image data, size = 128 x 96, rawbits, bitmap

The -- makes the end of cistopbm's options explicit. The input argument is optional in the synopsis, but naming it makes the source obvious and stops the command accidentally consuming unrelated standard input.

Do not redirect straight to an existing PBM unless replacing it is deliberate: shell redirection truncates the destination before cistopbm has finished writing. The .new suffix gives you a safe checkpoint. If conversion fails, the old output survives untouched, even though the new file may be incomplete.

4. Inspect the PBM header and dimensions

Use file as a quick format check, and read the header with a Netpbm-aware tool if one's installed. PBM output can be plain text or raw binary, so don't just cat the whole file into a terminal:

$ file -- "$output"
/path/to/image.pbm.new: Netpbm image data, size = 128 x 96, rawbits, bitmap
$ pnminfo -- "$output"
 ...

The exact pnminfo wording depends on the installed Netpbm build. What you actually need is confirmation that the file is recognised as PBM and its dimensions match what you expect. If pnminfo isn't installed, file alone still gives a useful first check, and a PBM viewer or another Netpbm program can give you a visual one.

PBM is a one-bit bitmap format, not a colour one, so a successful conversion will never preserve colour information the source never had.

5. Replace the destination only after checking it

Once the new PBM has the right dimensions and looks correct, move it into place. This changes the directory, so keep the original input and make a backup if the destination already exists:

$ cp --preserve=all -- /path/to/image.pbm /path/to/image.pbm.bak
$ mv -- "$output" /path/to/image.pbm
$ file -- /path/to/image.pbm
/path/to/image.pbm: Netpbm image data, size = 128 x 96, rawbits, bitmap

If there was no old image.pbm, skip the backup command. mv is normally an ordinary user command; it can fail if the directory isn't writable, but don't add sudo blindly, since a root-owned output can make later maintenance harder.

To recover from a bad replacement, remove the new destination only after confirming its exact path, then restore the backup:

$ rm -- /path/to/image.pbm
$ mv -- /path/to/image.pbm.bak /path/to/image.pbm

Warning: rm is irreversible. Check pwd and the full path before running it. If you're unsure, leave the backup in place and pick a different output name instead.

6. Read from standard input when needed

With no cisfile argument, cistopbm reads the RLE stream from standard input. That's useful in a pipeline, but keep the source and output paths visible so a later reader can audit the command:

$ cat -- "$input" | cistopbm > /path/to/image-from-stdin.pbm
$ file -- /path/to/image-from-stdin.pbm
/path/to/image-from-stdin.pbm: Netpbm image data, size = 128 x 96, rawbits, bitmap

For a regular file, passing the path directly is simpler and gives clearer errors. Avoid a pipeline when you need to tell a failed producer from a failed converter and your shell doesn't report pipeline status. Either way, keep the source file until the output has been checked.

7. Use inverse mapping only when the result needs it

The -i option reverses the foreground and background mapping to black and white. It does not rotate, resize or otherwise improve the image:

$ cistopbm -i -- "$input" > /path/to/image-inverted.pbm
$ file -- /path/to/image-inverted.pbm
/path/to/image-inverted.pbm: Netpbm image data, size = 128 x 96, rawbits, bitmap

Compare the inverted output against the ordinary conversion in an image viewer or another PBM-capable tool. Don't overwrite the first output just to test the option; if the image already looks right, leave out -i.

8. Diagnose the likely failures

A missing input path normally produces a non-zero exit status and an error from the program or shell. Recheck ls -l -- "$input" and test -r "$input". A zero-byte or unexpectedly small output usually means the conversion failed or the source wasn't the file you thought it was; check the exit status before you open it.

If the output is recognised as PBM but looks wrong, verify the source format and try both ordinary and inverse mapping as separate files. A valid PBM header proves nothing about whether the pixels are semantically correct. Keep the original RLE file and use a viewer or comparison process appropriate to your archive.

cistopbm is a converter, not a package manager or a service: no daemon restart, no configuration file. Install or repair the netpbm package through your normal system-management process only when the command or its supporting tools are genuinely absent.

Done means