com.keypoint

Class PngEncoder


public class PngEncoder
extends java.lang.Object

PngEncoder takes a Java Image object and creates a byte string which can be saved as a PNG file. The Image is presumed to use the DirectColorModel.

Thanks to Jay Denny at KeyPoint Software http://www.keypoint.com/ who let me develop this code on company time.

You may contact me with (probably very-much-needed) improvements, comments, and bug fixes at:

david@catcode.com

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. A copy of the GNU LGPL may be found at http://www.gnu.org/copyleft/lesser.html

Version:
1.5, 19 Oct 2003 CHANGES: -------- 19-Nov-2002 : CODING STYLE CHANGES ONLY (by David Gilbert for Object Refinery Limited); 19-Sep-2003 : Fix for platforms using EBCDIC (contributed by Paulo Soares); 19-Oct-2003 : Change private fields to protected fields so that PngEncoderB can inherit them (JDE) Fixed bug with calculation of nRows
Author:
J. David Eisenberg

Field Summary

static boolean
ENCODE_ALPHA
Constant specifying that alpha channel should be encoded.
static int
FILTER_LAST
Constants for filter (LAST).
static int
FILTER_NONE
Constants for filter (NONE).
static int
FILTER_SUB
Constants for filter (SUB).
static int
FILTER_UP
Constants for filter (UP).
protected static byte[]
IDAT
IDAT tag.
protected static byte[]
IEND
IEND tag.
protected static byte[]
IHDR
IHDR tag.
static boolean
NO_ALPHA
Constant specifying that alpha channel should not be encoded.
protected static byte[]
PHYS
protected int
bytePos
The byte position.
protected int
bytesPerPixel
The bytes-per-pixel.
protected int
compressionLevel
The compression level (1 = best speed, 9 = best compression, 0 = no compression).
protected CRC32
crc
CRC.
protected long
crcValue
The CRC value.
protected boolean
encodeAlpha
Encode alpha?
protected int
filter
The filter type.
protected int
height
The height.
protected Image
image
The image.
protected byte[]
leftBytes
The left bytes.
protected int
maxPos
The maximum position.
protected byte[]
pngBytes
The png bytes.
protected byte[]
priorRow
The prior row.
protected int
width
The width.

Constructor Summary

PngEncoder()
Class constructor.
PngEncoder(Image image)
Class constructor specifying Image to encode, with no alpha channel encoding.
PngEncoder(Image image, boolean encodeAlpha)
Class constructor specifying Image to encode, and whether to encode alpha.
PngEncoder(Image image, boolean encodeAlpha, int whichFilter)
Class constructor specifying Image to encode, whether to encode alpha, and filter to use.
PngEncoder(Image image, boolean encodeAlpha, int whichFilter, int compLevel)
Class constructor specifying Image source to encode, whether to encode alpha, filter to use, and compression level.

Method Summary

protected void
filterSub(byte[] pixels, int startPos, int width)
Perform "sub" filtering on the given row.
protected void
filterUp(byte[] pixels, int startPos, int width)
Perform "up" filtering on the given row.
int
getCompressionLevel()
Retrieve compression level.
boolean
getEncodeAlpha()
Retrieve alpha encoding status.
int
getFilter()
Retrieve filtering scheme.
Image
getImage()
Returns the image to be encoded.
int
getXDpi()
Get the DPI for the X axis.
int
getYDpi()
Get the DPI for the Y axis.
byte[]
pngEncode()
Creates an array of bytes that is the PNG equivalent of the current image.
byte[]
pngEncode(boolean encodeAlpha)
Creates an array of bytes that is the PNG equivalent of the current image, specifying whether to encode alpha or not.
protected byte[]
resizeByteArray(byte[] array, int newLength)
Increase or decrease the length of a byte array.
void
setCompressionLevel(int level)
Set the compression level to use.
void
setDpi(int xDpi, int yDpi)
Set the DPI resolution.
void
setEncodeAlpha(boolean encodeAlpha)
Set the alpha encoding on or off.
void
setFilter(int whichFilter)
Set the filter to use.
void
setImage(Image image)
Set the image to be encoded.
void
setXDpi(int xDpi)
Set the DPI for the X axis.
void
setYDpi(int yDpi)
Set the DPI for the Y axis.
protected int
writeByte(int b, int offset)
Write a single byte into the pngBytes array at a given position.
protected int
writeBytes(byte[] data, int offset)
Write an array of bytes into the pngBytes array.
protected int
writeBytes(byte[] data, int nBytes, int offset)
Write an array of bytes into the pngBytes array, specifying number of bytes to write.
protected void
writeEnd()
Write a PNG "IEND" chunk into the pngBytes array.
protected void
writeHeader()
Write a PNG "IHDR" chunk into the pngBytes array.
protected boolean
writeImageData()
Write the image data into the pngBytes array.
protected int
writeInt2(int n, int offset)
Write a two-byte integer into the pngBytes array at a given position.
protected int
writeInt4(int n, int offset)
Write a four-byte integer into the pngBytes array at a given position.
protected void
writeResolution()
Write a PNG "pHYs" chunk into the pngBytes array.

