Convert a PPM to an Atari Degas PI1 File

Bringing artwork to a Degas-compatible Atari ST means squeezing a PPM into its fixed screen format, and ppmtopi1 does that conversion. The examples use Netpbm 11.5.2 from package netpbm version 2:11.05.02-1.1build1, installed on this machine.

Allow about fifteen minutes. You need a shell, a readable PPM file and the Netpbm utilities. The conversion writes binary data to standard output, so redirect it to a new file. It needs no elevated privileges unless filesystem permissions protect the input or destination.

1. Check the installed converter

Confirm which executable your shell will run and ask the linked Netpbm library for its version:

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

-version is a common Netpbm option: it reports the library version and exits without converting anything. The installed command also accepts the long form --version, but using the documented single-hyphen form keeps the example portable across older Netpbm installations.

2. Inspect the input before conversion

ppmtopi1 takes one optional PPM filename; with none given it reads PPM data from standard input. Use file or pamfile to check the input without changing it:

$ file /path/to/input.ppm
/path/to/input.ppm: Netpbm image data, size: 320 x 200, rawbits, pixmap
$ pamfile /path/to/input.ppm
/path/to/input.ppm: PPM raw, 320 by 200 by 255 maxval

Swap in the real path for /path/to/input.ppm. PPM supports both plain text and raw binary encodings, and Netpbm reads either. The output format is an Atari Degas PI1 image, a 320 by 200, 16-colour screen format, so a source image with a different shape is not something to leave to guesswork: normalise it first and inspect the result.

If pamfile is not installed, ppmfile is not a substitute command. Use whatever PPM reader you already have, or inspect the file header with a format-aware tool. Do not edit a binary PPM in a text editor.

3. Convert to a new PI1 file

Run the converter with the input path and redirect standard output to a new destination:

$ ppmtopi1 /path/to/input.ppm > /path/to/output.pi1
ppmtopi1: computing colormap...
ppmtopi1: 16 colors found

The informational messages go to standard error. The PI1 bytes go to standard output, so they will not clutter your terminal unless you drop the redirection. The converter has no command-line option for an output filename: shell redirection supplies that part of the workflow.

$ test ! -e /path/to/output.pi1 && \
  ppmtopi1 /path/to/input.ppm > /path/to/output.pi1

A failed conversion can leave a partial file, because the shell creates the destination before the program has read all the input. Remove only that known partial output, or replace it with a backup after checking the error. This conversion never alters the input file.

4. Make the command quiet when scripting

For a batch job, use the common -quiet option if you do not need progress messages:

$ ppmtopi1 -quiet /path/to/input.ppm > /path/to/output.pi1
$ printf 'converter status: %s\n' "$?"
converter status: 0

Keep that exit status check right after the conversion: a zero status means the program completed, not that the image looks right. If you need diagnostics, drop -quiet and capture standard error separately:

$ if ppmtopi1 /path/to/input.ppm > /path/to/output.pi1 2>/tmp/ppmtopi1.log; then
    printf '%s\n' 'PI1 conversion completed'
  else
    status=$?
    printf 'PI1 conversion failed with status %s\n' "$status" >&2
    sed -n '1,20p' /tmp/ppmtopi1.log >&2
    exit "$status"
  fi

The temporary log holds only diagnostics for this example. Use a private temporary directory for a multi-user script, and remove the log once you no longer need it. Do not put untrusted filenames into shell syntax without quoting them.

5. Verify the result as a PI1 image

Check the output size first, then use the inverse Netpbm converter to read its header:

$ stat -c '%n %s bytes' /path/to/output.pi1
/path/to/output.pi1 32034 bytes
$ pi1toppm /path/to/output.pi1 | head -n 3
P6
320 200
7

A normal PI1 file from this Netpbm build is 32,034 bytes: a 34-byte header followed by the 320 by 200 screen data. The exact pixel bytes depend on the source and its reduced palette. The pi1toppm check reads the file and reports a 320 by 200 PPM stream; it also writes binary pixel data after the header, so limiting output with head -n 3 keeps the rest off your terminal.

For a file you intend to send elsewhere, copy it in binary mode and keep the .pi1 suffix. Never use a text-mode transfer or paste its contents into a terminal. If a receiving tool rejects it, compare the reported size and the first three lines from pi1toppm before you go digging into the image itself.

Common traps

• Unexpected EOF or read error. The PPM is truncated or its header does not match the available pixels. Recreate or re-export the source, then rerun the inspection step.
• Wrong image shape. Resize or crop the image to 320 by 200 with a separate Netpbm tool, write that as a new PPM, and convert the new file. Keep the original until the result has been checked.
• Unexpected colours. PI1 has only 16 palette entries. ppmtopi1 computes a palette during conversion, so gradients and photographs can lose detail. Preview the round-tripped output rather than judging by file size alone.
• No output file. Check the redirection path and directory permissions. Elevated privileges are not a normal fix for a path typo; use them only when you are authorised to write the intended protected directory.