Convert Atari Degas PI3 Files to PBM with pi3topbm

You will convert an Atari Degas .pi3 image into a PBM bitmap, then verify the output without changing the source file. The examples use Netpbm 11.5.2, installed here as Debian package version 2:11.05.02-1.1build1. Allow about ten minutes if the input file is already available.

You need a Linux shell, the netpbm package and read access to the Atari image. The conversion itself normally needs no elevated privileges. It reads an image and writes a new image; it does not edit the input.

1. Check the installed command

Confirm which executable will run and record the installed Netpbm build:

$ command -v pi3topbm
/usr/bin/pi3topbm
$ pi3topbm --help
pi3topbm: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pi3topbm: Built by Debian
pi3topbm: Use 'man pi3topbm' for help.

The command's manual page defines one optional input argument, pi3file. It has no options specific to pi3topbm; it also recognises options shared by libnetpbm programs. Do not assume that an option from another Netpbm converter applies here.

2. Convert a PI3 file to PBM

Redirect standard output to a new destination. Replace the placeholder path with the actual input file:

$ pi3topbm /path/to/archive/image.pi3 > image.pbm

A successful run is usually silent because the PBM data is written to standard output. The source file remains unchanged. You can also use standard input when that suits a pipeline:

$ pi3topbm < /path/to/archive/image.pi3 > image.pbm

Keep the input and output directions clear. The optional file argument is the input; the converted PBM goes to standard output. Sending both to the terminal can produce binary-looking output and make the shell difficult to use, so redirect the result to a file.

3. Verify the PBM header and dimensions

Use file to check that the output is a bitmap rather than relying only on the command's exit status:

$ file image.pbm
image.pbm: Netpbm image data, size = 640 x 400, rawbits, bitmap

The exact wording can vary with your file version. Look for Netpbm image data, bitmap, and sensible dimensions. A binary PBM normally begins with the magic number P4, followed by its width and height:

$ head -n 2 image.pbm
P4
640 400

Do not use a text editor to inspect the whole file. The header is text, but the pixels after it are binary data. If the file is empty or file does not identify it as a bitmap, keep the original PI3 file and investigate the error before trying another destination.

4. Protect an existing output

Use a temporary name in the same directory, verify it, and replace the old file only after the check succeeds:

$ pi3topbm /path/to/archive/image.pi3 > image.pbm.new
$ file image.pbm.new
image.pbm.new: Netpbm image data, size = 640 x 400, rawbits, bitmap
$ mv image.pbm.new image.pbm

The final mv changes the directory entry, so run it only when the new file is the intended replacement. If conversion fails, remove the incomplete image.pbm.new after checking that it is the temporary file you created. The existing image.pbm is not changed by this workflow. If you need an extra recovery point, copy the old file before the conversion:

$ cp --preserve=all image.pbm image.pbm.backup

Delete that backup only after you have opened or otherwise checked the replacement. That deletion is irreversible.

5. Diagnose the common failures

If the input cannot be opened, check the path and permissions without modifying anything:

$ ls -l /path/to/archive/image.pi3
$ test -r /path/to/archive/image.pi3 && echo readable
$ pi3topbm /path/to/archive/image.pi3 > image.pbm.new
$ printf 'exit status: %s\n' "$?"
exit status: 0

For a failure, the status will be non-zero and the program should report a diagnostic on standard error. Check that you selected a Degas .pi3 file rather than another Atari format. The extension alone is not proof of the file format.

A successful exit status only says that the converter completed its work. It does not confirm that the image is the one you expected. Check the dimensions and inspect the PBM with a viewer or another Netpbm tool. If you want to convert it further, do that as a separate step after the PBM check.

No sudo command is part of this workflow. Use elevated access only when your operating system's file permissions genuinely require it, and prefer copying the input into a directory you own rather than running an image converter as root.

6. Use the result in a pipeline

Because the output is standard PBM, it can feed another program without an intermediate file. For example, if pbmtoascii is installed, this produces a terminal preview:

$ pi3topbm /path/to/archive/image.pi3 | pbmtoascii

This preview is only useful for a small or deliberately reduced image, and its appearance depends on the terminal. For an archival conversion, keep the PBM file so its header and bytes can be checked independently.