Convert a Netpbm Image into a Palm Image Viewer PDB

If something still needs to open a picture on an old Palm handheld, pamtopdbimg turns a Netpbm image into the PDB file that Image Viewer expects. Budget about fifteen minutes for the full pass: convert, check the format, set a title, and make the output reproducible for tests.

You need a readable Netpbm image, a shell and a writable working directory. The conversion runs as your ordinary user. Reach for elevated privileges only if you deliberately chose to read from or write to a protected directory, and never use sudo just to make a broken path or permission problem look fixed.

1. Confirm the installed command

Check which binary sits first on your path, then record the Netpbm version. Both are read-only:

$ 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 carries build details after the library version, and exact paths or package revisions will differ on another distribution. One historical note worth knowing: the installed manpage dates -fixedtime to Netpbm 10.98. If your build reports something older, check its local manpage before you rely on that option.

2. Inspect the input without touching it

pamtopdbimg takes one optional input filename. Leave it out and the program reads standard input instead, but naming the file makes a repeatable conversion much 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

Swap in your real image path. Netpbm formats include PBM, PGM, PPM and PAM. file is a useful first pass, but it will not catch a source with a truncated or malformed pixel row, that failure only shows up once pamtopdbimg tries to read it.

• Black-and-white input (maxval 1): becomes a monochrome Palm image.
• Everything else, by default: becomes four-level greyscale.
• Want 16-level greyscale instead: add -4depth.

3. Write the first PDB file

Run the converter against a fresh output name. It writes PDB data to standard output, so 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"

Zero means it finished. The title defaults to unnamed unless you set one. Do not redirect straight over a PDB you still need: > truncates the destination before the converter has even started. Replacing an old result safely means writing new, checking, then moving into place:

$ 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 conversion fails partway, the old palm-image.pdb is untouched. Only remove the incomplete .new file once you are sure you do not need its diagnostics, deleting it cannot be undone.

4. Choose compression deliberately

Pick one, not several: -compressed forces compressed image data, -uncompressed forces uncompressed data, and -maybecompressed picks whichever comes out smaller. That third option matters more than it sounds, because compression can actually make some images bigger:

$ 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

Byte counts depend entirely on the image. In one smoke test against a small greyscale source, compressed output came to 258 bytes against 6544 bytes uncompressed, treat that as a demonstration of the gap, not a promise about your file. Passing conflicting compression flags together leaves the command with no single clear request, so keep scripts explicit and pass exactly one.

5. Set the title and greyscale depth

Quote the title option and its value together as one shell word whenever 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 gets four grey levels, two bits per pixel. Add the flag for sixteen levels, four bits per pixel:

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

-4depth does nothing to a black-and-white input whose maxval is 1. It never resizes, sharpens, or turns colour into full colour, a colour source still comes out as greyscale on this device.

6. Attach a note when the image needs context

Point -notefile= at a separate text file to attach its contents as a note:

$ 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 wants a filename, not the note text itself. Leave -notefile out and no note gets attached. Keep the note file around until you have checked the PDB in whatever workflow actually consumes it, editing the source text afterwards will not update a PDB you already built.

7. Make test output repeatable

Normal PDB metadata carries time values, which is a problem for checksums. Add -fixedtime whenever tests or build comparisons need identical bytes 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 fakes the mtime and ctime inside the PDB for repeatability. It is a testing and verification aid, not a way to preserve the image's real creation time. If two supposedly-identical builds differ, compare the input bytes, title, note, compression and depth options before you suspect anything more exotic.

Common failures

Program takes at most one argument almost always means the title or note option got split into separate shell words. Quote it as one, like '-title=Workshop map' above. An end-of-file error while reading a row points to a truncated or malformed Netpbm source, re-run file and check it with an appropriate Netpbm reader.

If file calls the output a PalmOS document but your viewer rejects it, check which Image Viewer variant that viewer actually supports, and the image depth. Keep the original Netpbm file and the exact command line you used. There is no undo here, because pamtopdbimg only ever writes a new file, recovery just means discarding the new PDB and keeping the source.