Convert a PGM image to Lisp Machine format with pgmtolispm

You will convert a Portable Graymap (PGM) image into the Lisp Machine bitmap format read by the tv:read-bit-array-file function on TI Explorer and Symbolics Lisp machines. The examples use Netpbm 11.5.2 from Debian package netpbm version 2:11.05.02-1.1build1. Allow about ten minutes if the input image is ready.

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. It does not need 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 is emitted by the shared Netpbm library. The installed manual describes pgmtolispm as accepting one optional PGM file and defines no command-specific options. It does recognise common libnetpbm options, but do not assume that an option from another Netpbm program applies here.

Checkpoint: if command -v finds nothing, install the distribution's netpbm package through your normal package-management process. Do not run the converter with sudo to solve a missing executable.

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. The PGM format 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 needs attention; it is not a reason to overwrite the source.

Checkpoint: make sure the reported dimensions and greyscale type match the image you intend to send to the Lisp Machine. The input must be PGM, not PBM or PPM. For a PBM source, convert it to PGM first with a separate, verified Netpbm workflow.

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

A status of 0 means the converter completed successfully. The exact file size and listing date vary. The command does not print the bitmap to your terminal because the redirected standard output contains binary data.

Use a fresh name while testing. Shell redirection truncates an existing destination before pgmtolispm starts, so pgmtolispm IMAGE.pgm > IMAGE.pgm can destroy the source even if the conversion later fails. Recovery is to restore the source from its backup or other original copy; there is no undo operation in pgmtolispm.

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 check shows that the produced file can be read by the companion Netpbm converter. It is not a visual proof that every Lisp Machine application will accept the image. Open the original and the round-tripped image with a suitable viewer if visual comparison matters.

The temporary file is safe to remove after inspection:

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

That removal is optional and only targets the named temporary output. Keep IMAGE.lispm until the target machine has read it successfully.

5. Account for the format's limits

The manual records two details that are easy to miss. First, output width is always rounded up to the nearest multiple of 32. Lisp Machine arrays with widths not divisible by 32 are awkward to pass to the BITBLT function, so this padding is deliberate. A source that is 17 pixels wide therefore has a format-level width of 32, even though a round-trip tool may present the meaningful image area differently.

Second, a PGM input produces a multi-plane Lisp Machine image. That is probably useful only with a colour Lisp Machine. The Lisp Machine file format has no colour map, so the planes must be treated 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 are more important, retain the PGM as the authoritative copy.

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

The input file is optional. With no filename, 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. Avoid putting untrusted shell text into a pipeline without understanding how it is quoted and where its output goes.