Convert a Netpbm Image into a Palm Image Viewer PDB

You will finish with a Palm Image Viewer PDB file made from a Netpbm image, plus checks for its format, title and reproducibility. This guide uses pamtopdbimg from Netpbm 11.5.2, provided here by Debian package netpbm 2:11.05.02-1.1build1.

Allow about fifteen minutes. You need a readable Netpbm image, a shell and a writable working directory. The conversion itself normally runs as your ordinary user. You need elevated privileges only if you deliberately read from or write to a protected directory. Do not use sudo to make an image conversion appear to work: fix the path or permissions instead.

1. Confirm the installed command

Check which executable is first in your path, then record the Netpbm version. These are read-only commands:

$ command -v pamtopdbimg
/usr/bin/pamtopdbimg
$ pamtopdbimg --version
pamtopdbimg: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
...
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The version output includes build details after the library version. The exact paths and package revision can differ on another distribution. The installed manpage dates the documented command behaviour to Netpbm 10.98, and says that -fixedtime was added there. If your command reports an older release, check its local manpage before using that option.

2. Inspect the input without changing it

pamtopdbimg accepts one optional input filename. If you omit it, the program reads the image from standard input, but using a named file makes a repeatable conversion easier to inspect:

$ input='/path/to/source.pgm'
$ test -r "$input" && echo 'input is readable'
input is readable
$ file "$input"
/path/to/source.pgm: Netpbm image data, size = 160 x 160, rawbits, greymap

Replace the placeholder with your actual image. Netpbm images include formats such as PBM, PGM, PPM and PAM. file is a useful first check, but it does not prove that every pixel row is complete. A truncated or malformed source will make pamtopdbimg fail while it is reading the image.

Input depth affects the PDB representation. A black-and-white image with maxval 1 becomes a monochrome Palm image. Other input becomes four-level greyscale by default, unless you request 16-level greyscale with -4depth.

3. Write the first PDB file

Run the converter with a fresh output name. The program writes the PDB data to standard output, so shell redirection supplies the destination:

$ output='palm-image.pdb'
$ pamtopdbimg "$input" > "$output"
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ file "$output"
palm-image.pdb: FireViewer/ImageViewer PalmOS document "unnamed"

A zero exit status means the conversion completed. The title is unnamed unless you provide one. Do not redirect straight over a PDB that you still need: > truncates its destination before the converter starts. If you need to replace an old result, create a new file first and move it into place only after checking it:

$ new_output='palm-image.pdb.new'
$ pamtopdbimg "$input" > "$new_output" && mv -- "$new_output" "$output"
$ test -s "$output" && echo 'PDB is non-empty'
PDB is non-empty

If the conversion fails, the old palm-image.pdb remains untouched. Remove the incomplete .new file only after confirming that you no longer need its diagnostics; deleting it is irreversible.

4. Choose compression deliberately

Specify at most one of the three compression options. -compressed requests compressed image data, -uncompressed requests uncompressed data, and -maybecompressed chooses whichever representation is smaller. The last option matters because compression can make some images larger:

$ pamtopdbimg -compressed "$input" > palm-image-compressed.pdb
$ pamtopdbimg -uncompressed "$input" > palm-image-uncompressed.pdb
$ pamtopdbimg -maybecompressed "$input" > palm-image-small.pdb
$ wc -c palm-image-compressed.pdb palm-image-uncompressed.pdb palm-image-small.pdb

The byte counts depend on the image. In a smoke test with a small greyscale input, the compressed output was 258 bytes and the uncompressed output was 6544 bytes. Treat those figures as an example of the difference, not a size promise. If you pass conflicting compression options, the command no longer has a single clear request; keep scripts explicit and pass one only.

5. Set the title and greyscale depth

Put the title and its value into one quoted shell argument when the text contains spaces:

$ pamtopdbimg '-title=Workshop map' "$input" > workshop-map.pdb
$ file workshop-map.pdb
workshop-map.pdb: FireViewer/ImageViewer PalmOS document "Workshop map"

Without -4depth, a non-monochrome image uses four greyscale levels, or two bits per pixel. Add -4depth for 16 levels, or four bits per pixel:

$ pamtopdbimg -4depth "$input" > workshop-map-16-level.pdb

-4depth has no effect on a black-and-white input whose maxval is 1. It does not resize the image, sharpen it or turn colour into full colour. If the source contains colour, pamtopdbimg produces a greyscale Palm representation.

6. Attach a note when the image needs context

Use -notefile= to attach the contents of a separate note file:

$ note='/path/to/description.txt'
$ test -r "$note" && echo 'note is readable'
note is readable
$ pamtopdbimg "-notefile=$note" '-title=Workshop map' "$input" > workshop-map-with-note.pdb

The option takes a filename, not the note text itself. Omitting -notefile attaches no note. Keep the note file until you have checked the PDB in the Palm Image Viewer workflow that will consume it; changing the source text later does not update an already-created PDB.

7. Make test output repeatable

Normal PDB metadata can include time values. Add -fixedtime when tests, checksums or build comparisons need identical output for identical input:

$ pamtopdbimg -fixedtime "$input" > build-a.pdb
$ pamtopdbimg -fixedtime "$input" > build-b.pdb
$ cmp --silent build-a.pdb build-b.pdb && echo 'byte-for-byte identical'
byte-for-byte identical

This option fakes the PDB image mtime and ctime values for repeatability. It is for testing and verification, not for preserving the time at which the image was created. If the files differ, compare the input bytes, title, note, compression and depth options before investigating anything more complicated.

Common failures

Program takes at most one argument usually means the title or note option was split into multiple shell words. Quote an option such as '-title=Workshop map' as shown above. An end-of-file error while reading a row points to a truncated or malformed Netpbm input; re-run file and test the source with an appropriate Netpbm reader.

If file identifies the output as a PalmOS document but your viewer rejects it, check the viewer's supported Image Viewer variant and the image depth. Keep the original Netpbm file and the command line used. pamtopdbimg does not provide an undo operation because it writes a new file; recovery is simply to discard the new PDB and retain the source.