Build a TeX PK Font from PBM Glyphs with pbmtopk

By the end, you will have a packed TeX font file, ending in .pk, and its matching font metric file, ending in .tfm. The local Netpbm package provides pbmtopk version 2.4. Allow about 15 minutes for a small test font, plus time to prepare the glyph bitmaps.

What pbmtopk produces

pbmtopk reads one or more PBM bitmap images and writes two related files. The PK file stores the packed glyph bitmaps. The TFM file stores TeX's measurements, such as character widths, heights, depths and italic corrections. The third positional argument is the font resolution in dots per inch, not the design size.

The first two arguments are output names. The program appends .pk and .tfm when those suffixes are omitted. Use a separate output directory while experimenting so that an existing font is not replaced accidentally.

Confirm the local version before relying on a script or tutorial written for another Netpbm build.

pbmtopk 2>&1 | head -n 1
dpkg-query -W -f='${Package} ${Version}\n' netpbm

On the package used for this guide, the first command prints pbmtopk: This is PBMtoPK, version 2.4, and the package is netpbm 2:11.05.02-1.1build1. The package version and the program version are different things.

Prepare one glyph

A PBM image is a one-bit bitmap. This deliberately small example draws a capital A and sends it to pbmtopk on standard input. The -c option assigns character number 65, which is the usual code for A. The hyphen at the end tells pbmtopk to read that PBM image from standard input.

Create a working directory and run the conversion there:

mkdir -p "$HOME/pbmtopk-work"
cd "$HOME/pbmtopk-work"
printf 'P1\n5 7\n0 0 1 0 0\n0 1 1 1 0\n1 0 1 0 1\n1 1 1 1 1\n1 0 0 0 1\n1 0 0 0 1\n1 0 0 0 1\n' |
  pbmtopk demo-font 300 -c 65 -

This creates demo-font.pk and demo-font.tfm. The number 300 is the target resolution in dots per inch. It does not resize the bitmap; it tells TeX which device resolution the font is intended for.

test -s demo-font.pk && test -s demo-font.tfm
file demo-font.pk demo-font.tfm

A successful local run reports TeX packed font data for the PK file and TeX font metric data for the TFM file. If either file is absent or empty, stop before using the font and read the diagnostic from pbmtopk.

Add glyph files in order

For ordinary file inputs, put the PBM paths after the options. Each bitmap becomes the next character in the font. Use -c immediately before a bitmap when you need to set that bitmap's character number. Options such as -W, -H, -D, -I, -h, -v, -x and -y apply to the next character encountered.

pbmtopk demo-font 300 \
  -c 65 -W 0.75 -H 0.70 -D 0 -h 6 -x 0 -y 7 glyph-A.pbm \
  -c 66 -W 0.75 -H 0.70 -D 0 -h 6 -x 0 -y 7 glyph-B.pbm

Widths, heights, depths and italic corrections are expressed as multiples of the design size. Horizontal and vertical escapements and offsets are pixel values. A common trap is mixing these units: -W 6 means six design-size units, while -h 6 means six pixels.

The -s option changes the design size, in TeX points. Its default is 1. The TFM parameters are interpreted as multiples of that design size, so choose it with the font's intended TeX use rather than treating it as a bitmap scaling switch.

Use an option file for a larger font

When there are many glyphs, -f reads one line per bitmap. Each line can contain the filename followed by horizontal offset, vertical offset, horizontal escapement, vertical escapement, width, height, depth and italic correction:

# glyphs.opt
=65
glyph-A.pbm 0 7 6 0 0.75 0.70 0 0
glyph-B.pbm 0 7 6 0 * * * *

A line beginning with = changes the character number for the following bitmap. Lines beginning with # or % are ignored. An asterisk, or an omitted attribute, asks pbmtopk to calculate a default from the bitmap where supported. The settings of the per-character options do not affect characters created through the option file.

pbmtopk demo-font 300 -f glyphs.opt

Keep the option file beside the PBM files or use explicit paths. Relative filenames are resolved by the process's current working directory, not by the directory containing the option file. That detail is easy to miss when a build runs from a different directory.

Set font metadata when needed

-C writes a coding-scheme comment in the TFM file, and -F writes a family comment. -p sets the first font parameters. The first seven are slant, interword spacing, stretchability, shrinkability, x-height, quad width and post-sentence extra space. Leave these at their reasonable defaults for a simple bitmap test. Set them deliberately for a font that will be used by TeX, especially if it contains mathematical or symbol glyphs.

pbmtopk demo-font 300 \
  -C 'ASCII' -F 'Demo Bitmap' \
  -c 65 glyph-A.pbm

Input and output safety

No elevated privileges are required. Run as your normal user and write into a directory you own. The program can use - for standard input or standard output, but do not use the same stream for a PBM input and an output file in a pipeline unless you have checked the direction carefully. Named output files make the result easier to inspect.

Before a batch conversion, check that every referenced PBM file exists and that the destination names are the ones you intend to create. If a test produced incorrect files, remove only those named outputs from your working directory and rerun after fixing the input. Do not delete a shared TeX font directory as a cleanup shortcut.

For a final check, inspect the exit status and both files:

set -o pipefail
pbmtopk demo-font 300 -f glyphs.opt
status=$?
printf 'pbmtopk exit status: %s\n' "$status"
test "$status" -eq 0 && test -s demo-font.pk && test -s demo-font.tfm
file demo-font.pk demo-font.tfm