Package net.sourceforge.jiu.codecs

# Class 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 final int`
`IMAGE_TYPE_BILEVEL`
Image type constant for bilevel images, stored in PBM files.
`static final int`
`IMAGE_TYPE_COLOR`
Image type constant for RGB truecolor images, stored in PPM files.
`private static final String[]`
`IMAGE_TYPE_FILE_EXTENSIONS`
`static final int`
`IMAGE_TYPE_GRAY`
Image type constant for grayscale images, stored in PGM files.
`static final 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()`

## Method Summary

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 net.sourceforge.jiu.ops.Operation

`addProgressListener, addProgressListeners, getAbort, removeProgressListener, setAbort, setProgress, setProgress`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### 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 Details

### PNMCodec

public PNMCodec()

## Method Details

### 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
  `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