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 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()
-
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, ornull
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
-
-
-
-
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
-
-
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. ReturnsIMAGE_TYPE_BILEVEL
for.pbm
,IMAGE_TYPE_GRAY
for.pgm
andIMAGE_TYPE_COLOR
for.ppm
. Otherwise,IMAGE_TYPE_UNKNOWN
is returned. To get a file extension given that you have an image type, usegetTypicalFileExtension(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 extendingImageCodec
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
orPortable Anymap (PNM)
.- Specified by:
getFormatName
in classImageCodec
- 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, ornull
if none are available.- Specified by:
getMimeTypes
in classImageCodec
- 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. Returnsnull
forIMAGE_TYPE_UNKNOWN
. To get the image type given that you have a file name, usedetermineImageTypeFromFileName(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. Iftrue
is returned this does not necessarily mean that all files in this format can be read, but at least some.- Specified by:
isLoadingSupported
in classImageCodec
- 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. Iftrue
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 classImageCodec
- 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 usingImageCodec.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 streamMissingParameterException
UnsupportedTypeException
WrongFileFormatException
WrongParameterException
-
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
-
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
-
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 streamInvalidFileStructureException
- if the format that is described above was not encounteredIOException
- if there were errors reading dataIllegalArgumentException
- 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 classOperation
- Throws:
MissingParameterException
- if any mandatory parameter was not given to the operationWrongParameterException
- 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
-
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, seePNMCodec
). This default implementation always returnsnull
.- Overrides:
suggestFileExtension
in classImageCodec
- 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
-
-