net.sourceforge.jiu.codecs

Class PalmCodec


public class PalmCodec
extends ImageCodec

A codec to read and write image files in the native image file format of 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:

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 setFile(String,CodecMode) 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

Known problems

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: I also received helpful feedback and test images from Bill Janssen.
Author:
Marco Schmidt

Field Summary

static int
COMPRESSION_NONE
Constant for compression type Uncompressed.
static int
COMPRESSION_PACKBITS
Constant for compression type Packbits.
static int
COMPRESSION_RLE
Constant for compression type RLE (run length encoding).
static int
COMPRESSION_SCANLINE
Constant for compression type Scanline.
private static int
FLAG_COLOR_TABLE
private static int
FLAG_COMPRESSED
private static int
FLAG_DIRECT_COLOR
private static int
FLAG_TRANSPARENCY
private static short[][]
PALM_SYSTEM_PALETTE_16_COLOR
private static short[][]
PALM_SYSTEM_PALETTE_16_GRAY
private static short[][]
PALM_SYSTEM_PALETTE_256
private static short[][]
PALM_SYSTEM_PALETTE_4_GRAY
private int
bitsPerPixel
private int
blueBits
private int
bytesPerRow
private long
compressedDataOffset
private int
compression
private int
flags
private int
greenBits
private int
height
private Palette
palette
private int
redBits
private byte[]
rgb
private byte[]
transColor
private int
transparencyIndex
private int
version
private int
width

Fields inherited from class net.sourceforge.jiu.codecs.ImageCodec

boundsAvail, boundsHeight, boundsWidth, boundsX1, boundsX2, boundsY1, boundsY2, comments, din, dout, dpiX, dpiY, image, imageIndex, in, mode, out, raf

Fields inherited from class net.sourceforge.jiu.ops.Operation

abort, progressListeners

Method Summary

private static Palette
createPalette(short[][] data)
static Palette
createSystem2BitGrayscalePalette()
Creates the 2 bits per pixel Palm system palette with grayscale values.
static Palette
createSystem4BitColorPalette()
Creates the 4 bits per pixel Palm system palette with color values.
static Palette
createSystem4BitGrayscalePalette()
Creates the 4 bits per pixel Palm system palette with grayscale values.
static Palette
createSystem8BitPalette()
Creates the 8 bits per pixel Palm system palette.
int
getCompression()
Returns the Palm compression method.
String
getFormatName()
String[]
getMimeTypes()
int
getTransparencyIndex()
Returns the transpareny index if one is available (hasTransparencyIndex() returns true) or an undefined value otherwise.
boolean
hasTransparencyIndex()
Returns whether a transpareny index is available and can be retrieved via getTransparencyIndex().
private void
invertBilevelData(byte[] row)
private static boolean
isEqualPalette(Palette palette, short[][] data)
boolean
isLoadingSupported()
static boolean
isPalmSystemPalette256(Palette palette)
Returns if the argument palette is the Palm system palette with 256 colors.
static boolean
isPalmSystemPaletteColor16(Palette palette)
Returns if the argument palette is the Palm system color palette with 16 entries.
static boolean
isPalmSystemPaletteGray16(Palette palette)
Returns if the argument palette is the Palm system grayscale palette with 16 entries.
static boolean
isPalmSystemPaletteGray4(Palette palette)
Returns if the argument palette is the Palm system grayscale palette with 4 entries.
boolean
isSavingSupported()
private void
load()
private void
loadHeader(DataInput in)
private void
loadImage(DataInput in)
private void
loadImageData(DataInput in)
private void
loadPalette(DataInput in)
void
process()
void
removeTransparencyIndex()
Removes the transparency index if one has been set.
private void
save()
private void
save(DataOutput out, BilevelImage image)
private void
save(DataOutput out, Gray8Image image)
private void
save(DataOutput out, Paletted8Image image)
private void
save(DataOutput out, RGB24Image image)
private void
saveFinalCompressedSize(DataOutput out)
private void
saveHeader(DataOutput out)
private void
saveInitialCompressedSize(DataOutput out)
private void
savePalette(DataOutput out, Palette palette)
private void
saveRow(DataOutput out, boolean firstRow, byte[] row, byte[] prev)
private void
saveRowRLE(DataOutput out, byte[] row)
private void
saveRowScanLine(DataOutput out, boolean firstRow, byte[] row, byte[] prev)
void
setCompression(int newCompressionType)
Sets the compression algorithm to be used for saving an image.
private void
setCorrectVersion()
void
setFile(String fileName, CodecMode codecMode)
Reuses super.setFile when used for CodecMode.LOAD, but creates a RandomAccessFile instead of a FileOutputStream in write mode so that the compressed size can be written correcly (requires a seek operation).
void
setTransparencyIndex(int newIndex)
Sets a new transparency index when saving an image.
private void
store(PixelImage image, int y, byte[] row)
String
suggestFileExtension(PixelImage image)

