Convert a PPM Image for X11 puzzle with ppmtopuzz

You will turn a PPM image into the binary picture file expected by the X11 puzzle program. The converter reads one image, writes the puzzle file to standard output, and leaves the source image alone. Allow about ten minutes for a first conversion and a quick output check.

You need a Linux shell, the netpbm package, a readable PPM file, and an X11 puzzle installation if you intend to play the result. The examples use Netpbm 2:11.05.02-1.1build1, installed here on Ubuntu. The local manual page is dated 22 August 1990, so the package version is worth recording when a script depends on this old, specialised format.

1. Check the installed command

Confirm that the executable is available before preparing an output file:

$ command -v ppmtopuzz
/usr/bin/ppmtopuzz
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

Your path or package version may differ. The command has no options specific to ppmtopuzz; it accepts the common options provided by the Netpbm library. Do not assume that a familiar image option such as a resize switch exists here.

2. Convert a PPM file to a puzzle file

Give the input path as the optional argument and redirect standard output to a new destination:

$ ppmtopuzz /path/to/input.ppm > /path/to/output.puzz
ppmtopuzz: computing colormap...
ppmtopuzz: 2 colors found

The progress lines are diagnostics, normally written to standard error. The puzzle data belongs in output.puzz. The program does not add a filename extension for you, and the extension is only a convention, so choose a name that makes the file's purpose clear.

Checkpoint: make sure the command returned success and the destination is non-empty:

$ printf '%s\n' "$?"
0
$ file /path/to/output.puzz
/path/to/output.puzz: data
$ wc -c < /path/to/output.puzz
1234

The exact byte count depends on the image. file may only report data because this is an X11 puzzle format rather than a self-identifying image format. A successful exit status and a non-zero output are the useful basic checks.

3. Use standard input when the image is in a pipeline

With no filename, ppmtopuzz reads the PPM image from standard input. This is useful when another Netpbm command produces a PPM stream:

$ pnmscale -width 128 /path/to/input.ppm | ppmtopuzz > /path/to/scaled.puzz

The resize is performed by pnmscale, not by ppmtopuzz. Check each stage if a pipeline fails. A simple test that exercises the input path without needing an existing image is:

$ printf 'P3\n2 1\n255\n255 0 0 0 255 0\n' | ppmtopuzz > /tmp/example.puzz
ppmtopuzz: computing colormap...
ppmtopuzz: 2 colors found
$ test -s /tmp/example.puzz && echo 'puzzle file written'
puzzle file written

This creates a temporary two-pixel PPM containing red and green, then converts it. It is a harmless format check, not a useful game image. Remove the temporary file when you have finished testing:

$ rm /tmp/example.puzz

That removal is ordinary user-level cleanup. Do not use sudo for conversion or cleanup unless your chosen input or destination is deliberately protected by filesystem permissions.

4. Protect an existing output

Shell redirection with > truncates its destination before the program starts. If output.puzz already contains a working image, do not test a replacement directly over it. Write a temporary file in the same directory and move it into place only after validation:

$ ppmtopuzz /path/to/input.ppm > /path/to/output.puzz.new
$ test -s /path/to/output.puzz.new
$ mv /path/to/output.puzz.new /path/to/output.puzz

The mv command replaces the old file. This is the point of no return for that previous pathname, so inspect the new file or open it with puzzle before committing to the replacement. If conversion fails, the original remains untouched and the partial .new file can be removed after inspection.

5. Diagnose input and output failures

A bad or missing input should fail before you treat the output as usable. Check the path and read permission without changing anything:

$ ls -l /path/to/input.ppm
$ test -r /path/to/input.ppm && echo readable
readable

If standard input is involved, remember that a prior command may have consumed it or produced something other than PPM. Netpbm reports a bad magic number for non-PPM input. Capture the status and diagnostics separately when debugging:

$ ppmtopuzz /path/to/input.ppm > /tmp/check.puzz 2> /tmp/ppmtopuzz.err
$ status=$?
$ printf 'status=%s\n' "$status"
status=0
$ test -s /tmp/check.puzz && echo 'output is non-empty'
output is non-empty
$ sed -n '1,4p' /tmp/ppmtopuzz.err
ppmtopuzz: computing colormap...
ppmtopuzz: 2 colors found

Do not pass a PNG, JPEG or an arbitrary binary file and expect automatic format detection. Convert it to PPM with an appropriate image tool first. If the input is valid but the result cannot be opened by puzzle, keep the original PPM, confirm that your puzzle build supports its picture format, and try a small known-good test image.