Convert PNM Images to Palm Bitmaps with pnmtopalm

You will convert a PNM image into a Palm Bitmap file, choose an output depth that the target Palm OS can read, and check that the command produced a usable binary file. The examples use Netpbm 11.5.2, installed here as package version 2:11.05.02-1.1build1. The manual page is dated 25 August 2017, so treat the installed command as the authority when another Netpbm release behaves differently.

Allow about fifteen minutes. You need a shell, a readable PNM image, and permission to write in the output directory. Conversion normally needs no elevated privileges. Do not use sudo simply because the output is a binary file.

1. Check the command and keep the original

Confirm which executable will run and inspect the input before choosing an output name:

$ command -v pnmtopalm
/usr/bin/pnmtopalm
$ file /path/to/input.ppm
/path/to/input.ppm: Netpbm image data, size 160 x 160, rawbits, pixmap

pnmtopalm reads a PNM image from the named file or from standard input, and writes the Palm Bitmap to standard output. It does not edit the input. Checkpoint: the input path is readable, and the destination you plan to create is a different path from the original.

2. Make a basic Palm Bitmap

Redirect standard output to a new file. This example lets pnmtopalm choose the depth from the image:

$ pnmtopalm /path/to/input.ppm > /path/to/output.palm
$ test -s /path/to/output.palm && echo 'Palm Bitmap written'
Palm Bitmap written

Use -verbose when you want a short description of the input and selected output format. Its diagnostic text goes to standard error, so it does not become part of the binary file:

$ pnmtopalm -verbose /path/to/input.ppm > /path/to/output.palm
pnmtopalm: Input is 160x160 color, maxval 255
pnmtopalm: Output is color with default colormap at 8 bpp

The exact wording depends on the image. The useful verification is a zero exit status and a non-empty destination. If the command fails, do not trust a partially written destination. Remove only that known temporary output, or rerun into a fresh name.

3. Choose a depth deliberately

Palm Bitmaps can use 1, 2, 4, 8 or 16 bits per pixel. Pass one of those values with -depth when compatibility or file size matters:

$ pnmtopalm -verbose -depth=2 /path/to/input.ppm > /path/to/output-2bpp.palm
pnmtopalm: Input is 160x160 color, maxval 255
pnmtopalm: Output is ... at 2 bpp

The input must contain a suitable number and set of colours for the requested result. A grayscale or monochrome input never becomes more than 4 bits deep, even if you request 8 bits, because the default 8-bit Palm colour map is not grayscale. If your source has too many colours, reduce it first with pnmquant or remap it to a known Netpbm Palm map.

Netpbm supplies maps for four greys, sixteen greys and the default Palm colour palette. Find their directory rather than guessing its location:

$ netpbm-config --datadir
/usr/share/netpbm

For a two-bit greyscale result, remap the image and pipe it into pnmtopalm:

$ pnmremap /path/to/input.ppm \
    -mapfile="$(netpbm-config --datadir)/palmgray2.map" \
  | pnmtopalm -depth=2 > /path/to/output-gray2.palm

Checkpoint: rerun with -verbose if you need to confirm the selected depth. The pipeline's exit status is normally the status of the last command, so when scripting a pipeline with failure detection, use your shell's appropriate pipeline-status feature.

4. Match the file to the Palm OS target

Depth is not the only compatibility decision. An uncompressed bitmap with one bit per pixel can use Palm Bitmap Version 0, which all Palm OS releases can read. More than one bit per pixel requires at least Version 1. A custom colour map raises the minimum to Version 1.

Transparency and compression require at least Version 2. Higher density requires Version 3. The manual associates 8-bit colour with Palm OS 3.5 and later, and 16-bit direct colour with Palm OS 4.0 and later, with a noted compatibility exception for some Handspring Visor systems. Confirm the actual target before selecting these formats.

Compression is selected explicitly:

$ pnmtopalm -scanline_compression /path/to/input.ppm > /path/to/output-scanline.palm
$ pnmtopalm -rle_compression /path/to/input.ppm > /path/to/output-rle.palm
$ pnmtopalm -packbits_compression /path/to/input.ppm > /path/to/output-packbits.palm

Compressed output is limited to 8 bits per pixel, and the command defaults compressed output to 8 bits unless you set -depth. The installed manual also warns that packbits compression with 16-bit direct colour produces an invalid bitmap. Do not combine those options.

5. Add transparency or density only when required

Mark one colour as fully transparent with -transparent. The value uses Netpbm colour syntax:

$ pnmtopalm -transparent=white /path/to/input.ppm > /path/to/output-transparent.palm

Transparency works only on Palm OS 3.5 and later. Density values are limited to 72, 108, 144, 216 and 288:

$ pnmtopalm -density=144 /path/to/input.ppm > /path/to/output-density.palm

A density above low causes a Version 3 bitmap. That format needs Palm OS Garnet or a handheld with the High Density Display Feature Set. A density setting is metadata about intended display resolution, not a resize operation.

6. Build multiple renditions without corrupting the stream

A Palm Bitmap stream can contain several renditions of one image. Create every rendition except the last with -offset, then create the final rendition without it and concatenate the files:

$ pnmtopalm -depth=1 -offset /path/to/input.ppm > /tmp/low.palm
$ pnmtopalm -depth=4 /path/to/input.ppm > /tmp/final.palm
$ cat /tmp/low.palm /tmp/final.palm > /path/to/multiple-depths.palm
$ test -s /path/to/multiple-depths.palm && echo 'rendition stream written'
rendition stream written

-offset pads the file to a four-byte boundary and records that another rendition follows. The final file must omit it so its header marks the end of the stream. If high-density renditions follow low-density ones, the last low-density rendition also needs -withdummy, and -withdummy requires -offset. Keep the temporary files until the combined stream has been tested on the target reader; then remove only those known temporary files.

7. Avoid the common traps

Shell redirection with > truncates an existing destination before pnmtopalm starts. Use a temporary output and rename it only after a successful conversion:

$ pnmtopalm -depth=2 /path/to/input.ppm > /path/to/output.palm.new
$ test -s /path/to/output.palm.new && mv /path/to/output.palm.new /path/to/output.palm

If conversion fails, the old output remains in place and the .new file can be inspected or removed. Do not replace a known-good bitmap until the target reader has accepted the new one.

Also remember that pnmtopalm does not resize an image, does not infer a safe Palm OS target, and does not make an arbitrary colour count fit a selected depth. Use a separate Netpbm preparation command, verify the chosen options, and keep the original PNM untouched.