Convert a PBM Image to CompuServe RLE with pbmtocis

pbmtocis converts a PBM bitmap into a CompuServe RLE file for software that still expects that old format. Allow about fifteen minutes if the input already exists. The examples use Netpbm 11.5.2, installed from the Debian netpbm package.

This is a read-only conversion workflow: it doesn't alter the source image or install anything. You need pbmtocis, cistopbm for the round-trip check, and a shell. Neither command normally needs sudo.

1. Check the installed command

Confirm which executable will run and record the Netpbm version:

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

pbmtocis --help just points to the manual rather than printing a usage screen. Read man pbmtocis if you're comparing a different package version. The installed manual documents exactly two options, -i and -w.

2. Convert a PBM file without overwriting its source

By default, pbmtocis reads PBM from standard input and writes the CompuServe RLE result to standard output. Redirect that to a new destination:

$ pbmtocis /path/to/input.pbm > /path/to/output.cis

The positional argument is optional. Leaving it out and using redirection instead does the same thing:

$ pbmtocis < /path/to/input.pbm > /path/to/output.cis
$ test -s /path/to/output.cis && echo 'RLE output is non-empty'
RLE output is non-empty

Both of those create or truncate output.cis. If that name might already hold something useful, write to a temporary name first and replace the destination only after checking it:

$ pbmtocis /path/to/input.pbm > /path/to/output.cis.new
$ test -s /path/to/output.cis.new && mv /path/to/output.cis.new /path/to/output.cis

Don't run the mv until the test succeeds. If conversion fails, leave the existing output alone, inspect the error, and only remove the incomplete .new file once you're certain it's disposable.

3. Understand the fixed output sizes

CompuServe RLE output is fixed at 128 by 96 pixels or 256 by 192 pixels, and the installed program chooses between the two from your input's dimensions:

• Small PBM in? You get 128 by 96 out.
• Wider or taller than that? You get 256 by 192, and anything beyond that gets cropped at the right or bottom.
• Smaller than the selected size? The converter pads it.

For example, this creates a deliberately small PBM and converts it to the smaller RLE size:

$ printf 'P1\n4 3\n0 1 0 1\n1 0 1 0\n0 0 1 1\n' > /tmp/example.pbm
$ pbmtocis /tmp/example.pbm > /tmp/example.cis
$ cistopbm /tmp/example.cis | head -2
P4
128 96

The cistopbm output above is a verification image, not the original four-by-three geometry: the converter has padded it to the fixed size. head only reads the textual PBM header, so don't treat the binary pixel data after it as terminal text.

4. Choose the padding colour

When the input doesn't fill the selected canvas, padding is black by default. Use -w to request white padding instead:

$ pbmtocis /tmp/example.pbm > /tmp/example-black.cis
$ pbmtocis -w /tmp/example.pbm > /tmp/example-white.cis
$ cistopbm /tmp/example-white.cis | head -2
P4
128 96

The header confirms the fixed geometry but can't show you the padding colour: inspect the round-tripped PBM with an image viewer or another PBM tool when the border matters. -w only affects padding, it doesn't invert foreground pixels.

5. Invert foreground and background mapping when required

Use -i when the receiving application expects PBM foreground and background flipped:

$ pbmtocis -i /tmp/example.pbm > /tmp/example-inverted.cis
$ test -s /tmp/example-inverted.cis && echo 'inverted RLE output is non-empty'
inverted RLE output is non-empty

This is a conversion choice, not a display setting. If you're unsure which polarity the target expects, produce both variants and compare round-tripped images before sending one to a legacy system. The options combine, for example pbmtocis -i -w input.pbm > output.cis.

6. Verify and diagnose the result

The most useful check is a round trip through cistopbm: it confirms the output reads back as CompuServe RLE and shows the selected geometry:

$ cistopbm /path/to/output.cis > /tmp/output-roundtrip.pbm
$ head -2 /tmp/output-roundtrip.pbm
P4
128 96

A missing-input error usually means the path is wrong or the file isn't readable. Check those without changing anything:

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

• PBM larger than 256 by 192? Expect cropping and a warning. Keep the original and use pamcut deliberately beforehand if those pixels matter.
• Output looks inverted? Rerun with -i and compare the round-trip images.
• Border wrong? Rerun with or without -w.

A successful exit status proves the command completed, not that the target device will interpret polarity or padding as you intended. Keep the source and the first checked output until the receiving application has accepted the file. No service restart, root shell or persistent configuration change is part of this workflow.