JIU 0.14.3

net.sourceforge.jiu.codecs
Class PNGCodec

java.lang.Object
  extended by net.sourceforge.jiu.ops.Operation
      extended by net.sourceforge.jiu.codecs.ImageCodec
          extended by net.sourceforge.jiu.codecs.PNGCodec

public class PNGCodec
extends ImageCodec

A codec for the Portable Network Graphics (PNG) format. Supports both loading and saving of images.

Usage examples

Load an image

The following example code loads an image from a PNG file. Note that you could also use ImageLoader or ToolkitLoader which require only a single line of code and can load all formats supported by JIU, including PNG.
  PNGCodec codec = new PNGCodec();
  codec.setFile("image.png", CodecMode.LOAD);
  codec.process();
  PixelImage image = codec.getImage();

Save an image

  PNGCodec codec = new PNGCodec();
  codec.setFile("out.png", CodecMode.SAVE);
  codec.setImage(image);
  codec.setCompressionLevel(Deflater.BEST_COMPRESSION);
  codec.appendComment("Copyright (c) 1992 John Doe");
  // sets last modification time to current time
  codec.setModification(new GregorianCalendar(
   new SimpleTimeZone(0, "UTC")));
  codec.process();

Supported storage order types

Loading

This codec reads both non-interlaced and Adam7 interlaced PNG files.

Saving

This codec only writes non-interlaced PNG files.

Supported color types

Loading

Saving

Transparency information

PNG allows to store different types of transparency information. Full alpha channels, transparent index values, and more. Right now, this JIU codec does not make use of this information and simply skips over it when encountered.

Bounds

This codec regards the bounds concept. If bounds are specified with ImageCodec.setBounds(int, int, int, int), the codec will only load or save part of an image.

Metadata

Loading

Saving

Implementation details

This class relies heavily on the Java runtime library for decompression and checksum creation.

Background

To learn more about the PNG file format, visit its official homepage. There you can find a detailed specification, test images and existing PNG libraries and PNG-aware applications. The book PNG - The Definitive Guide by Greg Roelofs, published by O'Reilly, 1999, ISBN 1-56592-542-4 is a valuable source of information on PNG. It is out of print, but it can be viewed online and downloaded for offline reading in its entirety from the site.

Since:
0.12.0
Author:
Marco Schmidt

Constructor Summary
PNGCodec()
           
 
Method Summary
 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.
 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.
static void main(String[] args)
           
 void process()
          This method does the actual work of the operation.
 void setCompressionLevel(int newLevel)
          Sets the compression level to be used with the underlying Deflater object which does the compression.
 void setCompressionStrategy(int newStrategy)
          Sets the compression strategy to be used with the underlying Deflater object which does the compression.
 void setEncodingIdatSize(int newSize)
          Sets the size of IDAT chunks generated when encoding.
 void setFile(String fileName, CodecMode codecMode)
          Gives a file name and codec mode to the codec which will then try to create the corresponding I/O object.
 void setModification(Calendar time)
          Sets date and time of last modification of the image to be stored in a PNG stream when saving.
 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, 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
 

Constructor Detail

PNGCodec

public PNGCodec()
Method Detail

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

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

main

public static void main(String[] args)
                 throws Exception
Throws:
Exception

process

public void process()
             throws InvalidFileStructureException,
                    MissingParameterException,
                    OperationFailedException,
                    UnsupportedTypeException,
                    WrongFileFormatException
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
InvalidFileStructureException
UnsupportedTypeException
WrongFileFormatException

setCompressionLevel

public void setCompressionLevel(int newLevel)
Sets the compression level to be used with the underlying Deflater object which does the compression. If no value is specified, Deflater.DEFAULT_COMPRESSION is used.

Parameters:
newLevel - compression level, from 0 to 9, 0 being fastest and compressing worst and 9 offering highest compression and taking the most time

setCompressionStrategy

public void setCompressionStrategy(int newStrategy)
Sets the compression strategy to be used with the underlying Deflater object which does the compression. If no value is specified, Deflater.DEFAULT_STRATEGY is used.

Parameters:
newStrategy - one of Deflater's strategy values: Deflater.DEFAULT_STRATEGY, Deflater.FILTERED, Deflater.HUFFMAN_ONLY

setEncodingIdatSize

public void setEncodingIdatSize(int newSize)
Sets the size of IDAT chunks generated when encoding. If this method is never called, a default value of 32768 bytes (32 KB) is used. Note that a byte array of the size of the value you specify here is allocated, so make sure that you keep the value small enough to stay within a system's memory.

Compressed image data is spread over several IDAT chunks by this codec. The length of the compressed data of a complete image is known only after the complete image has been encoded. With PNG, that length value has to be stored before the compressed data as a chunk size value. This codec is supposed to work with OutputStream objects, so seeking back to adjust the chunk size value of an IDAT chunk is not possible. That's why all data of a chunk is compressed into a memory buffer. Whenever the buffer gets full, it is written to output as an IDAT chunk.

Note that the last IDAT chunk may be smaller than the size defined here.

Parameters:
newSize - size of encoding compressed data buffer

setFile

public void setFile(String fileName,
                    CodecMode codecMode)
             throws IOException,
                    UnsupportedCodecModeException
Description copied from class: ImageCodec
Gives a file name and codec mode to the codec which will then try to create the corresponding I/O object. The default implementation in ImageCodec creates a DataInputStream object wrapped around a BufferedInputStream wrapped around a FileInputStream for CodecMode.LOAD. Similar for CodecMode.SAVE: a DataOutputStream around a BufferedOutputStream object around a FileOutputStream object. Codecs that need different I/O objects must override this method (some codecs may need random access and thus require a RandomAccessFile object).

Overrides:
setFile in class ImageCodec
Parameters:
fileName - name of the file to be used for loading or saving
codecMode - defines whether file is to be used for loading or saving
Throws:
IOException
UnsupportedCodecModeException

setModification

public void setModification(Calendar time)
Sets date and time of last modification of the image to be stored in a PNG stream when saving. Make sure the argument object has UTC as time zone (as demanded by the PNG specs). If you want the current time and date, use new GregorianCalendar(new SimpleTimeZone(0, "UTC")) as parameter for this method.

Parameters:
time - time of last modification of the image

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

JIU 0.14.3

Copyright © 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Marco Schmidt