Convert a PBM image to CompuServe RLE with pbmtocis

You will convert a PBM bitmap into a CompuServe RLE file, choose the converter's black or white padding, and check the result by converting it back to PBM. 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 does not 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

The option summary from pbmtocis --help points to the manual rather than printing a full usage screen. Read man pbmtocis if you need to compare a different package version. The installed manual documents 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 output to a new destination:

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

The optional positional argument is the PBM input file. Leaving it out and using redirection is equivalent:

$ 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

These commands create or truncate output.cis. If that name might already contain a useful file, use a temporary name in the same directory 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

Do not run the mv until the test succeeds. If conversion fails, leave the existing output alone and inspect the error; remove the incomplete .new file only when you are certain it is disposable.

3. Understand the fixed output sizes

CompuServe RLE output is fixed at either 128 by 96 pixels or 256 by 192 pixels. The installed program chooses between those sizes from the input dimensions. A small PBM becomes 128 by 96; an input wider or taller than that uses 256 by 192. Anything beyond 256 by 192 is cropped at the right or bottom. An input smaller than the selected size is padded.

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 in PBM format, not the original four-by-three geometry. The converter has padded it to the required fixed size. The head command reads only the textual PBM header; do not treat the binary pixel data that follows as terminal text.

Checkpoint: if the dimensions are wrong for the receiving system, do not try to force a size with an undocumented pbmtocis flag. Prepare the PBM with pamcut or pnmpad first, then convert it. The manual specifically recommends those tools for finer control of size adjustment.

4. Choose the padding colour

When the input does not fill the selected fixed canvas, padding is black by default. Use -w to request white padding:

$ 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 it cannot show the padding colour. Inspect the round-tripped PBM with an image viewer or another PBM tool when the border matters. The -w option affects padding only; it does not invert foreground pixels.

5. Invert foreground and background mapping when required

Use -i when the receiving application expects the opposite mapping of PBM foreground and background:

$ 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 are unsure which polarity the target expects, produce both variants and compare round-tripped images before sending one to a legacy system. You can combine the options, 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 verifies that the output is readable as CompuServe RLE and exposes 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 is not readable. Check those conditions without changing anything:

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

If the PBM is larger than 256 by 192, expect cropping and a warning. Keep the original PBM if those pixels matter, and use pamcut deliberately before conversion. If the output looks inverted, rerun with -i and compare the round-trip images. If the border is wrong, rerun with or without -w.

A successful exit status proves that the command completed, not that the target device will interpret polarity or padding as 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.