Field Details

ENCODE_ALPHA

public static final boolean ENCODE_ALPHA
Constant specifying that alpha channel should be encoded.
Field Value:
true

FILTER_LAST

public static final int FILTER_LAST
Constants for filter (LAST).
Field Value:
2

FILTER_NONE

public static final int FILTER_NONE
Constants for filter (NONE).
Field Value:
0

FILTER_SUB

public static final int FILTER_SUB
Constants for filter (SUB).
Field Value:
1

FILTER_UP

public static final int FILTER_UP
Constants for filter (UP).
Field Value:
2

IDAT

protected static final byte[] IDAT
IDAT tag.

IEND

protected static final byte[] IEND
IEND tag.

IHDR

protected static final byte[] IHDR
IHDR tag.

NO_ALPHA

public static final boolean NO_ALPHA
Constant specifying that alpha channel should not be encoded.
Field Value:
false

PHYS

protected static final byte[] PHYS

bytePos

protected int bytePos
The byte position.

bytesPerPixel

protected int bytesPerPixel
The bytes-per-pixel.

compressionLevel

protected int compressionLevel
The compression level (1 = best speed, 9 = best compression, 0 = no compression).

crc

protected CRC32 crc
CRC.

crcValue

protected long crcValue
The CRC value.

encodeAlpha

protected boolean encodeAlpha
Encode alpha?

filter

protected int filter
The filter type.

height

protected int height
The height.

image

protected Image image
The image.

leftBytes

protected byte[] leftBytes
The left bytes.

maxPos

protected int maxPos
The maximum position.

pngBytes

protected byte[] pngBytes
The png bytes.

priorRow

protected byte[] priorRow
The prior row.

width

protected int width
The width.

Constructor Details

PngEncoder

public PngEncoder()
Class constructor.

PngEncoder

public PngEncoder(Image image)
Class constructor specifying Image to encode, with no alpha channel encoding.
Parameters:
image - A Java Image object which uses the DirectColorModel
See Also:
java.awt.Image

PngEncoder

public PngEncoder(Image image,
                  boolean encodeAlpha)
Class constructor specifying Image to encode, and whether to encode alpha.
Parameters:
image - A Java Image object which uses the DirectColorModel
encodeAlpha - Encode the alpha channel? false=no; true=yes
See Also:
java.awt.Image

PngEncoder

public PngEncoder(Image image,
                  boolean encodeAlpha,
                  int whichFilter)
Class constructor specifying Image to encode, whether to encode alpha, and filter to use.
Parameters:
image - A Java Image object which uses the DirectColorModel
encodeAlpha - Encode the alpha channel? false=no; true=yes
whichFilter - 0=none, 1=sub, 2=up
See Also:
java.awt.Image

PngEncoder

public PngEncoder(Image image,
                  boolean encodeAlpha,
                  int whichFilter,
                  int compLevel)
Class constructor specifying Image source to encode, whether to encode alpha, filter to use, and compression level.
Parameters:
image - A Java Image object
encodeAlpha - Encode the alpha channel? false=no; true=yes
whichFilter - 0=none, 1=sub, 2=up
compLevel - 0..9 (1 = best speed, 9 = best compression, 0 = no compression)
See Also:
java.awt.Image

Method Details

filterSub

protected void filterSub(byte[] pixels,
                         int startPos,
                         int width)
Perform "sub" filtering on the given row. Uses temporary array leftBytes to store the original values of the previous pixels. The array is 16 bytes long, which will easily hold two-byte samples plus two-byte alpha.
Parameters:
pixels - The array holding the scan lines being built
startPos - Starting position within pixels of bytes to be filtered.
width - Width of a scanline in pixels.

filterUp

protected void filterUp(byte[] pixels,
                        int startPos,
                        int width)
Perform "up" filtering on the given row. Side effect: refills the prior row with current row
Parameters:
pixels - The array holding the scan lines being built
startPos - Starting position within pixels of bytes to be filtered.
width - Width of a scanline in pixels.

getCompressionLevel

public int getCompressionLevel()
Retrieve compression level.
Returns:
int (1 = best speed, 9 = best compression, 0 = no compression)

getEncodeAlpha

public boolean getEncodeAlpha()
Retrieve alpha encoding status.
Returns:
boolean false=no, true=yes

