Build an MPlayer Bitmap Font Raster with pamtompfont

You will convert a Netpbm image into the binary raster used by an MPlayer bitmap font, then verify that the output is a real file and that the input was not changed. The command does not create a complete font package: it writes the raster image only. Allow about fifteen minutes for a first test, plus time to prepare an image arranged to match your font descriptor.

You need the netpbm package, a readable PNM or PAM image, and a writable working directory. The examples below use Netpbm 11.5.2 from Debian package version 2:11.05.02-1.1build1. The installed manual is dated 18 May 2008, so keep the local command and manual as the authority when working on another release.

1. Check the installed command

Confirm the executable and library version before building a pipeline. This is an ordinary read-only check and does not need elevated privileges:

$ command -v pamtompfont
/usr/bin/pamtompfont
$ pamtompfont -version
pamtompfont: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
...
$ dpkg-query -W -f='\${Package} \${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The version command reports the linked libnetpbm version and other build details. Its output is informational; the useful checkpoint is that the command exists and reports the version you expect.

2. Understand what the output represents

pamtompfont reads one PNM or PAM image and writes an MPlayer bitmap font raster to standard output. An MPlayer bitmap font normally has two parts: a descriptor that maps codepoints to rectangles, and one or more raster files containing the pixels. pamtompfont produces the raster file, not the descriptor.

Every glyph in a raster has the same height. The descriptor records the raster file name, each glyph's top-left position, and its width. That means the source image must already be laid out in a way your descriptor understands. Converting an arbitrary photograph succeeds as an image conversion, but it does not make the photograph a usable text font.

Checkpoint: keep the source image and descriptor together, and choose a new destination name. The output is binary data, so do not open it in a text editor or expect file to identify it as a PNM image.

3. Convert an image to a new raster file

Pass the input path as the optional positional argument and redirect standard output to a new file:

$ pamtompfont /path/to/glyph-sheet.pbm > glyph-sheet.mpf

pamtompfont has no command-specific options. It accepts the common Netpbm options, including -quiet and -version. The two-hyphen form is also accepted for common options, so --quiet is equivalent to -quiet.

A successful run normally leaves no conversion report on standard output because standard output is the raster itself. Check both the exit status and the destination:

$ printf 'conversion status: %s\n' "$?"
conversion status: 0
$ test -s glyph-sheet.mpf && printf '%s\n' 'raster is non-empty'
raster is non-empty
$ file glyph-sheet.mpf
glyph-sheet.mpf: data

Run the status command immediately after pamtompfont. If you run another command first, $? describes that later command instead.

4. Make a controlled smoke-test image

If you do not yet have a font sheet, use another Netpbm program to create a small test image. This verifies the conversion path, not the correctness of a production font layout:

$ pbmtext 'Hi' > /tmp/pamtompfont-test.pbm
$ file /tmp/pamtompfont-test.pbm
/tmp/pamtompfont-test.pbm: Netpbm image data, size = 40 x 29, rawbits, bitmap
$ pamtompfont /tmp/pamtompfont-test.pbm > /tmp/pamtompfont-test.font
$ printf 'conversion status: %s\n' "$?"
conversion status: 0
$ stat -c '%n %s bytes' /tmp/pamtompfont-test.font
/tmp/pamtompfont-test.font 1192 bytes

The exact size depends on the source image. The important checks are that the input is recognised as a Netpbm image, pamtompfont returns zero, and the output is non-empty. Do not treat the test file as a useful font unless you also have a descriptor whose glyph positions match its pixels.

5. Preserve an existing output before replacing it

Shell redirection with > truncates the destination before pamtompfont starts. If the name already exists, convert to a temporary file and replace the old raster only after verification:

$ pamtompfont /path/to/glyph-sheet.pbm > glyph-sheet.mpf.new
$ test -s glyph-sheet.mpf.new
$ mv glyph-sheet.mpf.new glyph-sheet.mpf

The mv changes the destination name, so do not use this sequence until you have checked the new file. If conversion fails or produces an empty file, leave the existing raster in place and investigate. To recover from a replacement, restore your own backup or regenerate the previous raster from its original image. There is no pamtompfont undo operation.

Do not use sudo for this workflow merely because the output is a font file. Run it as the account that owns the working directory. Elevated privileges are only relevant if normal file permissions prevent reading the chosen input or writing the chosen destination; fix the path or permissions deliberately rather than running the whole pipeline as root.

6. Diagnose rejected input

A non-zero status means that the conversion did not complete. For example, plain text is rejected as neither PAM nor one of the PNM formats:

$ printf '%s\n' 'not an image' | pamtompfont
pamtompfont: bad magic number 0x6e6f - not a PAM, PPM, PGM, or PBM file
$ printf 'conversion status: %s\n' "$?"
conversion status: 1

For a file-based failure, check the path and read permission without changing the source:

$ ls -l /path/to/glyph-sheet.pbm
$ test -r /path/to/glyph-sheet.pbm && printf '%s\n' 'input is readable'

If the image opens but the generated font renders incorrectly, check the layout and descriptor together. pamtompfont does not infer character positions, glyph widths or codepoint mappings from the picture. Those are properties of the MPlayer font format and the descriptor that consumes the raster.