net.sourceforge.jiu.codecs

Class PNMCodec


public class PNMCodec
extends ImageCodec

A codec to read and write Portable Anymap (PNM) image files. This format includes three file types well-known in the Unix world:

Compression

The file format only allows for uncompressed storage.

ASCII mode / binary mode

PNM streams can be stored in binary mode or ASCII mode. ASCII mode files are text files with numbers representing the pixels. They become larger than their binary counterparts, but as they are very redundant they can be compressed well with archive programs. ASCII PGM and PPM files can have all kinds of maximum sample values, thus allowing for arbitrary precision. They are not restricted by byte limits. PBM streams always have two colors, no matter if they are ASCII or binary.

Color depth for PGM / PPM

The header of a PGM and PPM file stores a maximum sample value (such a value is not stored for PBM, where the maximum value is always 1). When in binary mode, PGM and PPM typically have a maximum sample value of 255, which makes PGM 8 bits per pixel and PPM 24 bits per pixel large. One sample will be stored as a single byte. However, there also exist binary PGM files with a maximum sample value larger than 255 and smaller than 65536. These files use two bytes per sample, in network byte order (big endian). I have yet to see PPM files with that property, but they are of course imagineable. 16 bpp

DPI values

PNM files cannot store the physical resolution in DPI.

Number of images

Only one image can be stored in a PNM file.

Usage example - load an image from a PNM file

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

Usage example - save an image to a PNM file

 PNMCodec codec = new PNMCodec();
 BilevelImage myFax = ...; // initialize
 codec.setImage(myFax);
 codec.setFile("out.pbm", CodecMode.SAVE);
 codec.process();
 codec.close();
 
Author:
Marco Schmidt

Field Summary

static int
IMAGE_TYPE_BILEVEL
Image type constant for bilevel images, stored in PBM files.
static int
IMAGE_TYPE_COLOR
Image type constant for RGB truecolor images, stored in PPM files.
private static String[]
IMAGE_TYPE_FILE_EXTENSIONS
static int
IMAGE_TYPE_GRAY
Image type constant for grayscale images, stored in PGM files.
static int
IMAGE_TYPE_UNKNOWN
Image type constant for images of unknown type.
private Boolean
ascii
private int
columns
private int
height
private int
imageType
private PushbackInputStream
in
private int
maxSample
private DataOutput
out
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

static int
determineImageTypeFromFileName(String fileName)
Attempts to find the appropriate image type by looking at a file's name.
Boolean
getAscii()
Returns if ASCII mode was used for loading an image or will be used to store an image.
String
getFormatName()
String[]
getMimeTypes()
static String
getTypicalFileExtension(int imageType)
Returns the typical file extension (including leading dot) for an image type.
boolean
isLoadingSupported()
boolean
isSavingSupported()
private void
load()
Loads an image from a PNM input stream.
private int
loadAsciiNumber()
private void
loadBilevelImage()
private void
loadBilevelImageAscii()
private void
loadBilevelImageBinary()
private void
loadColorImage()
private void
loadGrayImage()
private String
loadTextLine()
private void
loadType()
Loads the first two characters (which are expected to be a capital P followed by a decimal digit between 1 and 6, inclusively) and skips following LF and CR characters.
void
process()
This method does the actual work of the operation.
private void
save()
private void
save(BilevelImage image)
private void
save(Gray16Image image)
private void
save(Gray8Image image)
private void
save(RGB24Image image)
private void
save(RGB48Image image)
private void
saveAsciiNumber(int number)
private void
saveHeader()
void
setAscii(boolean asciiMode)
Specify whether ASCII mode is to be used when saving an image.
private void
setMaximumSample(String line)
private void
setResolution(String line)
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

IMAGE_TYPE_BILEVEL

public static final int IMAGE_TYPE_BILEVEL
Image type constant for bilevel images, stored in PBM files.
Field Value:
0

IMAGE_TYPE_COLOR

public static final int IMAGE_TYPE_COLOR
Image type constant for RGB truecolor images, stored in PPM files.
Field Value:
2

IMAGE_TYPE_FILE_EXTENSIONS

private static final String[] IMAGE_TYPE_FILE_EXTENSIONS

