Convert a PPM Image to an Atari Degas PI1 File with ppmtopi1

You will finish with an Atari Degas .pi1 file made from a PPM image, plus a quick way to confirm that the output is the expected fixed-size format. 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 does not require elevated privileges unless the input or destination is protected by filesystem permissions.

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

The -version option is a common Netpbm option. It reports the library version and exits without converting an image. 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 no filename 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

Replace /path/to/input.ppm with the real path. PPM supports both plain text and raw binary encodings, and Netpbm can read either. The output format is an Atari Degas PI1 image, which is a 320 by 200, 16-colour screen format. 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 the 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 do not appear in the terminal unless you omit the redirection. The converter has no command-line option for an output filename. The 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 reads all input. Remove only that known partial output, or replace it with a backup after checking the error. This conversion does not alter 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 the exit status check immediately after the conversion. A zero status means the program completed successfully; it is not a visual inspection of the image. If you need diagnostics, leave out -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 contains only diagnostics for this example. Use a private temporary directory for a multi-user script, and remove the log when it is no longer needed. 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 produced by 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 prevents your terminal from receiving the rest.

For a file you intend to send elsewhere, copy it in binary mode and keep the .pi1 suffix. Do not 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 investigating the image itself.

6. Handle the common failures

• Unexpected EOF or read error: the PPM is truncated or its header does not describe 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 may lose detail. Preview the round-tripped output rather than judging only the file size.
• 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.

There is no persistent setting to undo. To recover, delete or quarantine only a PI1 file you created and rerun the conversion with a corrected input or destination. The source PPM remains unchanged.