Methods inherited from class net.sourceforge.jiu.codecs.ImageCodec

appendComment, checkBounds, checkImageResolution, close, getBoundsHeight, getBoundsWidth, getBoundsX1, getBoundsX2, getBoundsY1, getBoundsY2, getComment, getDataInput, getDataOutput, getDpiX, getDpiY, getFileExtensions, getFormatName, getImage, getImageIndex, getInputAsDataInput, getInputStream, getMimeTypes, getMode, getNumComments, getOutputAsDataOutput, getOutputStream, getRandomAccessFile, hasBounds, initModeFromIOObjects, isLoadingSupported, isRowRequired, isSavingSupported, isTileRequired, removeAllComments, removeBounds, setBounds, setBoundsIfNecessary, setDataInput, setDataOutput, setDpi, setFile, setFile, setImage, setImageIndex, setInputStream, setOutputStream, setRandomAccessFile, suggestFileExtension

Methods inherited from class net.sourceforge.jiu.ops.Operation

addProgressListener, addProgressListeners, getAbort, process, removeProgressListener, setAbort, setProgress, setProgress

Field Details

COMPRESSION_NONE

public static final int COMPRESSION_NONE
Constant for compression type Uncompressed.
Field Value:
255

COMPRESSION_PACKBITS

public static final int COMPRESSION_PACKBITS
Constant for compression type Packbits.
Field Value:
2

COMPRESSION_RLE

public static final int COMPRESSION_RLE
Constant for compression type RLE (run length encoding).
Field Value:
1

COMPRESSION_SCANLINE

public static final int COMPRESSION_SCANLINE
Constant for compression type Scanline.
Field Value:
0

FLAG_COLOR_TABLE

private static final int FLAG_COLOR_TABLE
Field Value:
16384

FLAG_COMPRESSED

private static final int FLAG_COMPRESSED
Field Value:
32768

FLAG_DIRECT_COLOR

private static final int FLAG_DIRECT_COLOR
Field Value:
1024

FLAG_TRANSPARENCY

private static final int FLAG_TRANSPARENCY
Field Value:
8192

PALM_SYSTEM_PALETTE_16_COLOR

private static final short[][] PALM_SYSTEM_PALETTE_16_COLOR

PALM_SYSTEM_PALETTE_16_GRAY

private static final short[][] PALM_SYSTEM_PALETTE_16_GRAY

PALM_SYSTEM_PALETTE_256

private static final short[][] PALM_SYSTEM_PALETTE_256

PALM_SYSTEM_PALETTE_4_GRAY

private static final short[][] PALM_SYSTEM_PALETTE_4_GRAY

bitsPerPixel

private int bitsPerPixel

blueBits

private int blueBits

bytesPerRow

private int bytesPerRow

compressedDataOffset

private long compressedDataOffset

compression

private int compression

flags

private int flags

greenBits

private int greenBits

height

private int height

palette

private Palette palette

redBits

private int redBits

rgb

private byte[] rgb

transColor

private byte[] transColor

transparencyIndex

private int transparencyIndex

version

private int version

width

private int width

Method Details

createPalette

private static Palette createPalette(short[][] data)

createSystem2BitGrayscalePalette

public static Palette createSystem2BitGrayscalePalette()
Creates the 2 bits per pixel Palm system palette with grayscale values. This palette is used when no custom palette is defined in a 2 bpp image.
Returns:
Palm's default palette for 2 bits per pixel (grayscale), with 4 entries

createSystem4BitColorPalette

public static Palette createSystem4BitColorPalette()
Creates the 4 bits per pixel Palm system palette with color values. This palette (or the 4 bpp grayscale palette) is used when no custom palette is defined in a 4 bpp image.
Returns:
Palm's default palette for 4 bits per pixel (color), with 16 entries

createSystem4BitGrayscalePalette

public static Palette createSystem4BitGrayscalePalette()
Creates the 4 bits per pixel Palm system palette with grayscale values. This palette (or the 4 bpp color palette) is used when no custom palette is defined in a 4 bpp image.
Returns:
Palm's default palette for 4 bits per pixel (grayscale), with 16 entries

createSystem8BitPalette

public static Palette createSystem8BitPalette()
Creates the 8 bits per pixel Palm system palette. This palette is used when no custom palette is defined in an 8 bpp image.
Returns:
Palm's default palette for 8 bits per pixel, with 256 entries

getCompression

public int getCompression()
Returns the Palm compression method. This should be one of the COMPRESSION_xyz constants of this class.
Returns:
integer value with the compression method (found in a file when loading or to be used for saving)

getFormatName

public String getFormatName()
Overrides:
getFormatName in interface ImageCodec

getMimeTypes

public String[] getMimeTypes()
Overrides:
getMimeTypes in interface ImageCodec

getTransparencyIndex

public int getTransparencyIndex()

hasTransparencyIndex

public boolean hasTransparencyIndex()
Returns:
transparency index, a positive value that is a valid index into the palette

