Examples of PalmCodec

almos.com/">Palm OS, an operating system for handheld devices.

Supported file types when loading

This codec reads uncompressed, scan line compressed and RLE compressed Palm files with bit depths of 1, 2, 4, 8 and 16 bits per pixel. Not supported are the Packbits compression algorithm or any color depths other then the aforementioned.

Supported image types when saving

Compression types Uncompressed, Scan line and RLE are written. When saving an image as a Palm, the image data classes will be mapped to file types as follows:

{@link BilevelImage}: will be saved as a 1 bit per pixel, monochrome file.
{@link Gray8Image}: will be saved as an 8 bits per pixel file with a custom palette which will contain the 256 shades of gray from black - (0, 0, 0) - to white - (255, 255, 255).
{@link Paletted8Image}: it is first checked if the image is using the Palm system 8 bits per pixel palette. If so, an 8 bits per pixel file with no custom palette is written, otherwise an 8 bits per pixel file with a custom palette (of the original length) is written.
{@link RGB24Image}: will be saved as a 16 bits per pixel, direct color file. Some information will get lost when converting from 24 to 16 bits per pixel. Instead of 256 shades for each red, green and blue (and thus, 256³ = 16,777,216 possible colors) the resulting file will only use 32 shades of red and blue and 64 shades of green (65,536 possible colors).

I/O objects

This codec supports all the I/O classes that are considered in ImageCodec. If you save images and want a correct compressed size field in the resulting Palm file, make sure to give a RandomAccessFile object to the codec. Or simply use {@link #setFile} which does that automatically.

File extension

This codec suggests .palm as file extension for this file format. This is by no means official, but I find it helpful.

Transparency information

The transparency index in a Palm file is saved and loaded, but a loaded index is not stored in the image object as there is no support for transparency information of any kind in PixelImage yet. The RGB transparency color that is present in a file only in direct color mode is read but not written.

Bounds

The bounds concept of ImageCodec is supported so that you can load or save only part of an image.

Open questions on the Palm file format

How does Packbits compression work? Where can I get sample files or a Windows converter that writes those?
How is FLAG_4_BYTE_FIELDS interpreted? When are four byte fields used?
When loading a 4 bpp Palm image file without a custom palette, how is the decoder supposed to know whether to take the predefined color or grayscale palette with 16 entries?

Known problems

Unfortunately, the Palm image file format does not include a signature that makes it easy to identify such a file. Various checks on allowed combinations of color depth, compression type etc. will prevent the codec from trying to interpret all files as Palm image files, but there is still a probability of false identification.

Usage examples

Load an image from a Palm image file:

 PalmCodec codec = new PalmCodec(); codec.setFile("test.palm", CodecMode.LOAD); codec.process(); PixelImage image = codec.getImage(); codec.close();

Save an image to a Palm file using RLE compression:

 PalmCodec codec = new PalmCodec(); codec.setImage(image); codec.setCompression(PalmCodec.COMPRESSION_RLE); codec.setFile("out.palm", CodecMode.SAVE); codec.process(); codec.close();

Background

The code is based on:

the specification Palm Native Image Format,
the source code of the utilities pnmtopalm and palmtopnm that are part of the Netpbm package,
Palm OS Compressed Bitmaps by Ken Krugler, a Palm Developer Knowledge Base article on the scan line compression algorithm and
Palm OS Bitmaps, also part of the Palm Developer Knowledge Base, contains general information on the structure of Palm images.

I also received helpful feedback and test images from Bill Janssen. @author Marco Schmidt