Convert a PBM Image to a CMU Window Manager Bitmap

You will convert a Portable Bitmap (PBM) image into the binary bitmap format used by the CMU window manager. The command writes the converted data to standard output, so the safe workflow is to redirect it to a new file and then verify that the file is non-empty and has the dimensions you expected. Allow about ten minutes for a small image. You need the Netpbm package and a readable PBM file.

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

1. Check the command and input

First confirm which executable your shell will run. This is an ordinary read-only check and does not require elevated privileges:

$ 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 both its plain form, whose magic number is P1, and its raw form, whose magic number is P4. The input file name is only a convention: the contents, not a .pbm suffix, identify the format.

Checkpoint: inspect the file without changing it:

$ 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 can differ between distributions. You are checking for a PBM image and plausible dimensions, not 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

A successful run normally prints no progress message. The output is binary, not text, so do not open it in an editor or expect a readable header. The input is read only; this command does not alter 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 depends on the image dimensions. For the 4 by 3 sample used on this machine, the converter produced a 16-byte CMU header followed by one byte of bitmap data. Do not treat that particular total as a universal expected size. The useful first check is that the command succeeded and the destination is non-empty.

3. Use standard input in a pipeline

When no file argument is supplied, pbmtocmuwm reads the PBM image from standard input. That makes it suitable for 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. Use the pipeline form when another program is deliberately producing PBM data or when the input is already arriving on standard input. Keep the final redirection: without it, binary bytes will be sent to your terminal.

A minimal generated PBM is useful for a smoke test without risking a real image:

$ 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

This changes only files under /tmp. Remove those test files when you are finished if they are no longer useful.

4. Avoid destroying an existing output

Shell redirection with > truncates its destination before the converter starts. That is a destructive operation if the destination already contains a useful bitmap. Prefer a temporary name and replace the old file 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 command is the point at which the old destination is replaced. If conversion fails, leave the old output alone and remove the incomplete temporary file:

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

Only run that removal after checking the path. It is irreversible, although it removes just the temporary file in this example. Do not use sudo for a conversion in a directory you own. If the input or destination is protected, fix the directory permissions or choose a user-writable working directory rather than making the converter run as root.

5. Understand the small option surface

The manual defines no options specific to pbmtocmuwm. It recognises common libnetpbm options, but those do not resize the image, select a CMU variant or change the output into text. In particular, do not invent an output-file option: the output destination is standard output and the shell redirection chooses the file.

The installed binary accepts --version, which is 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 additional 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. Check the path and permissions:

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

If the file is not a valid PBM, Netpbm may report a read or format error and may already have written a partial output file. This is why the temporary destination in step 4 matters. Delete or quarantine the partial .new file, keep the original input, and correct 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 immediately:

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

Do not inspect binary output with a text filter and then infer that it is corrupt. Use test -s, wc -c, the PBM dimensions you supplied, and a CMU window manager or later tool that explicitly supports this bitmap format. pbmtocmuwm converts the representation; it does not display the image or validate how a particular window manager will use it.