Turn a PBM Bitmap into a Face File with pbmtoybm

Bennet Yee's face format predates most desktops you have used, and pbmtoybm is still the tool for making one from a plain PBM bitmap. The result is a YBM file that the face and xbm programs can read directly. The conversion uses pbmtoybm from Netpbm 11.5.2, installed here as package 2:11.05.02-1.1build1.

Allow about ten minutes. You need a shell, the Netpbm package, and a monochrome PBM image. This guide only reads the source and writes a new output file: no installing, no elevated privileges, and the input image never changes.

1. Check the installed command

Confirm the executable and library version before trusting anything that follows. Both are ordinary read-only commands:

$ command -v pbmtoybm
/usr/bin/pbmtoybm
$ pbmtoybm -version
pbmtoybm: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pbmtoybm: Built from source dated 2024-03-31 09:09:47
pbmtoybm: Built by Debian

Build details can differ on another host, that is normal. -version is a common Netpbm option rather than something specific to this converter: it reports the linked libnetpbm version and stops without converting anything.

2. Check that the input is really a PBM

pbmtoybm takes one optional input filename. A PBM file is black-and-white, not greyscale or colour, and its header is normally P1 for plain text or P4 for raw binary.

Look at the file without touching it:

$ file INPUT.pbm
INPUT.pbm: Netpbm image data, size 64 x 64, rawbits, bitmap
$ sed -n '1,5p' INPUT.pbm
P1
# small example
4 3
0 1 0 0

file only gives you a quick steer. If it names a different image type, convert to PBM first: a common trap is feeding in a PGM or PPM by mistake, since they all live in the same Netpbm family. Check the magic number and dimensions rather than trusting a .pbm suffix on faith.

3. Write the YBM output

Pass the PBM path as the one optional argument and redirect standard output to a new file:

$ pbmtoybm INPUT.pbm > OUTPUT.ybm
$ printf 'converter status: %s\n' "$?"
converter status: 0
$ file OUTPUT.ybm
OUTPUT.ybm: data

A zero status means it worked. YBM is a compact binary face file, so a generic file result of data is not a failure, it is what you should expect. Do not open it in a text editor or wait for a human-readable header that is never coming.

4. Verify the dimensions with a round trip

The companion ybmtopbm command decodes the result, which makes it a good local check: it proves the output is a recognisable YBM file and that the bitmap dimensions survived.

$ ybmtopbm OUTPUT.ybm > ROUNDTRIP.pbm
$ head -3 ROUNDTRIP.pbm
P4
4 3
$ cmp <(pnmtoplainpnm INPUT.pbm) <(pnmtoplainpnm ROUNDTRIP.pbm)
$ printf 'round-trip status: %s\n' "$?"
round-trip status: 0

The dimensions above are illustrative, use whatever your own files print. Process substitution keeps the comparison temporary and leaves both PBM files untouched. pnmtoplainpnm normalises the representation first, so a plain-versus-raw encoding difference does not masquerade as a real image difference.

No process substitution in your shell? Write the normalised files under a temporary directory instead and compare those:

$ workdir=$(mktemp -d)
$ trap 'rm -rf "$workdir"' EXIT
$ pnmtoplainpnm INPUT.pbm > "$workdir/input.pbm"
$ pnmtoplainpnm ROUNDTRIP.pbm > "$workdir/roundtrip.pbm"
$ cmp "$workdir/input.pbm" "$workdir/roundtrip.pbm"
$ echo 'bitmap content matches'

trap here removes only the temporary directory on exit. It does not touch the source, the YBM result, or anything else.

5. Use standard input in a pipeline

With no filename, pbmtoybm reads the PBM image from standard input, handy when another Netpbm command produces the bitmap on the fly:

$ pnmcrop INPUT.pbm | pbmtoybm > CROPPED.ybm
$ ybmtopbm CROPPED.ybm | head -3
P4
64 64

Only pipe into this when the upstream command genuinely produces PBM. The command name above is a placeholder for whatever PBM-producing step you actually have: verify its output format before wiring it up for real. A bad magic number diagnostic means the first input bytes were not a recognised PNM image, often because a text error message or the wrong format slipped into the pipe.

YBM bytes go to standard output and diagnostics go to standard error. Keep those two apart: redirecting both into the same file can corrupt the binary result the moment an error message gets written.

6. Handle failures without guessing

There are no options specific to pbmtoybm itself, though it recognises common libnetpbm options such as -quiet, with the usual double-hyphen long form accepted too. Quiet mode hides informational messages, it does not repair bad input or change the YBM format.

$ pbmtoybm --quiet INPUT.pbm > OUTPUT.ybm
$ status=$?
$ printf 'converter status: %s\n' "$status"
converter status: 0

Capture the status straight away if a script needs it, before running anything else. For a missing file, a malformed PBM header, or the wrong image type, read the diagnostic and fix the source rather than shipping a partial output. A failed redirection can still leave an empty or incomplete destination behind, so only delete that file once you have confirmed it is the one this attempt created.