Convert Lisp Machine Bitmaps to PGM with lispmtopgm

You will convert a Lisp Machine bitmap into a PGM image on standard output, save it without overwriting the source, and check that the result is a usable file. lispmtopgm is a small Netpbm converter for the format written by the tv:write-bit-array-file function on TI Explorer and Symbolics Lisp machines.

Allow about fifteen minutes for one file, plus time to find a viewer or another Netpbm tool if you need to inspect the image. You need a shell, a readable Lisp Machine bitmap, and Netpbm. The examples do not need sudo: conversion reads one file and writes another in your working directory.

1. Check the installed converter

Confirm which executable the shell will run and record the local Netpbm version. These are read-only commands:

$ command -v lispmtopgm
/usr/bin/lispmtopgm
$ lispmtopgm --version
lispmtopgm: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
... 

The exact build lines can vary, but the important detail here is Netpbm 11.5.2. The Debian package installed on the machine used for this guide is netpbm 2:11.05.02-1.1build1. Keep the version with any conversion notes because format edge cases can differ between releases.

There are no options specific to lispmtopgm. It accepts one optional input filename and also recognises options common to libnetpbm programs. Do not assume that a familiar option from another Netpbm converter applies here.

2. Preserve and inspect the source

Replace the example path with the actual file. Start with metadata checks rather than opening or rewriting it:

$ INPUT='/path/to/bitmap.lispm'
$ test -r "$INPUT" && echo 'source is readable'
source is readable
$ file -- "$INPUT"
$ stat --printf='bytes: %s\n' -- "$INPUT"

The filename extension is not a format check, and file may not identify this historical format. The useful checks are that the path names the intended file and that it is readable. If test prints nothing, fix the path or permissions before converting.

Do not edit or delete the source as part of this workflow. A Lisp Machine file can contain a width that the converter cannot handle correctly, so the original is your recovery copy. If the file belongs to another user or directory access is restricted, ask its owner to provide a readable copy rather than running the converter as root.

3. Convert to a new PGM file

lispmtopgm writes the converted PGM image to standard output. Redirect that output to a new destination:

$ OUTPUT='/path/to/bitmap.pgm.new'
$ lispmtopgm "$INPUT" > "$OUTPUT"
$ printf 'converter exit status: %s\n' "$?"
converter exit status: 0

A zero status means the command completed successfully. The .new suffix is deliberate. Shell redirection truncates an existing destination before the program runs, so redirecting straight to a valuable bitmap.pgm can destroy it if a later conversion fails.

If the command returns a non-zero status, do not use the output as if it were complete. Inspect it, keep the source, and choose a different destination for the next attempt. Once you have checked the result, promote it atomically:

$ file -- "$OUTPUT"
$ test -s "$OUTPUT" && echo 'output is non-empty'
output is non-empty
$ mv -- "$OUTPUT" '/path/to/bitmap.pgm'

The final mv changes the directory entry and does not alter the source. It replaces an existing destination if you name one, so only run it after checking that replacement is intended. If the check fails, leave the original destination alone and remove the incomplete .new file manually after confirming its path.

4. Check what the conversion means

The source format can represent multi-plane bitmaps as colour, but it does not contain a colour map. lispmtopgm therefore treats the data as monochrome and produces PGM output. A successful conversion is not a promise that colour information has survived. If the original image depended on a machine-specific palette, the PGM file cannot reconstruct that palette from this format alone.

Check the resulting file with the tools available on your system:

$ file -- '/path/to/bitmap.pgm'
/path/to/bitmap.pgm: Netpbm image data, ...
$ head -n 3 '/path/to/bitmap.pgm'
P5
...

The exact file description, dimensions and header lines depend on the input. The first PGM header marker is normally P5 for binary PGM output, but use the complete file rather than copying a partial header into another file. If you have an image viewer, open the PGM and check its dimensions and visible content. A later Netpbm converter can also consume it if you need another image format.

5. Handle the width limitation

The Lisp Machine format is quirky around image width. Its width is usually rounded up to a multiple of 32, though not always. The converter does not handle a non-multiple-of-32 width properly, and the manual warns that such arrays are probably not image data produced by the Lisp Machine microcode.

There is a second historical failure mode. The Lisp Machine saving code can round a non-modulo-32 width down when calculating the file length, leaving the file up to seven bits too short. lispmtopgm does not repair that truncated input gracefully.

If the output has the wrong dimensions, looks corrupted, or conversion reports a format error, go back to the source producer. Check whether the bitmap was written by the expected tv:write-bit-array-file path and whether its width was suitable. Do not try to fix the file by padding random bytes: that changes evidence without establishing the intended image layout. Re-run the conversion only after obtaining a sound source or confirming that the odd width is expected.

6. Recover from common mistakes

If you accidentally choose the wrong output path but have not run the command, change OUTPUT. If conversion fails, leave the source untouched and inspect the .new file only as a diagnostic. If you have not promoted it, the previous PGM remains available. If you already ran mv over an old PGM, recovery depends on your backup or filesystem snapshots; lispmtopgm has no undo operation.

Running lispmtopgm with no usable input does not create a useful image. On the installed build, an empty standard input produced bad id string in Lispm file and exit status 1. Supply the input filename explicitly unless you intentionally provide a valid Lisp Machine file through standard input.