Convert Palm Bitmaps to PPM with palmtopnm

Old PalmOS devices left behind a pile of Palm Bitmap files, and palmtopnm is the Netpbm tool that turns them into a format anything modern can open. You will finish with a converted PPM image, plus a safe way to check whether the source has a transparent colour. This guide uses Netpbm 11.5.2 from the installed netpbm package. Allow about ten minutes if you already have a Palm Bitmap, or longer if you first need to locate one.

palmtopnm reads a Palm Bitmap from a named file or standard input and writes a PPM image to standard output. It is an ordinary user-level conversion: the examples do not need sudo, and none of them modify the input file.

1. Confirm the installed command

Check which executable will run and record the local Netpbm build information:

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

The version output also includes build details. Exact wording can vary, but the important check is that this is the Netpbm build you expect. If command -v returns nothing, install the distribution's Netpbm package through its normal package-management process first; that is the only step here that changes system state, and it needs the privileges appropriate to your distribution.

2. Convert one Palm Bitmap

Write the converted image to a new file. The redirection matters: without it, binary PPM data lands in your terminal.

$ test -r /path/to/bitmap.palm
$ palmtopnm /path/to/bitmap.palm > /path/to/bitmap.ppm
$ file /path/to/bitmap.ppm
/path/to/bitmap.ppm: Netpbm image data

The exact description from file depends on the image, so treat it as a quick sanity check rather than proof. A successful conversion normally prints no progress text on standard output, because that stream carries the image. With -verbose, informational text is shown while the image remains the command's output.

This example creates or replaces /path/to/bitmap.ppm. Before running it on a valuable output, choose a new destination or make a backup. Recovery is simple if the destination is disposable: remove the generated PPM and repeat the conversion. The Palm Bitmap source is never touched.

3. Read from standard input when a pipeline is useful

The input filename is optional, which lets you pass a file through a pipeline while keeping the PPM destination explicit:

$ palmtopnm < /path/to/bitmap.palm > /path/to/bitmap.ppm
$ test -s /path/to/bitmap.ppm && printf '%s\n' 'PPM output was written'
PPM output was written

Use one input source at a time: a named file and standard input are not two images to combine. Keep the output redirection separate from diagnostic messages, so a downstream image reader receives only PPM data.

If conversion fails, rerun without overwriting the destination and capture the diagnostic stream:

$ palmtopnm /path/to/bitmap.palm > /tmp/palmtopnm-test.ppm
$ status=$?
$ printf 'palmtopnm exit status: %s\n' "$status"
palmtopnm exit status: 0

Only treat status 0 as a successful conversion. A non-zero status can leave a partial output file, so do not feed that file to another image-processing step as if it were complete. Delete the temporary file once you have inspected the error:

$ rm -f /tmp/palmtopnm-test.ppm

4. Select a different rendition

A Palm Bitmap can hold several renditions of the same image at different depths. By default, palmtopnm uses rendition number 1. If the file has more renditions, pick a number from 1 through the number available:

$ palmtopnm -rendition 2 /path/to/bitmap.palm > /path/to/bitmap-rendition-2.ppm

There is no universal safe value for the number. Start with the default, then use -verbose to inspect the input before picking another rendition:

$ palmtopnm -verbose /path/to/bitmap.palm > /tmp/bitmap-verbose.ppm
$ printf 'exit status: %s\n' "$?"
exit status: 0

Keep the verbose output out of the PPM file if you redirect diagnostics separately for a shell or script that needs strict stream handling. If rendition 2 is outside the file's range, the command should fail rather than silently inventing a rendition. Use the exact available range the command reports, and remove any partial output after a failed attempt.

5. Inspect transparency without generating an image

Use -transparent when you need the Palm Bitmap's transparent colour rather than a converted image:

$ palmtopnm -transparent /path/to/bitmap.palm
#RRGGBB

The value prints as a hash followed by six hexadecimal digits, such as #00FF80, for red, green and blue from 0 through 255. If the Bitmap has no transparent colour, the command writes nothing. This mode does not generate a PPM image, so do not redirect it to a file you expect an image viewer to open.

Capture the value only when it exists:

transparent=$(palmtopnm -transparent /path/to/bitmap.palm)
if [ -n "$transparent" ]; then
    printf 'transparent colour: %s\n' "$transparent"
else
    printf '%s\n' 'no transparent colour is set'
fi

Quote the variable when you reuse it. An empty result is not an error: it is the documented result for a Bitmap without a transparent colour.

6. Make a transparency mask when needed

palmtopnm does not create a transparency mask itself. The Netpbm manual documents a separate pipeline using ppmcolormask, with the colour read from the same source file:

$ ppmcolormask "$(palmtopnm -transparent /path/to/bitmap.palm)" \
    < /path/to/bitmap.ppm > /path/to/bitmap-mask.pgm

Use that only when the transparent-colour query returns a value and the PPM came from the same Bitmap rendition. If the query is empty, stop instead of passing an empty colour argument. The pipeline writes a new mask file; it does not alter either source file. Check ppmcolormask exists with command -v ppmcolormask before using the example.

7. Handle the usual mistakes

• Binary data in the terminal: you omitted the output redirection. Press Ctrl-C if necessary, then repeat with > output.ppm.
• Empty or incomplete output: inspect the exit status immediately after palmtopnm and remove the partial file before retrying.
• A rendition number fails: it may be outside the file's available range. Try the default and inspect -verbose output before choosing another number.
• -transparent prints nothing: that can mean no transparent colour is set. It does not mean a PPM image was emitted.
• Do not use -forceplain: that old option is from pre-10.23 documentation. The manual says the common -plain option made it redundant, and it is not part of this guide's examples.