getFilter

public int getFilter()
Retrieve filtering scheme.
Returns:
int (see constant list)

getImage

public Image getImage()
Returns the image to be encoded.

getXDpi

public int getXDpi()
Get the DPI for the X axis.
Returns:
The number of dots per inch

getYDpi

public int getYDpi()
Get the DPI for the Y axis.
Returns:
The number of dots per inch

pngEncode

public byte[] pngEncode()
Creates an array of bytes that is the PNG equivalent of the current image. Alpha encoding is determined by its setting in the constructor.
Returns:
an array of bytes, or null if there was a problem

pngEncode

public byte[] pngEncode(boolean encodeAlpha)
Creates an array of bytes that is the PNG equivalent of the current image, specifying whether to encode alpha or not.
Parameters:
encodeAlpha - boolean false=no alpha, true=encode alpha
Returns:
an array of bytes, or null if there was a problem

resizeByteArray

protected byte[] resizeByteArray(byte[] array,
                                 int newLength)
Increase or decrease the length of a byte array.
Parameters:
array - The original array.
newLength - The length you wish the new array to have.
Returns:
Array of newly desired length. If shorter than the original, the trailing elements are truncated.

setCompressionLevel

public void setCompressionLevel(int level)
Set the compression level to use.
Parameters:
level - the compression level (1 = best speed, 9 = best compression, 0 = no compression)

setDpi

public void setDpi(int xDpi,
                   int yDpi)
Set the DPI resolution.
Parameters:
xDpi - The number of dots per inch for the X axis.
yDpi - The number of dots per inch for the Y axis.

setEncodeAlpha

public void setEncodeAlpha(boolean encodeAlpha)
Set the alpha encoding on or off.
Parameters:
encodeAlpha - false=no, true=yes

setFilter

public void setFilter(int whichFilter)
Set the filter to use.
Parameters:
whichFilter - from constant list

setImage

public void setImage(Image image)
Set the image to be encoded.
Parameters:
image - A Java Image object which uses the DirectColorModel
See Also:
java.awt.Image, java.awt.image.DirectColorModel

setXDpi

public void setXDpi(int xDpi)
Set the DPI for the X axis.
Parameters:
xDpi - The number of dots per inch

setYDpi

public void setYDpi(int yDpi)
Set the DPI for the Y axis.
Parameters:
yDpi - The number of dots per inch

writeByte

protected int writeByte(int b,
                        int offset)
Write a single byte into the pngBytes array at a given position.
Parameters:
b - The integer to be written into pngBytes.
offset - The starting point to write to.
Returns:
The next place to be written to in the pngBytes array.

writeBytes

protected int writeBytes(byte[] data,
                         int offset)
Write an array of bytes into the pngBytes array. Note: This routine has the side effect of updating maxPos, the largest element written in the array. The array is resized by 1000 bytes or the length of the data to be written, whichever is larger.
Parameters:
data - The data to be written into pngBytes.
offset - The starting point to write to.
Returns:
The next place to be written to in the pngBytes array.

writeBytes

protected int writeBytes(byte[] data,
                         int nBytes,
                         int offset)
Write an array of bytes into the pngBytes array, specifying number of bytes to write. Note: This routine has the side effect of updating maxPos, the largest element written in the array. The array is resized by 1000 bytes or the length of the data to be written, whichever is larger.
Parameters:
data - The data to be written into pngBytes.
nBytes - The number of bytes to be written.
offset - The starting point to write to.
Returns:
The next place to be written to in the pngBytes array.

writeEnd

protected void writeEnd()
Write a PNG "IEND" chunk into the pngBytes array.

writeHeader

protected void writeHeader()
Write a PNG "IHDR" chunk into the pngBytes array.

writeImageData

protected boolean writeImageData()
Write the image data into the pngBytes array. This will write one or more PNG "IDAT" chunks. In order to conserve memory, this method grabs as many rows as will fit into 32K bytes, or the whole image; whichever is less.
Returns:
true if no errors; false if error grabbing pixels

writeInt2

protected int writeInt2(int n,
                        int offset)
Write a two-byte integer into the pngBytes array at a given position.
Parameters:
n - The integer to be written into pngBytes.
offset - The starting point to write to.
Returns:
The next place to be written to in the pngBytes array.

writeInt4

protected int writeInt4(int n,
                        int offset)
Write a four-byte integer into the pngBytes array at a given position.
Parameters:
n - The integer to be written into pngBytes.
offset - The starting point to write to.
Returns:
The next place to be written to in the pngBytes array.

writeResolution

protected void writeResolution()
Write a PNG "pHYs" chunk into the pngBytes array.