Convert Amiga ILBM Images to PPM with ilbmtoppm

ilbmtoppm turns an Amiga IFF ILBM file into a PPM you can open on anything, and pulls out a separate PBM mask when the source carries transparency. The examples use ilbmtoppm from Netpbm 11.5.2 on this machine.

Allow about fifteen minutes. You need a readable ILBM file, a shell, and enough free space for the output. The converter does not need root, and none of the commands below change the input file. Keep a PPM-capable viewer or another Netpbm utility handy if you want to check the result visually.

1. Check the installed converter

Confirm which executable will run and note its Netpbm version. These are ordinary read-only commands:

$ command -v ilbmtoppm
/usr/bin/ilbmtoppm
$ ilbmtoppm --version
ilbmtoppm: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
...

The exact build date and extra diagnostic lines can differ. The installed manual page is dated 12 November 2014, while this binary reports Netpbm 11.5.2. Keep that gap in mind when comparing option lists on another host.

Checkpoint: if command -v prints nothing, install Netpbm through your normal distribution package management process. Do not grab a binary from an untrusted download just to make this example work.

2. Convert one ILBM to a new PPM

Use an explicit output path and shell redirection. Swap /path/to/source.ilbm for the real file, and leave the source untouched:

$ ilbmtoppm /path/to/source.ilbm > /path/to/source.ppm
$ test -s /path/to/source.ppm && echo 'PPM written'
PPM written

With no input filename, ilbmtoppm reads the ILBM from standard input. With a filename, it reads that file and writes the PPM to standard output. Redirection is part of the normal workflow here, not an optional extra.

Warning: do not redirect straight over the only copy of an existing image. Shell redirection truncates the destination before the converter even starts. If /path/to/source.ppm already exists and matters, pick a new name or move the old file to a dated backup first. Recovery is then just removing the new output and restoring the backup; the converter itself has no undo operation.

Checkpoint: check the output is actually a PPM before opening it in another tool:

$ file /path/to/source.ppm
/path/to/source.ppm: Netpbm image data, ...

The dimensions and exact description are specific to the image. A non-zero exit status, an empty file, or an error such as Unexpected end of input file means the conversion did not produce a trustworthy result. Keep the original ILBM and go investigate its format or completeness.

3. Inspect the source when a conversion is unclear

Add -verbose when you need detail on the ILBM's chunks and image properties:

$ ilbmtoppm -verbose /path/to/source.ilbm > /path/to/verbose.ppm
$ test -s /path/to/verbose.ppm && echo 'verbose conversion completed'
verbose conversion completed

Diagnostic text goes to standard error while the PPM stays on standard output. The exact lines depend on the file. The converter recognises chunks such as BMHD, CMAP, CAMG, PCHG and BODY, and skips unknown ones. Some metadata chunks, including NAME, AUTH, ANNO and DPI, are ignored normally but shown in verbose mode.

If a damaged or unusual file fails, do not treat a successful-looking partial output as proof the image is correct. Compare the output size and dimensions against a known-good viewer or a later conversion step.

4. Preserve transparency in a PBM mask

An ILBM can carry transparency information separately from its colour pixels. Pass a mask filename to get a PBM mask alongside the PPM:

$ ilbmtoppm -maskfile /path/to/source-mask.pbm \
    /path/to/source.ilbm > /path/to/source.ppm
$ file /path/to/source.ppm /path/to/source-mask.pbm
/path/to/source.ppm:      Netpbm image data, ...
/path/to/source-mask.pbm: Netpbm image data, ...

The mask maps onto the input image: white pixels mean transparent, black pixels mean opaque. If the ILBM carries no transparency information, no mask file gets created at all. Check for that case explicitly rather than assuming a missing mask means the command failed.

There is a destructive edge case here: an existing mask path can be overwritten by shell or program output behaviour. Use a fresh destination while testing, and confirm the old file is backed up before reusing its name.

5. Handle HAM, EHB and deep-image hints deliberately

The converter normally trusts the flags in the ILBM's CAMG chunk. Some files omit them or get them wrong. -isham forces HAM handling, and -isehb forces Extra_Halfbrite handling:

$ ilbmtoppm -isham /path/to/ham.ilbm > /path/to/ham.ppm
$ ilbmtoppm -isehb /path/to/ehb.ilbm > /path/to/ehb.ppm

Use these only when the file is known to be HAM or EHB. Force the wrong interpretation and you get plausible-looking but wrong colours. Do not stack both switches on the same command.

Current Netpbm documentation also describes -isdeep for a deep ILBM. The local 2014 manual page does not list it, but the installed 11.5.2 binary accepts it anyway. It only applies when the input has the right number of planes, so treat it as a format-specific hint rather than a general image-quality switch. Check the result against a trusted copy after using it.

6. Extract a colour map or correct low-valued colours

Use -cmaponly when you want a PPM containing the ILBM's colour map rather than its rendered image:

$ ilbmtoppm -cmaponly /path/to/source.ilbm > /path/to/colour-map.ppm
$ test -s /path/to/colour-map.ppm && echo 'colour map written'
colour map written

A pure colour-map stream is treated this way even without -cmaponly, whenever it has no BODY chunk or zero bit planes. That default can catch you out if you were expecting a full raster image.

If every colour-map value sits below 16, ilbmtoppm warns that it is assuming a 4-bit colour map. Add -adjustcolors to scale that map up to 8-bit values:

$ ilbmtoppm -adjustcolors /path/to/source.ilbm > /path/to/adjusted.ppm

Use this because the source format genuinely needs it, not just because the warning is annoying. Scaling changes the numeric colour values, so compare the adjusted image against the original application's intended look.

7. Skip a problematic IFF chunk only with evidence

-ignore takes a four-letter IFF chunk identifier and skips that chunk:

$ ilbmtoppm -ignore ANNO /path/to/source.ilbm > /path/to/without-anno.ppm

This helps when a non-essential chunk is malformed or triggers a compatibility problem, but it can also strip out information that matters for a particular file. Note the identifier you skipped and compare the result against a normal conversion. Do not reach for a guessed identifier as a first response to a parse error.

For a repeatable conversion, keep the original file, the exact command, the Netpbm version, and any diagnostic output together. That is what lets you reproduce a colour difference or recover from a forced interpretation that turned out wrong.

Done means