Convert PPM Images to Amiga ILBM with ppmtoilbm

You will convert a PPM image into an Amiga ILBM file, select a suitable ILBM type, and verify the result without changing the source image. Allow about fifteen minutes, including a test conversion and an inspection of the output. The examples use Netpbm 11.5.2 from the Debian package netpbm 2:11.05.02-1.1build1 installed on this machine.

Scope: all conversions below are ordinary user commands. They do not need sudo. The command reads the PPM and writes ILBM to standard output, so shell redirection determines the destination file.

1. Check the installed command

Confirm that the executable and package are the ones you expect:

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

The program's help output is intentionally brief on this installation. The authoritative local option list is man ppmtoilbm. The input may be a PPM file path, or you can omit the path when your shell workflow supplies standard input.

2. Convert a PPM to a normal ILBM

Use a new destination name and redirect the converter's standard output. Replace the placeholder path with a readable PPM file:

$ ppmtoilbm /path/to/source.ppm > /path/to/output.ilbm

By default, ppmtoilbm writes a normal ILBM with up to five bit planes, using the fewest planes it needs within that limit. It writes the BMHD, CMAP and BODY chunks. The default compression is ByteRun1. Diagnostic messages such as colour-map calculation or a compression warning are written to standard error, so they do not corrupt the redirected ILBM file.

Verify the result before using it elsewhere:

$ file /path/to/output.ilbm
/path/to/output.ilbm: IFF data, ILBM interleaved image, 640 x 480
$ test -s /path/to/output.ilbm && echo 'ILBM file is non-empty'
ILBM file is non-empty

The dimensions and wording from file will match your image. A successful exit status and an ILBM signature are useful checks, but you should also open the image with a viewer that understands ILBM when visual fidelity matters.

3. Control the normal image depth

Use -maxplanes, or its short form -mp, to set the maximum number of planes for a normal ILBM. The documented range is 1 to 16:

$ ppmtoilbm -maxplanes 8 /path/to/source.ppm > /path/to/output-8-plane.ilbm

This is a limit, not a request for exactly eight planes. If you need an exact depth, use -fixplanes or -fp:

$ ppmtoilbm -fixplanes 4 /path/to/source.ppm > /path/to/output-4-plane.ilbm

Both options accept values from 1 to 16. If the image cannot be represented within the selected normal depth, the default mode reports an error rather than silently inventing another format. Check the command's exit status when scripting:

$ if ppmtoilbm -maxplanes 4 /path/to/source.ppm > /path/to/output.ilbm; then
>     echo 'conversion succeeded'
> else
>     echo 'conversion failed' >&2
> fi

Do not treat a file created by redirection as proof of success. A failed command can leave a partial destination.

4. Choose HAM when the image needs more colours

Amiga Hold-And-Modify output is available with -ham6 or -ham8. These force six or eight planes respectively:

$ ppmtoilbm -ham6 /path/to/source.ppm > /path/to/output-ham6.ilbm
$ file /path/to/output-ham6.ilbm
/path/to/output-ham6.ilbm: IFF data, ILBM interleaved image, 640 x 480

The local manual describes six and eight planes as the values understood by current Amiga hardware. HAM images receive a grayscale colour map. That is deliberate: it supports row-by-row operation and gives HAM images of the same depth a shared map, but it may not give the best colour selection for an individual picture.

If you want conditional selection, -hamif writes HAM only when the image does not fit within -maxplanes. The related -24if and -dcif modes conditionally select 24-bit or direct-colour output. The -hamforce, -24force and -dcforce forms always select their respective formats.

5. Use a fixed colour map or make a map-only file

To make a normal ILBM use colours from another PPM file, pass that file to -map:

$ ppmtoilbm -map /path/to/palette.ppm /path/to/source.ppm > /path/to/output-mapped.ilbm

The map file determines the colour map and number of planes, so -maxplanes and -fixplanes are ignored in this mode. Make sure the palette file is intentional and readable before starting the conversion.

For a file containing only the BMHD and CMAP chunks, use -cmaponly:

$ ppmtoilbm -cmaponly /path/to/source.ppm > /path/to/colour-map.ilbm
$ file /path/to/colour-map.ilbm
/path/to/colour-map.ilbm: IFF data, ILBM interleaved image, 0 x 0

This is not a complete displayable image: it has no BODY chunk and reports zero planes. Use it when another workflow needs a colour-map file, not as a substitute for an ordinary conversion.

6. Avoid overwriting a good output

Shell redirection with > truncates an existing destination before ppmtoilbm starts. For a replacement, write to a temporary file in the same directory and rename it only after verification:

$ ppmtoilbm /path/to/source.ppm > /path/to/output.ilbm.new
$ file /path/to/output.ilbm.new
/path/to/output.ilbm.new: IFF data, ILBM interleaved image, 640 x 480
$ mv /path/to/output.ilbm.new /path/to/output.ilbm

The mv command replaces the old file. That replacement is the irreversible step in this workflow, so keep a backup if the existing ILBM matters:

$ cp --preserve=all /path/to/output.ilbm /path/to/output.ilbm.bak

If conversion fails, do not move the partial .new file into place. Remove that temporary file after inspecting any error, or leave it for diagnosis. The source PPM is never modified by ppmtoilbm.

7. Diagnose the common failures

A missing or unreadable input produces an error such as:

$ ppmtoilbm /path/to/missing.ppm > /tmp/test.ilbm
ppmtoilbm: Unable to open file '/path/to/missing.ppm' for reading.  fopen() returns errno 2 (No such file or directory)

Check the path and permissions without changing them:

$ ls -l /path/to/source.ppm
$ test -r /path/to/source.ppm && echo readable

If a conversion stops because the normal plane limit is too small, choose a larger -maxplanes, use -hamif, or choose a forced output mode after checking that your target Amiga software supports it. If an output is unexpectedly large, the manual says that disabling compression permits stream writing but usually increases the file by 30 to 50 percent. Compression is the sensible default unless memory or streaming requirements dictate otherwise.