Convert PNM Images to Solitaire Files with pnmtosir

You will finish with a Solitaire Image Recorder file made from a PBM, PGM or PPM image, plus a simple check that the conversion produced the format you expected. The examples use Netpbm 11.5.2 from package netpbm 2:11.05.02-1.1build1, as installed on this machine.

Allow about ten minutes. You need pnmtosir, a readable PNM file and a directory where you can create the output. The command does not need elevated privileges when those files belong to your user. Do not use sudo just because the output format is old.

1. Check the installed command

Start by confirming the binary and the Netpbm version. This is read-only:

$ command -v pnmtosir
/usr/bin/pnmtosir
$ pnmtosir --version
pnmtosir: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pnmtosir: Built from source dated 2024-03-31 09:09:47
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The version text is diagnostic output from this build, so the exact build date can differ on another host. The important checkpoint is that the command you will run is the expected Netpbm program.

2. Inspect the input without changing it

pnmtosir accepts one optional pnmfile argument. If you omit it, the program reads the PNM image from standard input. The input may be PBM, PGM or PPM. Check the file type and permissions before converting:

$ file /path/to/input.pnm
/path/to/input.pnm: Netpbm image data, size 640 x 480, rawbits, pixmap
$ test -r /path/to/input.pnm && echo readable
readable

Your file output will vary. A PPM is a colour image, a PGM is greyscale and a PBM is monochrome. The file name is not enough to establish the format, so inspect the header if you are unsure:

$ head -n 3 /path/to/input.pnm
P6
640 480
255

Do not use a text editor to save a binary PNM. Raw PGM and PPM files contain binary pixel data after the header, and rewriting them as text can corrupt the image.

3. Convert to a new SIR file

Write standard output to a new destination. The shell creates or truncates the destination before pnmtosir starts, so choose a name that does not contain a useful existing file:

$ pnmtosir /path/to/input.pnm > /path/to/output.sir
pnmtosir: Writing a 24-bit SIR format (MGI TYPE 11)

For PPM input, pnmtosir writes an MGI TYPE 11 file. PBM and PGM input use MGI TYPE 17. The wording of the diagnostic identifies the selected output type, but it is written to standard error; the SIR image itself is written to standard output.

$ pnmtosir /path/to/input.pnm > /path/to/output.sir.new
$ test -s /path/to/output.sir.new
$ mv /path/to/output.sir.new /path/to/output.sir

The mv command changes the destination only after conversion has produced a non-empty file. If conversion fails, leave the original output alone and inspect the error. To recover from an unwanted replacement, restore your own backup or rename the previous file before retrying; there is no undo facility in pnmtosir.

4. Verify the result

First check that the output is recognised as a Solitaire file and is not empty:

$ test -s /path/to/output.sir && echo non-empty
non-empty
$ file /path/to/output.sir
/path/to/output.sir: Solitaire Image Recorder format MGI Type 11

For a stronger check, use the installed sirtopnm utility to decode a copy. It should report the corresponding PNM type and write a valid image:

$ sirtopnm /path/to/output.sir > /tmp/output-roundtrip.ppm
sirtopnm: Writing a PPM file
$ head -n 3 /tmp/output-roundtrip.ppm
P6
640 480
255

Use a .pgm destination and inspect the first header line when the source was greyscale. A PBM input may be decoded as PGM by the installed converter, so the round-trip type is not necessarily the original textual PNM subtype. The useful checks are a successful exit status, a recognised header and the expected dimensions.

5. Use standard input in a pipeline

The optional file argument makes a pipeline possible. This example creates a tiny PGM with another Netpbm command, then converts it without an intermediate input file:

$ printf 'P2\n4 2\n15\n0 3 6 9 12 15 9 3\n' | pnmtosir > /path/to/gradient.sir
pnmtosir: Writing a grayscale SIR format (MGI TYPE 17)
$ file /path/to/gradient.sir
/path/to/gradient.sir: Solitaire Image Recorder format MGI Type 17

This is ordinary shell I/O, not a special pnmtosir option. Keep the producer's errors visible while testing. In a script, check each command's exit status before treating the SIR file as ready for another system.

6. Diagnose the likely failures

A missing or unreadable input normally means the path or permissions are wrong. Check it without changing permissions:

$ ls -l /path/to/input.pnm
$ test -r /path/to/input.pnm && echo readable || echo 'not readable'

An empty output is not a successful conversion. Keep the source and rerun to a new temporary name so that you can examine the diagnostic without destroying a previous result. If file reports a generic data file, use sirtopnm and its exit status to test whether the SIR structure can be decoded.

The manual defines no options specific to pnmtosir. It does recognise options common to libnetpbm programs, but this guide does not rely on them. In particular, do not invent a resize, compression or output-file option: resize the PNM with a separate, verified tool before conversion, and use shell redirection for the destination.