invertBilevelData

private void invertBilevelData(byte[] row)

isEqualPalette

private static boolean isEqualPalette(Palette palette,
                                      short[][] data)

isLoadingSupported

public boolean isLoadingSupported()
Overrides:
isLoadingSupported in interface ImageCodec

isPalmSystemPalette256

public static boolean isPalmSystemPalette256(Palette palette)
Returns if the argument palette is the Palm system palette with 256 colors.
Parameters:
palette - to be checked
Returns:
if the argument is an 8 bits per pixel Palm system palette

isPalmSystemPaletteColor16

public static boolean isPalmSystemPaletteColor16(Palette palette)
Returns if the argument palette is the Palm system color palette with 16 entries.
Parameters:
palette - to be checked

isPalmSystemPaletteGray16

public static boolean isPalmSystemPaletteGray16(Palette palette)
Returns if the argument palette is the Palm system grayscale palette with 16 entries.
Parameters:
palette - to be checked

isPalmSystemPaletteGray4

public static boolean isPalmSystemPaletteGray4(Palette palette)
Returns if the argument palette is the Palm system grayscale palette with 4 entries.
Parameters:
palette - to be checked

isSavingSupported

public boolean isSavingSupported()
Overrides:
isSavingSupported in interface ImageCodec

load

private void load()
            throws InvalidFileStructureException,
                   IOException,
                   OperationFailedException,
                   UnsupportedTypeException,
                   WrongFileFormatException

loadHeader

private void loadHeader(DataInput in)
            throws InvalidFileStructureException,
                   IOException,
                   UnsupportedTypeException,
                   WrongFileFormatException

loadImage

private void loadImage(DataInput in)
            throws InvalidFileStructureException,
                   IOException,
                   UnsupportedTypeException,
                   WrongFileFormatException,
                   WrongParameterException

loadImageData

private void loadImageData(DataInput in)
            throws InvalidFileStructureException,
                   IOException

loadPalette

private void loadPalette(DataInput in)
            throws InvalidFileStructureException,
                   IOException,
                   UnsupportedTypeException,
                   WrongFileFormatException

process

public void process()
            throws InvalidFileStructureException,
                   MissingParameterException,
                   OperationFailedException,
                   WrongParameterException
Overrides:
process in interface Operation

removeTransparencyIndex

public void removeTransparencyIndex()
Removes the transparency index if one has been set.

save

private void save()
            throws IOException,
                   OperationFailedException,
                   UnsupportedTypeException

save

private void save(DataOutput out,
                  BilevelImage image)
            throws IOException

save

private void save(DataOutput out,
                  Gray8Image image)
            throws IOException

save

private void save(DataOutput out,
                  Paletted8Image image)
            throws IOException

save

private void save(DataOutput out,
                  RGB24Image image)
            throws IOException

saveFinalCompressedSize

private void saveFinalCompressedSize(DataOutput out)
            throws IOException

saveHeader

private void saveHeader(DataOutput out)
            throws IOException

saveInitialCompressedSize

private void saveInitialCompressedSize(DataOutput out)
            throws IOException

savePalette

private void savePalette(DataOutput out,
                         Palette palette)
            throws IOException

saveRow

private void saveRow(DataOutput out,
                     boolean firstRow,
                     byte[] row,
                     byte[] prev)
            throws IOException

saveRowRLE

private void saveRowRLE(DataOutput out,
                        byte[] row)
            throws IOException

saveRowScanLine

private void saveRowScanLine(DataOutput out,
                             boolean firstRow,
                             byte[] row,
                             byte[] prev)
            throws IOException

setCompression

public void setCompression(int newCompressionType)
Sets the compression algorithm to be used for saving an image.
Parameters:
newCompressionType - int value that is one of the COMPRESSION_xyz constants of this class

setCorrectVersion

private void setCorrectVersion()

setFile

public void setFile(String fileName,
                    CodecMode codecMode)
            throws IOException,
                   UnsupportedCodecModeException
Reuses super.setFile when used for CodecMode.LOAD, but creates a RandomAccessFile instead of a FileOutputStream in write mode so that the compressed size can be written correcly (requires a seek operation).
Overrides:
setFile in interface ImageCodec
Parameters:
fileName - name of the file to be opened
codecMode - defines whether this codec object is to be used for loading or saving

setTransparencyIndex

public void setTransparencyIndex(int newIndex)
Sets a new transparency index when saving an image. If this method is called, the argument value is used as an index into the palette for a color that is supposed to be transparent. When the resulting Palm image file is drawn onto some background, all pixels in the color pointed to by the transparency index are not supposed to be overdrawn so that the background is visisble at those places.
Parameters:
newIndex - the new transparency index, must be smaller than the number of entries in the palette

store

private void store(PixelImage image,
                   int y,
                   byte[] row)

suggestFileExtension

public String suggestFileExtension(PixelImage image)
Overrides:
suggestFileExtension in interface ImageCodec