Convert a PGM Image to Lisp Machine Format with pgmtolispm

pgmtolispm turns a Portable Graymap into the bitmap format that TI Explorer and Symbolics Lisp machines read. Most people meet this command exactly once, while archiving or reviving old Lisp Machine software, and that is via the tv:read-bit-array-file function.

Allow about ten minutes if the input image is ready. The examples use Netpbm 11.5.2 from Debian package netpbm version 2:11.05.02-1.1build1.

This is a format conversion, not a display or colour-management workflow. The command writes the converted bitmap to standard output, so you choose the destination yourself, and it needs no elevated privileges unless your input or destination is protected.

1. Check the installed command

Confirm which executable will run and record the Netpbm build information:

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

The version diagnostic comes from the shared Netpbm library. The installed manual describes pgmtolispm as accepting one optional PGM file and defines no command-specific options of its own. It does recognise the common libnetpbm options, but do not assume an option from another Netpbm program applies here.

2. Inspect the PGM input

Keep the original image and check its header before converting it:

$ file IMAGE.pgm
IMAGE.pgm: Netpbm image data, size WIDTH x HEIGHT, rawbits, greymap
$ pamfile IMAGE.pgm
IMAGE.pgm: PGM raw, WIDTH by HEIGHT pixels, maxval MAXVAL

Replace IMAGE.pgm with the path to your file. PGM can be plain text or binary and can use a range of maximum sample values; Netpbm reads those forms for you. A failed inspection usually means the path, permissions or file format need attention, not that the source needs overwriting.

3. Write a new Lisp Machine bitmap

Redirect standard output to a new destination file:

$ pgmtolispm IMAGE.pgm > IMAGE.lispm
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ ls -l IMAGE.lispm
-rw-r--r-- 1 USER GROUP SIZE DATE IMAGE.lispm

Status 0 means the converter completed successfully; the exact file size and listing date will vary. The command never prints the bitmap to your terminal, because redirected standard output here carries binary data.

4. Check the result with the reverse converter

If lispmtopgm is installed, use it to make a temporary PGM for a structural check:

$ lispmtopgm IMAGE.lispm > /tmp/IMAGE-roundtrip.pgm
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ pamfile /tmp/IMAGE-roundtrip.pgm
/tmp/IMAGE-roundtrip.pgm: PGM raw, WIDTH by HEIGHT pixels, maxval MAXVAL

The exact dimensions and maximum value depend on the source. This shows the companion Netpbm converter can read the file you produced; it is not a visual proof that every Lisp Machine application will accept the image. Open the original and the round-tripped image in a viewer if visual comparison matters.

The temporary file is safe to remove after inspection, and that removal is optional, targeting only the named temporary output. Keep IMAGE.lispm until the target machine has read it successfully.

$ rm -- /tmp/IMAGE-roundtrip.pgm

5. Account for the format's limits

• Width rounds up to a multiple of 32. Lisp Machine arrays with widths not divisible by 32 are awkward to pass to BITBLT, so this padding is deliberate: a 17-pixel-wide source has a format-level width of 32, even if a round-trip tool later presents the meaningful area differently.
• A PGM input produces a multi-plane image. That is probably only useful with a colour Lisp Machine. The Lisp Machine file format has no colour map, so treat the planes as a greymap rather than as a portable colour image; pgmtolispm is not a way to preserve modern RGB colour semantics.

Do not crop away the padded area without checking the consumer's expectations. If a fixed-width display or BITBLT operation is the destination, plan for the rounded width; if exact source dimensions matter more, keep the PGM as the authoritative copy.

6. Use standard input when the file is already in a pipeline

The input file is optional. With none given, pgmtolispm reads the PGM from standard input and still writes the Lisp Machine bitmap to standard output:

$ cat IMAGE.pgm | pgmtolispm > IMAGE.lispm
$ test -s IMAGE.lispm
$ printf 'non-empty output confirmed\n'
non-empty output confirmed

For a simple file conversion, naming the input directly is easier to audit. Use standard input when another trusted command is deliberately producing the PGM, and avoid feeding untrusted shell text into a pipeline without understanding how it is quoted and where its output goes.