edu.rit.image

Class PJGColorImage

java.lang.Object

edu.rit.image.PJGImage

edu.rit.image.BaseColorImage

edu.rit.image.PJGColorImage

public class PJGColorImage
extends BaseColorImage

Class PJGColorImage provides a color image that is read from or written to a file in Parallel Java Graphics (PJG) format; class PJGColorImage is best suited when the image has a small number of discrete colors. For further information about the PJG format, see class PJGImage. The image is layered on top of an integer matrix (type int[][]). The height and width of the image are equal to the number of rows and columns in the underlying matrix.

To get and set the image's pixel data, use the getPixel(), getPixelColor(), setPixel(), setPixelColor(), and setPixelHSB() methods. You only need to allocate storage in the pixel data matrix for the portions of the image you are actually accessing; the complete matrix need not be allocated. Class Arrays has static methods for allocating portions of a matrix.

Changing the contents of the underlying matrix directly will also change the image. The color information is stored in a matrix element as follows:

• Bits 31 .. 24 -- Unused, must be 0
• Bits 23 .. 16 -- Red component in the range 0 .. 255
• Bits 15 .. 8 -- Green component in the range 0 .. 255
• Bits 7 .. 0 -- Blue component in the range 0 .. 255

A color may be specified using hue, saturation, and brightness components instead of red, green, and blue components.

The hue component gives the basic color. A hue of 0 = red; 1/6 = yellow; 2/6 = green; 3/6 = cyan; 4/6 = blue; 5/6 = magenta; 1 = red again. Intermediate hue values yield intermediate colors.

The saturation component specifies how gray or colored the color is. A saturation of 0 yields fully gray; a saturation of 1 yields fully colored. Intermediate saturation values yield mixtures of gray and colored.

The brightness component specifies how dark or light the color is. A brightness of 0 yields fully dark (black); a brightness of 1 yields fully light (somewhere between white and colored depending on the saturation). Intermediate brightness values yield somewhere between a gray shade and a darkened color (depending on the saturation).

To write a PJGColorImage object to a PJG image file, call the prepareToWrite() method, specifying the output stream to write. The prepareToWrite() method returns an instance of class PJGImage.Writer. Call the methods of the PJG image writer object to write the pixel data, or sections of the pixel data, to the output stream. When finished, close the PJG image writer.

When writing an image to a PJG file, class PJGColorImage uses run length encoded 24-bit color pixel data segments (see class PJGImage) to compress the pixel data. This technique will work well if the image has many runs of consecutive identical pixels and the image has no more than 16,383 unique colors; it will work even better if the image has no more than 127 unique colors.

To read a PJGColorImage object from a PJG image file, call the prepareToRead() method, specifying the input stream to read. The prepareToRead() method returns an instance of class PJGImage.Reader. Call the methods of the PJG image reader object to read the pixel data, or sections of the pixel data, from the input stream. When finished, close the PJG image reader.

To get a BufferedImage object that uses the same underlying pixel data matrix as the PJGColorImage object, call the getBufferedImage() method. You can then do all the following with the BufferedImage: display it on the screen, draw into it using a graphics context, copy another BufferedImage into it, read it from or write it to a file using package javax.imageio (which typically supports PNG, JPG, and GIF formats). The rows and columns of the underlying matrix need not all be allocated when accessing the BufferedImage. If you get a pixel from the BufferedImage in an unallocated row or column, a pixel value of 0 (black) is returned. If you set a pixel in the BufferedImage in an unallocated row or column, the pixel value is discarded.

Note: Class PJGColorImage is not multiple thread safe.

Nested Class Summary

Nested classes/interfaces inherited from class edu.rit.image.PJGImage

PJGImage.Reader, PJGImage.Writer

Constructor Summary

Constructors

Constructor and Description
PJGColorImage() Construct a new PJG color image.
PJGColorImage(int theHeight, int theWidth, int[][] theMatrix) Construct a new PJG color image with the given height, width, and underlying matrix.

Method Summary

Modifier and Type	Method and Description
PJGImage.Reader	prepareToRead(java.io.InputStream theStream) Prepare to read this image from the given input stream.
PJGImage.Writer	prepareToWrite(java.io.OutputStream theStream) Prepare to write this image to the given output stream.

Methods inherited from class edu.rit.image.BaseColorImage

fill, fill, fill, fill, fill, fill, fillHSB, getBufferedImage, getDisplayable, getMatrix, getPixel, getPixel, getPixel, getPixelColor, setMatrix, setPixel, setPixel, setPixel, setPixel, setPixel, setPixelColor, setPixelHSB

Methods inherited from class edu.rit.image.PJGImage

addComment, clearComments, createFromStream, getComments, getCreationTime, getHeight, getWidth, readFromStream, setCreationTime

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PJGColorImage

public PJGColorImage()

Construct a new PJG color image. The image's height and width are uninitialized. Before accessing the image's pixels, specify the height and width by calling the setMatrix() method or by reading the image from an input stream.

PJGColorImage

public PJGColorImage(int theHeight,
                     int theWidth,
                     int[][] theMatrix)

Construct a new PJG color image with the given height, width, and underlying matrix.

Parameters:

theHeight - Image height in pixels.

theWidth - Image width in pixels.

theMatrix - Underlying matrix.

Throws:

java.lang.NullPointerException - (unchecked exception) Thrown if theMatrix is null.

java.lang.IllegalArgumentException - (unchecked exception) Thrown if theHeight <= 0. Thrown if theWidth <= 0. Thrown if theMatrix.length does not equal theHeight.

Method Detail

prepareToWrite

public PJGImage.Writer prepareToWrite(java.io.OutputStream theStream)
                               throws java.io.IOException

Prepare to write this image to the given output stream. Certain header information is written to the output stream at this time. To write this image's pixel data, call methods on the returned PJG image writer, then close the PJG image writer.

For improved performance, specify an output stream with buffering, such as an instance of class java.io.BufferedOutputStream.

Specified by:

prepareToWrite in class PJGImage

Parameters:

theStream - Output stream.

Returns:

PJG image writer object with which to write this image.

Throws:

java.lang.NullPointerException - (unchecked exception) Thrown if theStream is null.

java.io.IOException - Thrown if an I/O error occurred.

prepareToRead

public PJGImage.Reader prepareToRead(java.io.InputStream theStream)
                              throws java.io.IOException

Prepare to read this image from the given input stream. Certain header information is read from the input stream at this time. To read this image's pixel data, call methods on the returned PJG image reader, then close the PJG image reader.

For improved performance, specify an input stream with buffering, such as an instance of class java.io.BufferedInputStream.

Specified by:

prepareToRead in class PJGImage

Parameters:

theStream - Input stream.

Returns:

PJG image reader object with which to read this image.

Throws:

java.lang.NullPointerException - (unchecked exception) Thrown if theStream is null.

java.io.IOException - Thrown if an I/O error occurred.