Convert a PBM Bitmap to a Bennet Yee Face File with pbmtoybm

You will finish with a YBM file that can be consumed by the face and xbm programs associated with Bennet Yee's face format. The conversion uses pbmtoybm from Netpbm 11.5.2, installed here as package version 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. It does not alter the input image, install anything, or require elevated privileges.

1. Check the installed command

Confirm the executable and the library version before relying on examples. These 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

The exact build information can differ on another host. The -version option is a common Netpbm option, not a converter-specific feature. It reports the linked libnetpbm version and stops without converting an image.

2. Check that the input is a PBM image

pbmtoybm accepts one optional input filename. A PBM file is a black-and-white raster, not a greyscale or colour image. Its portable bitmap header is normally P1 for plain text or P4 for the raw binary form.

Inspect the file without modifying 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

The file result is only a quick indication. If it reports a different image type, convert that image to PBM first. A common trap is supplying a PGM or PPM file because it also belongs to the wider Netpbm family. The converter expects PBM input, so check the magic number and dimensions rather than trusting a .pbm suffix.

3. Write the YBM output

Pass the PBM path as the 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 the command completed successfully. YBM output is a compact binary face file, so a generic file result such as data is not a failure. Do not open it in a text editor or expect it to begin with a human-readable image header.

4. Verify the dimensions and round trip

The companion ybmtopbm command can decode the result. It is a useful local check because it proves that the output is recognisable as a YBM file and preserves the bitmap dimensions:

$ 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 sample dimensions are illustrative: use the dimensions printed by your own files. The process substitution keeps the comparison temporary and does not alter either PBM file. pnmtoplainpnm normalises the PBM representation so that a plain-versus-raw encoding difference does not look like an image difference.

If your shell does not support process substitution, write the normalised files beneath a temporary directory and compare them:

$ 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'

The trap removes only the temporary directory when the shell exits. It does not remove the source, the YBM result, or any other path.

5. Use standard input in a pipeline

With no filename, pbmtoybm reads the PBM image from standard input. This is useful when another Netpbm program produces the bitmap:

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

Use a pipeline only when the upstream command really produces PBM. The command name in this example is deliberately a placeholder for a PBM-producing step: substitute a verified command for your workflow and check its output format first. A diagnostic such as bad magic number means the first input bytes were not a recognised PNM image, often because a text error message or the wrong image format entered the pipe.

The converter writes its YBM bytes to standard output and diagnostics to standard error. Keep those streams separate. Redirecting both into the same file can corrupt the binary result if an error message is emitted.

6. Handle failures without guessing

There are no command-line options specific to pbmtoybm. It does recognise common libnetpbm options such as -quiet, and the long form with two hyphens is accepted for common options. Quiet mode suppresses informational messages, but it does not repair invalid input or change the YBM format.

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

Always capture the status before running another command if a script needs it. For a missing file, malformed PBM header, or wrong image type, keep the diagnostic on screen and fix the source rather than accepting a partial output file. A failed redirection may still leave an empty or incomplete destination, so remove that destination only when you have confirmed it is the file created by this attempted conversion.