PNMCodec

java.lang.Object
- net.sourceforge.jiu.ops.Operation
- - net.sourceforge.jiu.codecs.ImageCodec
  - - net.sourceforge.jiu.codecs.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:
- PBM (Portable Bitmap - 1 bit per pixel bilevel image),
- PGM (Portable Graymap - grayscale image) and
- PPM (Portable Pixmap - RGB truecolor image).
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

Fields
Modifier and Type	Field	Description
`private Boolean`	`ascii`
`private int`	`columns`
`private int`	`height`
`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 int`	`imageType`
`private PushbackInputStream`	`in`
`private int`	`maxSample`
`private DataOutput`	`out`
`private int`	`width`

Constructor Summary

Constructors
Constructor Description

PNMCodec()

Constructors
Constructor	Description
`PNMCodec()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`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()`	Returns the name of the file format supported by this codec.
`String[]`	`getMimeTypes()`	Return the MIME (Multipurpose Internet Mail Extensions) type strings for this format, or `null` if none are available.
`static String`	`getTypicalFileExtension(int imageType)`	Returns the typical file extension (including leading dot) for an image type.
`boolean`	`isLoadingSupported()`	Returns if this codec is able to load images in the file format supported by this codec.
`boolean`	`isSavingSupported()`	Returns if this codec is able to save images in the file format supported by this codec.
`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 int`	`read16BitBinaryValue()`	Read a 16-bit binary value in network (big-endian) order.
`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)`	Attempts to suggest a filename extension.

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, getImage, getImageIndex, getInputAsDataInput, getInputStream, getMode, getNumComments, getOutputAsDataOutput, getOutputStream, getRandomAccessFile, hasBounds, initModeFromIOObjects, isRowRequired, isTileRequired, removeAllComments, removeBounds, setBounds, setBoundsIfNecessary, setDataInput, setDataOutput, setDpi, setFile, setFile, setImage, setImageIndex, setInputStream, setOutputStream, setRandomAccessFile

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from class net.sourceforge.jiu.ops.Operation
addProgressListener, addProgressListeners, getAbort, removeProgressListener, setAbort, setProgress, setProgress

- Field Detail
  - IMAGE_TYPE_UNKNOWN
```
public static final int IMAGE_TYPE_UNKNOWN
```
    Image type constant for images of unknown type.
    
    See Also:
    
    Constant Field Values
  - IMAGE_TYPE_BILEVEL
```
public static final int IMAGE_TYPE_BILEVEL
```
    Image type constant for bilevel images, stored in PBM files.
    
    See Also:
    
    Constant Field Values
  - IMAGE_TYPE_GRAY
```
public static final int IMAGE_TYPE_GRAY
```
    Image type constant for grayscale images, stored in PGM files.
    
    See Also:
    
    Constant Field Values
  - IMAGE_TYPE_COLOR
```
public static final int IMAGE_TYPE_COLOR
```
    Image type constant for RGB truecolor images, stored in PPM files.
    
    See Also:
    
    Constant Field Values
  - IMAGE_TYPE_FILE_EXTENSIONS
```
private static final String[] IMAGE_TYPE_FILE_EXTENSIONS
```
  - ascii
```
private Boolean ascii
```
  - columns
```
private int columns
```
  - imageType
```
private int imageType
```
  - in
```
private PushbackInputStream in
```
  - out
```
private DataOutput out
```
  - height
```
private int height
```
  - maxSample
```
private int maxSample
```
  - width
```
private int width
```
- Constructor Detail
  - PNMCodec
```
public PNMCodec()
```
- Method Detail
  - determineImageTypeFromFileName
```
public static int determineImageTypeFromFileName(String fileName)
```
    Attempts to find the appropriate image type by looking at a file's name. Ignores case when comparing. Returns IMAGE_TYPE_BILEVEL for .pbm, IMAGE_TYPE_GRAY for .pgm and IMAGE_TYPE_COLOR for .ppm. Otherwise, IMAGE_TYPE_UNKNOWN is returned. To get a file extension given that you have an image type, use getTypicalFileExtension(int).
    
    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
    
    See Also:
    
    setAscii(boolean)
  - getFormatName
```
public String getFormatName()
```
    Description copied from class: ImageCodec
    
    Returns the name of the file format supported by this codec. All classes extending ImageCodec must override this method. When overriding, leave out any words in a particular language so that this format name can be understood by everyone. Usually it is enough to return the format creator plus a typical abbreviation, e.g. Microsoft BMP or Portable Anymap (PNM).
    
    Specified by:
    
    getFormatName in class ImageCodec
    
    Returns:
    
    name of the file format supported by this codec
  - getMimeTypes
```
public String[] getMimeTypes()
```
    Description copied from class: ImageCodec
    
    Return the MIME (Multipurpose Internet Mail Extensions) type strings for this format, or null if none are available.
    
    Specified by:
    
    getMimeTypes in class ImageCodec
    
    Returns:
    
    MIME type strings or null
  - getTypicalFileExtension
```
public static String getTypicalFileExtension(int imageType)
```
    Returns the typical file extension (including leading dot) for an image type. Returns null for IMAGE_TYPE_UNKNOWN. To get the image type given that you have a file name, use determineImageTypeFromFileName(java.lang.String).
    
    Parameters:
    
    imageType - the image type for which the extension is required
    
    Returns:
    
    the file extension or null
  - isLoadingSupported
```
public boolean isLoadingSupported()
```
    Description copied from class: ImageCodec
    
    Returns if this codec is able to load images in the file format supported by this codec. If true is returned this does not necessarily mean that all files in this format can be read, but at least some.
    
    Specified by:
    
    isLoadingSupported in class ImageCodec
    
    Returns:
    
    if loading is supported
  - isSavingSupported
```
public boolean isSavingSupported()
```
    Description copied from class: ImageCodec
    
    Returns if this codec is able to save images in the file format supported by this codec. If true is returned this does not necessarily mean that all types files in this format can be written, but at least some.
    
    Specified by:
    
    isSavingSupported in class ImageCodec
    
    Returns:
    
    if saving is supported
  - 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 ImageCodec.setInputStream(InputStream).
    
    Throws:
    
    InvalidFileStructureException - if the input stream is not a valid PNM stream (or unsupported)
    
    IOException - if there were problems reading from the input stream
    
    MissingParameterException
    
    UnsupportedTypeException
    
    WrongFileFormatException
    
    WrongParameterException
  - loadAsciiNumber
```
private int loadAsciiNumber()
                     throws InvalidFileStructureException,
                            IOException