IMAGE_TYPE_GRAY

public static final int IMAGE_TYPE_GRAY
Image type constant for grayscale images, stored in PGM files.
Field Value:
1

IMAGE_TYPE_UNKNOWN

public static final int IMAGE_TYPE_UNKNOWN
Image type constant for images of unknown type.
Field Value:
-1

ascii

private Boolean ascii

columns

private int columns

height

private int height

imageType

private int imageType

in

private PushbackInputStream in

maxSample

private int maxSample

out

private DataOutput out

width

private int width

Method Details

determineImageTypeFromFileName

public static int determineImageTypeFromFileName(String fileName)
Parameters:
fileName - the file name to be examined
Returns:
one of the IMAGE_TYPE_xxx constants of this class

getAscii

public Boolean getAscii()
Returns if ASCII mode was used for loading an image or will be used to store an image.
Returns:
true for ASCII mode, false for binary mode, null if that information is not available

getFormatName

public String getFormatName()
Overrides:
getFormatName in interface ImageCodec

getMimeTypes

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

getTypicalFileExtension

public static String getTypicalFileExtension(int imageType)
Parameters:
imageType - the image type for which the extension is required
Returns:
the file extension or null

isLoadingSupported

public boolean isLoadingSupported()
Overrides:
isLoadingSupported in interface ImageCodec

isSavingSupported

public boolean isSavingSupported()
Overrides:
isSavingSupported in interface ImageCodec

load

private void load()
            throws InvalidFileStructureException,
                   IOException,
                   MissingParameterException,
                   UnsupportedTypeException,
                   WrongFileFormatException,
                   WrongParameterException
Loads an image from a PNM input stream. It is assumed that a stream was given to this codec using setInputStream(InputStream).

loadAsciiNumber

private int loadAsciiNumber()
            throws InvalidFileStructureException,
                   IOException

loadBilevelImage

private void loadBilevelImage()
            throws InvalidFileStructureException,
                   IOException,
                   WrongParameterException

loadBilevelImageAscii

private void loadBilevelImageAscii()
            throws InvalidFileStructureException,
                   IOException

loadBilevelImageBinary

private void loadBilevelImageBinary()
            throws InvalidFileStructureException,
                   IOException

loadColorImage

private void loadColorImage()
            throws InvalidFileStructureException,
                   IOException

loadGrayImage

private void loadGrayImage()
            throws InvalidFileStructureException,
                   IOException,
                   UnsupportedTypeException

loadTextLine

private String loadTextLine()
            throws InvalidFileStructureException,
                   IOException

loadType

private void loadType()
            throws InvalidFileStructureException,
                   IOException,
                   WrongFileFormatException
Loads the first two characters (which are expected to be a capital P followed by a decimal digit between 1 and 6, inclusively) and skips following LF and CR characters. This method not only checks the two bytes, it also initializes internal fields for storage mode (ASCII or binary) and image type.
Throws:
WrongFileFormatException - if the input stream is not a PNM stream

process

public void process()
            throws MissingParameterException,
                   OperationFailedException
This method does the actual work of the operation. It must be called after all parameters have been given to the operation object.
Overrides:
process in interface Operation
Throws:
MissingParameterException - if any mandatory parameter was not given to the operation
OperationFailedException -

save

private void save()
            throws IOException,
                   MissingParameterException,
                   WrongParameterException

save

private void save(BilevelImage image)
            throws IOException

save

private void save(Gray16Image image)
            throws IOException

save

private void save(Gray8Image image)
            throws IOException

save

private void save(RGB24Image image)
            throws IOException

save

private void save(RGB48Image image)
            throws IOException

saveAsciiNumber

private void saveAsciiNumber(int number)
            throws IOException

saveHeader

private void saveHeader()
            throws IOException

setAscii

public void setAscii(boolean asciiMode)
Specify whether ASCII mode is to be used when saving an image. Default is binary mode.
Parameters:
asciiMode - if true, ASCII mode is used, binary mode otherwise

setMaximumSample

private void setMaximumSample(String line)
            throws InvalidFileStructureException

setResolution

private void setResolution(String line)
            throws InvalidFileStructureException

suggestFileExtension

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