Convert a PBM Image to an Atari Degas PI3 File

You will finish with a reproducible PBM-to-PI3 conversion, a verified Atari Degas Elite output file, and a safe way to avoid overwriting an existing image. The examples use pbmtopi3 from Netpbm 11.5.2, installed here as Debian package version 2:11.05.02-1.1build1.

Allow about ten minutes. You need a shell, the Netpbm command, a readable PBM image, and enough space for a temporary output file. The normal conversion is unprivileged: do not use sudo unless your input or destination permissions genuinely require it.

1. Check the installed command

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

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

This build does not provide a normal option summary for --help; it directs you to the manual instead. The command has no options defined specifically for this conversion. Its input argument is optional, so you can provide a PBM path or send PBM data on standard input.

2. Confirm the input is really PBM

Use file before converting a path supplied by somebody else or produced by an unfamiliar tool:

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

The wording can vary slightly. The useful parts are that the file is identified as a Netpbm bitmap and that its dimensions are visible. PBM is a monochrome, two-value format. The PBM manual describes the raw format as beginning with the P4 magic number, followed by width, height and a packed bitmap raster. A file name ending in .pbm is only a convention; pbmtopi3 reads the file content, not its suffix.

If the file is not readable, fix the path or permissions rather than escalating immediately:

$ test -r /path/to/input.pbm && echo readable
readable

Do not edit or delete the source as part of this conversion. Keep it until the PI3 has been checked.

3. Convert to a new PI3 file

Give the output a new name while testing. Shell redirection with > truncates an existing destination before pbmtopi3 has succeeded, so this is a destructive boundary:

$ pbmtopi3 /path/to/input.pbm > /path/to/output.pi3
$ printf 'exit status: %s\n' "$?"
exit status: 0

A zero status means the converter completed and wrote its standard output. It does not prove that the source image looks the way you expect. Check the new file itself:

$ file /path/to/output.pi3
/path/to/output.pi3: Atari DEGAS Elite bitmap 640 x 400 x 2, color palette 0777 0000 0000 0000 0000 ...
$ test -s /path/to/output.pi3 && echo non-empty
non-empty

The installed program writes the Atari Degas Elite PI3 format at 640 x 400 with two colour values. In a verified test, even a 10 x 10 PBM produced a PI3 reported as 640 x 400. That is a format characteristic, not a request to preserve arbitrary input dimensions. If your source is not designed for the target display, inspect the result before replacing any useful file.

4. Use standard input in a pipeline

Omit the optional input path when another Netpbm program is producing PBM data. For example, pbmmake can create a temporary white bitmap and pipe it directly into pbmtopi3:

$ pbmmake -white 640 400 | pbmtopi3 > /path/to/white-screen.pi3
$ file /path/to/white-screen.pi3
/path/to/white-screen.pi3: Atari DEGAS Elite bitmap 640 x 400 x 2, color palette 0000 0000 0000 0000 0000 ...

The exact palette text can differ with the bitmap content and Netpbm build. The important checks are a successful pipeline and a PI3 file identified at 640 x 400. If you need the producer's failure to stop the pipeline reliably in a script, enable the shell's pipefail option before running it. That is a shell setting, not a pbmtopi3 option.

5. Round-trip the result when an image check matters

Use the related pi3topbm converter to turn the result back into a PBM that ordinary tools can inspect. This does not restore the original file; it creates a separate verification image:

$ pi3topbm /path/to/output.pi3 > /tmp/output-roundtrip.pbm
$ file /tmp/output-roundtrip.pbm
/tmp/output-roundtrip.pbm: Netpbm image data, size = 640 x 400, rawbits, bitmap

Open or further convert the round-trip PBM with a trusted image tool. The round-trip check tests that the PI3 is structurally readable and shows the target dimensions. It cannot prove that every source pixel survived unchanged when the input was not already 640 x 400, because the PI3 format has its own fixed display geometry.

6. Diagnose failures without guessing

A missing input path is an ordinary file error. A file containing text that is not PBM produces a non-zero status and a diagnostic such as:

$ pbmtopi3 /path/to/not-a-pbm.txt > /tmp/failed.pi3
pbmtopi3: bad magic number 0x6e6f - not a PPM, PGM, PBM, or PAM file
$ printf 'exit status: %s\n' "$?"
exit status: 1

The hexadecimal value and wording depend on the bytes in the bad file. Treat any non-zero status as a failed conversion. Inspect the input with file, confirm its permissions, and check that the producer emitted PBM rather than PGM, PPM or another format. Although Netpbm's shared reader recognises several PNM-family formats, the documented purpose of this command is PBM input, so keep the source format explicit in scripts.

If the output path already existed and the command failed, the shell may have left it empty or truncated. This is why the examples use a new name. To replace a checked file, first preserve the old one and then move the verified temporary output into place:

$ cp --preserve=all /path/to/output.pi3 /path/to/output.pi3.bak
$ mv /path/to/output.pi3.new /path/to/output.pi3

If the replacement is wrong, restore the backup with mv /path/to/output.pi3.bak /path/to/output.pi3. Remove the backup only after you are satisfied; that deletion is irreversible.