```
    Throws:
    
    InvalidFileStructureException
    
    IOException
  - loadBilevelImage
```
private void loadBilevelImage()
                       throws InvalidFileStructureException,
                              IOException,
                              WrongParameterException
```
    Throws:
    
    InvalidFileStructureException
    
    IOException
    
    WrongParameterException
  - loadBilevelImageAscii
```
private void loadBilevelImageAscii()
                            throws InvalidFileStructureException,
                                   IOException
```
    Throws:
    
    InvalidFileStructureException
    
    IOException
  - loadBilevelImageBinary
```
private void loadBilevelImageBinary()
                             throws InvalidFileStructureException,
                                    IOException
```
    Throws:
    
    InvalidFileStructureException
    
    IOException
  - read16BitBinaryValue
```
private int read16BitBinaryValue()
                          throws IOException
```
    Read a 16-bit binary value in network (big-endian) order.
    
    Returns:
    
    An integer between 0 and 65535, or -1 for EOF.
    
    Throws:
    
    IOException - If the underlying read operation failed.
  - loadColorImage
```
private void loadColorImage()
                     throws InvalidFileStructureException,
                            IOException
```
    Throws:
    
    InvalidFileStructureException
    
    IOException
  - loadGrayImage
```
private void loadGrayImage()
                    throws InvalidFileStructureException,
                           IOException,
                           UnsupportedTypeException
```
    Throws:
    
    InvalidFileStructureException
    
    IOException
    
    UnsupportedTypeException
  - loadTextLine
```
private String loadTextLine()
                     throws InvalidFileStructureException,
                            IOException
```
    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
    
    InvalidFileStructureException - if the format that is described above was not encountered
    
    IOException - if there were errors reading data
    
    IllegalArgumentException - if the input stream was not given to this codec
  - process
```
public void process()
             throws MissingParameterException,
                    OperationFailedException
```
    Description copied from class: Operation
    
    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 class Operation
    
    Throws:
    
    MissingParameterException - if any mandatory parameter was not given to the operation
    
    WrongParameterException - if at least one of the input parameters was not initialized appropriately (values out of the valid interval, etc.)
    
    OperationFailedException
  - save
```
private void save()
           throws IOException,
                  MissingParameterException,
                  WrongParameterException
```
    Throws:
    
    IOException
    
    MissingParameterException
    
    WrongParameterException
  - save
```
private void save(BilevelImage image)
           throws IOException
```
    Throws:
    
    IOException
  - save
```
private void save(Gray8Image image)
           throws IOException
```
    Throws:
    
    IOException
  - save
```
private void save(Gray16Image image)
           throws IOException
```
    Throws:
    
    IOException
  - save
```
private void save(RGB24Image image)
           throws IOException
```
    Throws:
    
    IOException
  - save
```
private void save(RGB48Image image)
           throws IOException
```
    Throws:
    
    IOException
  - saveAsciiNumber
```
private void saveAsciiNumber(int number)
                      throws IOException
```
    Throws:
    
    IOException
  - saveHeader
```
private void saveHeader()
                 throws IOException
```
    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
```
    Throws:
    
    InvalidFileStructureException
  - setResolution
```
private void setResolution(String line)
                    throws InvalidFileStructureException
```
    Throws:
    
    InvalidFileStructureException
  - suggestFileExtension
```
public String suggestFileExtension(PixelImage image)
```
    Description copied from class: ImageCodec
    
    Attempts to suggest a filename extension. The type of the argument image will be taken into consideration, although this will be necessary for some file formats only (as an example, PNM has different extensions for different image types, see PNMCodec). This default implementation always returns null.
    
    Overrides:
    
    suggestFileExtension in class ImageCodec
    
    Parameters:
    
    image - the image that is to be written to a file
    
    Returns:
    
    the file extension, including a leading dot, or null if no file extension can be recommended

Class PNMCodec

Compression

ASCII mode / binary mode

Color depth for PGM / PPM

DPI values

Number of images

Usage example - load an image from a PNM file

Usage example - save an image to a PNM file

Field Summary

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

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

Field Detail

IMAGE_TYPE_UNKNOWN

IMAGE_TYPE_BILEVEL

IMAGE_TYPE_GRAY

IMAGE_TYPE_COLOR

IMAGE_TYPE_FILE_EXTENSIONS

ascii

columns

imageType

in

out

height

maxSample

width

Constructor Detail

PNMCodec

Method Detail

determineImageTypeFromFileName

getAscii

getFormatName

getMimeTypes

getTypicalFileExtension

isLoadingSupported

isSavingSupported

load

loadAsciiNumber

loadBilevelImage

loadBilevelImageAscii

loadBilevelImageBinary

read16BitBinaryValue

loadColorImage

loadGrayImage

loadTextLine

loadType

process

save

save

save

save

save

save

saveAsciiNumber

saveHeader

setAscii

setMaximumSample

setResolution

suggestFileExtension