Convert a PBM Image to a CMU Window Manager Bitmap

pbmtocmuwm converts a Portable Bitmap into the binary format the old CMU window manager used. The command writes to standard output, so the safe workflow is redirect, then verify non-empty and the right dimensions. Allow ten minutes for a small image.

This guide describes the Netpbm 11.5.2 build installed here, from package version 2:11.05.02-1.1build1. The local manual page is dated 15 April 1989, and documents a stable core interface: one optional input file, no command-specific options, CMU bitmap out.

1. Check the command and input

Confirm which executable your shell will run. This is an ordinary read-only check, no elevated privileges needed:

$ command -v pbmtocmuwm
/usr/bin/pbmtocmuwm
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

PBM is a monochrome, two-colour format. Netpbm accepts its plain form, magic number P1, and its raw form, magic number P4. The file name is only a convention: the contents, not a .pbm suffix, identify the format.

$ file /path/to/input.pbm
/path/to/input.pbm: Netpbm PBM image data, size 4 x 3
$ test -r /path/to/input.pbm && echo 'input is readable'
input is readable

The wording from file differs between distributions. You're checking for a PBM image and plausible dimensions, not matching an exact sentence.

2. Convert to a new CMU bitmap file

Give the input path as the only argument and redirect standard output to a new destination:

$ pbmtocmuwm /path/to/input.pbm > /path/to/output.cmu

• No progress message on success. That's normal.
• Output is binary, not text. Don't open it in an editor or expect a readable header.
• Input is read only. This command never alters it.

Verify the result immediately:

$ test -s /path/to/output.cmu && echo 'CMU bitmap was written'
CMU bitmap was written
$ wc -c /path/to/output.cmu
17 /path/to/output.cmu

The byte count tracks the image dimensions. For the 4 by 3 sample used here, the converter produced a 16-byte CMU header plus one byte of bitmap data: don't treat that total as universal. The useful check is simply that the command succeeded and the destination is non-empty.

3. Use standard input in a pipeline

With no file argument, pbmtocmuwm reads the PBM image from standard input, which suits a Netpbm pipeline:

$ pbmfile=/path/to/input.pbm
$ cat "$pbmfile" | pbmtocmuwm > /path/to/output.cmu
$ test -s /path/to/output.cmu && echo 'pipeline output is non-empty'
pipeline output is non-empty

For a single file, passing the path directly is easier to audit later. Use the pipeline form when another program is genuinely producing the PBM data, or when the input is already on standard input. Keep the final redirection: drop it and binary bytes hit your terminal.

A minimal generated PBM makes a safe smoke test with no real image at risk:

$ printf 'P1\n# 4 by 3 test\n4 3\n0 1 0 1\n1 0 1 0\n0 0 1 1\n' > /tmp/test.pbm
$ pbmtocmuwm /tmp/test.pbm > /tmp/test.cmu
$ wc -c /tmp/test.cmu
17 /tmp/test.cmu

That only touches files under /tmp. Remove them once you're done if they're no longer useful.

4. Avoid destroying an existing output

Shell redirection with > truncates its destination before the converter even starts, which is destructive if that destination already holds a useful bitmap. Prefer a temporary name and swap it in only after the conversion and checks succeed:

$ pbmtocmuwm /path/to/input.pbm > /path/to/output.cmu.new
$ test -s /path/to/output.cmu.new
$ mv -- /path/to/output.cmu.new /path/to/output.cmu

The mv is the point where the old destination actually gets replaced. If conversion fails, leave the old output alone and remove only the incomplete temporary file:

$ rm -- /path/to/output.cmu.new

Only run that removal after checking the path: it's irreversible, though it only touches the temporary file here. Don't reach for sudo for a conversion in a directory you own. If the input or destination is protected, fix the directory permissions or pick a user-writable working directory instead of running the converter as root.

5. Understand the small option surface

The manual defines no options specific to pbmtocmuwm. It recognises common libnetpbm options, but none of those resize the image, select a CMU variant, or turn the output into text. In particular, don't go looking for an output-file option: the destination is standard output, and shell redirection chooses the file.

The installed binary does accept --version, useful when a script needs to record the implementation:

$ pbmtocmuwm --version 2>&1 | head -4
pbmtocmuwm: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pbmtocmuwm: Built from source dated 2024-03-31 09:09:47
pbmtocmuwm: Built by Debian

That diagnostic is a property of this installed build, not an extra conversion mode documented by the old command-specific manual page.

6. Diagnose failures without guessing

If the input path is wrong or unreadable, the command exits non-zero and reports the failed open:

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

If the file isn't valid PBM, Netpbm may report a read or format error and may already have written a partial output file, which is exactly why the temporary destination in step 4 matters. Delete or quarantine the partial .new file, keep the original input, and fix the PBM producer before trying again.

If a command appears to succeed but the destination is zero bytes, check the shell command and its status right away:

$ pbmtocmuwm /path/to/input.pbm > /path/to/output.cmu.new
$ status=$?
$ printf 'converter status: %s\n' "$status"
converter status: 0

Don't inspect binary output with a text filter and assume corruption. Use test -s, wc -c, the PBM dimensions you supplied, and a CMU window manager or later tool that actually supports this bitmap format. pbmtocmuwm converts the representation; it doesn't display the image or validate how a particular window manager will use it.