Turn a Xerox Doodle Brush File into a PBM Image with brushtopbm

You will finish with a portable bitmap (PBM) made from a Xerox doodle brush file, plus checks that show whether the conversion really worked. The installed command reads one brush file, or standard input, and writes the PBM image to standard output. It does not edit the source file.

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 the guide also shows how to recognise an 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 do not need 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 that the program accepts common libnetpbm options, which is why --version works in this installation. Do not assume that an option from another Netpbm converter applies here.

2. Keep the source and destination separate

Choose a new destination name before converting. Shell redirection with > truncates an existing destination before the program starts, so a failed conversion can destroy a previous PBM. This example writes 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 that the command completed its read and write operations. It does not prove that the image is the one you intended. Keep the original brush file until the PBM has been inspected.

If example.pbm already contains useful data, use a temporary output and replace the old file only after checking it:

$ 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 the conversion fails, leave the old PBM in place and remove the incomplete example.pbm.new after checking that 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 that the result is a PBM and to 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 from a command-line resize setting. The output normally begins with the binary PBM magic number P4, followed by width and height. If you need a more direct header check, display only 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 contains 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. This is useful when an archive or another program produces the brush bytes, but preserve 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 for operational purposes: keep the original brush file if you may 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 that the input should be investigated, 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 performs the brush-to-PBM conversion. If you need a PNG or another display format, use a separate installed Netpbm or image tool after 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.