Convert a Xerox Brush File to PBM with brushtopbm

Somewhere you have found a Xerox doodle brush file, and brushtopbm is the Netpbm tool that turns it into a portable bitmap you can actually view. It reads one brush file, or standard input, and writes the PBM image to standard output without touching the source. Allow about ten minutes.

You need Netpbm, a readable brush file, a shell, and somewhere safe to write the result. The examples use Netpbm 11.5.2 from Debian package netpbm 2:11.05.02-1.1build1. The format is old and uncommon, so this guide also covers recognising input that is not a valid brush file.

1. Check the installed command

Confirm which executable your shell will run and record the package version. These are ordinary read-only commands and need no sudo:

$ command -v brushtopbm
/usr/bin/brushtopbm
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ brushtopbm --version 2>&1 | sed -n '1,2p'
brushtopbm: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
brushtopbm: Built from source dated 2024-03-31 09:09:47

The manual does not define a brushtopbm-specific option list. It says the program accepts common libnetpbm options, which is why --version works here. Do not assume an option from another Netpbm converter applies to this one.

2. Keep the source and destination separate

Choose a new destination name before converting. Shell redirection with > truncates an existing destination before the program even starts, so a failed conversion can destroy a previous PBM. Write a new file in the current directory:

$ ls -l /path/to/example.brush
$ brushtopbm /path/to/example.brush > example.pbm
$ printf 'exit status: %s\n' "$?"
exit status: 0

A zero status means the read and write completed; it does not prove the image is the one you intended. Keep the original brush file until you have inspected the PBM.

If example.pbm already holds useful data, write to a temporary name and replace the old file only after checking the new one:

$ brushtopbm /path/to/example.brush > example.pbm.new
$ file example.pbm.new
$ mv example.pbm.new example.pbm

The mv changes the destination only after conversion has succeeded. If conversion fails, leave the old PBM in place and remove the incomplete example.pbm.new once you have confirmed it is the failed output; that removal is irreversible, so do not add it blindly to a script.

3. Verify the PBM header and dimensions

Use file to check the result is a PBM and read its dimensions:

$ file example.pbm
example.pbm: Netpbm image data, size = 96 x 64, rawbits, bitmap

The dimensions come from the brush file, not a command-line resize setting. Output normally begins with the binary PBM magic number P4, followed by width and height. For a more direct header check, look at the first few bytes:

$ xxd -l 16 -g 1 example.pbm
00000000: 50 34 0a 39 36 20 36 34 0a ...  P4.96 64.

Do not treat the pixel bytes as text. A PBM in raw format has binary row data after the header, so a text editor can show misleading characters or alter the image if you save it.

$ test -s example.pbm && echo 'PBM output is non-empty'
PBM output is non-empty

4. Use standard input for a pipeline

The brush-file argument is optional. Without it, brushtopbm reads standard input, which is useful when an archive or another program produces the brush bytes. Keep a copy first if the input is valuable:

$ cat /path/to/example.brush | brushtopbm > example-from-stdin.pbm
$ file example-from-stdin.pbm
example-from-stdin.pbm: Netpbm image data, size = 96 x 64, rawbits, bitmap

The shorter redirection form is clearer when the source is already a file:

$ brushtopbm < /path/to/example.brush > example-from-stdin.pbm

There is no pbmtobrush companion in the documented Netpbm toolset. Treat this conversion as one-way: keep the original brush file if you might need it again.

5. Diagnose a rejected or suspicious input

A Xerox doodle brush file is not a PBM with a different filename. The installed converter expects a 16-byte header, including a magic value and two big-endian dimensions, followed by padded bitmap rows. A file with a random extension, a truncated header, or the wrong byte order is not a safe test input.

When the command fails, first check the path and read permission without changing anything:

$ ls -l /path/to/example.brush
$ test -r /path/to/example.brush && echo readable
readable
$ brushtopbm /path/to/example.brush > example.pbm.new
brushtopbm: Error reading a row of data from brushfile

The exact diagnostic depends on where the input ends. A non-zero exit status and an incomplete output mean the input needs investigating, not that sudo is required: elevation cannot repair a malformed or truncated brush file.

The program may also warn about extraneous data at the end of an otherwise readable file. Treat that as a format or acquisition problem: compare the file with the producer's original copy, and do not silently discard the extra bytes in a batch conversion.

6. Preview or convert the result separately

brushtopbm only does the brush-to-PBM conversion. For a PNG or another display format, use a separate installed Netpbm or image tool once the PBM checks pass:

$ pnmtopng example.pbm > example.png
$ file example.png
example.png: PNG image data, 96 x 64, 1-bit colormap, non-interlaced

If pnmtopng is not installed, keep the verified PBM or use the image tools already approved for your system. Do not install packages or run a conversion as root merely to preview a user-owned image. If the PBM looks wrong, return to the input and dimension checks rather than deleting the source.