Minimum unique abbreviation of option is acceptable. You may use double hyphens instead of single hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value.
This program is part of Netpbm.
pnmtopalm reads a PNM image as input, from Standard Input or pnmfile and produces a Palm Bitmap as output.
Palm Bitmap files are either grayscale files 1, 2, or 4 bits wide, or color files 8 bits wide, so pnmtopalm automatically scales colors to have an appropriate maxval, unless you specify a depth or max depth. Input files must have an appropriate number and set of colors for the selected output constraints.
This often means that you should run the PNM image through pnmquant or pnmremap before you pass it to pnmtopalm. Netpbm comes with several colormap files you can use with pnmremap for this purpose. They are palmgray2.map (4 shades of gray for a depth of 2), palmgray4.map (16 shades of gray for a depth of 4), and palmcolor8.map (232 colors in default Palm colormap). In a standard Netpbm installation, these are in the Netpbm data directory, and you can find the Netpbm data directory with a netpbm-config --datadir shell command.
Example:
pnmremap myimage.ppm \
-mapfile=$(netpbm-config --datadir)/palmgray2.map \
| pnmtopalm -depth=2 >myimage.palm
pnmtopalm generates a Version 0, 1, 2, or 3 Palm Bitmap. It generates the oldest (lowest) version it can for the given image and the options you specify.
All releases of Palm OS can read a Version 0 bitmap. Palm OS 3.0 and later can read a Version 1 bitmap. Palm OS 3.5 and later can read a Version 2 bitmap. To read a Version 3 bitmap, you need Palm OS Garnet or a handheld running the High Density Display Feature Set.
A palm image file can contain multiple renditions of the same image, with different color depths, so a viewer can choose one appropriate for the display. The nextDepthOffset field tells where in the stream the next rendition begins.
pnmtopalm creates a file that contains only one image, but you can separately concatenate multiple one-image files to create a multi-image file. If you do that, you'll need to use -offset so that the resulting concatenation is a correct stream.
By default (if you don't specify -offset), pnmtopalm generates a nextDepthOffset field that says there is no following image (and does not add any padding after the image).
Version 3 Palm Bitmaps actually have a nextBitmapOffset field instead of the nextDepthOffset. The foregoing applies to whichever is relevant.
The -offset option was new in Netpbm 10.26 (January 2005). Before that, pnmtopalm always set the nextDepthOffset field to "none."
Before Netpbm 10.27 (March 2005), you cannot use -offset if you create a compressed raster (because pnmtopalm isn't smart enough to be able to know the size of the image at the time it writes the header). You also cannot use it with 16 bit color depth or with the -colormap option, for much the same reason.
This dummy image header is a special sequence specified in Palm Bitmap specifications. It looks to an older Palm Bitmap interpreter like an invalid image header, so such an interpreter will stop reading the stream there. But a new Palm Bitmap interpreter recognizes it for what it is (just something to choke an old interpreter) and skips over it. Presumably, you will add to the stream after this high density images which would confuse an older interpreter.
If you specify -withdummy, you must also specify -offset, since it doesn't make any sense otherwise.
-withdummy was new in Netpbm 10.27 (March 2005).
This option was new in Netpbm 10.27 (March 2005).
This option was new in Netpbm 10.27 (March 2005). Earlier Netpbm could not generate Version 3 Palm Bitmaps, so there was no such thing as density.
Palm Bitmaps may contains multiple renditions of the same bitmap, in different depths. To construct an N-multiple-rendition Palm Bitmap with pnmtopalm, first construct renditions 1 through N-1 using the -offset option, then construct the Nth image without the -offset option. Then concatenate the individual renditions together in a single file using cat.
If you will include both high density and low density renditions, put the high density images last and when you create the last of the low density images, use the -withdummy option.
If you specify the Palm packbits compression scheme for a 16-bit direct color bitmap, this program generates an invalid bitmap.