Convert an Atari Spectrum File to PPM with sputoppm

You will convert an Atari uncompressed Spectrum file into a PPM image, check that the result has the expected 320 x 200 geometry, and keep a failed conversion from destroying an existing output. The examples use Netpbm 11.5.2 from Debian package version 2:11.05.02-1.1build1.

Allow about ten minutes. You need a shell, the netpbm package, and a readable uncompressed Spectrum file. You do not need elevated privileges for conversion. The input format is specialised: a normal PPM, PNG, or compressed Spectrum file is not a substitute.

1. Check the installed command

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

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

The manpage defines one optional positional argument, spufile. There are no sputoppm-specific options. With a filename, the command reads that file. With no filename, it reads standard input.

2. Confirm that the input is the right kind of file

Do not identify the format by its filename alone. Check the path, size, and read permission without changing the file:

$ INPUT='/path/to/image.spu'
$ test -r "$INPUT" && echo 'input is readable'
input is readable
$ stat -c '%n %s bytes' "$INPUT"
/path/to/image.spu 51104 bytes

The size shown is the fixed size of the format handled by this implementation: 32,000 bytes of screen data followed by 19,104 bytes of palette data. A real file may still be malformed despite having that length, so treat this as a quick check, not format authentication. If the file is a compressed Spectrum file, use spctoppm instead; sputoppm is for the uncompressed form.

Do not edit, truncate, or rename the original while testing. Keep a copy of irreplaceable historical files before processing them.

3. Convert to a new PPM file

Redirect standard output to a new destination. The command normally prints the image data, not a progress report:

$ sputoppm "$INPUT" > image.ppm
$ printf 'exit status: %s\n' "$?"
exit status: 0

This is an ordinary unprivileged command. The output is raw PPM, identified by the P6 magic number, with width 320, height 200, and maximum channel value 7. The converter writes those values from the decoded Spectrum data; it does not resize the image and it does not preserve the original file as metadata.

$ sputoppm "$INPUT" > image.ppm.new
$ file image.ppm.new
$ mv image.ppm.new image.ppm

The mv command changes the destination name in the current directory. If conversion fails, leave the existing image.ppm alone and remove the incomplete image.ppm.new after checking that no other process needs it.

4. Verify the PPM header and dimensions

Use file for a quick independent check, then inspect only the text header. Do not send the binary pixel data through tools that may alter it:

$ file image.ppm
image.ppm: Netpbm image data, size = 320 x 200, rawbits, pixmap
$ head -c 12 image.ppm | od -An -tc
   P   6  \n   3   2   0       2   0   0  \n   7  \n

Whitespace in the od display varies, but the useful sequence is P6, then 320 200, then 7. A successful exit status alone only says that the process completed. Open the PPM with an image viewer or pass it to a separate Netpbm converter if you need to check the picture itself.

5. Read from standard input when that helps

The filename is optional, so a pipeline can provide the uncompressed Spectrum bytes. This does not change the output format:

$ sputoppm < "$INPUT" > image-from-stdin.ppm
$ file image-from-stdin.ppm
image-from-stdin.ppm: Netpbm image data, size = 320 x 200, rawbits, pixmap

Use a pipeline only when its upstream command is understood. For example, if you decompress an archive first, make sure the result is the uncompressed Spectrum representation before handing it to sputoppm. Do not assume that a file named .spc or .spu tells you which converter is correct.

6. Diagnose failures without changing the source

An error opening the input usually means the path, permissions, or file type is wrong. Recheck the exact value held in INPUT:

$ printf 'input: %s\n' "$INPUT"
input: /path/to/image.spu
$ ls -l -- "$INPUT"
$ test -r "$INPUT" && echo readable || echo 'not readable'

If the input is readable but the output is not a valid PPM, retain the source and inspect it with a format-aware tool or obtain an uncompressed copy. Do not fix a damaged file by padding it with zeros and then treat the resulting image as authentic. A zero-filled file of the expected length is useful only as a local smoke test of the installed converter.

If you accidentally created an incomplete replacement, delete only that temporary output after confirming its exact path:

$ test -f image.ppm.new && printf 'review before deleting: %s\n' "$PWD/image.ppm.new"
review before deleting: /current/directory/image.ppm.new
$ rm -- image.ppm.new

That last command is irreversible. It needs no sudo, and it should never target the original Spectrum file or your previously verified PPM.