edu.rit.image
Class PJGHueImage

java.lang.Object
  edu.rit.image.PJGImage
      edu.rit.image.BaseColorImage
          edu.rit.image.PJGHueImage

public class PJGHueImage
extends BaseColorImage

Class PJGHueImage provides a color image that is read from or written to a file in Parallel Java Graphics (PJG) format; class PJGHueImage is best suited when the image has a continuous range of hues. 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 PJGHueImage 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 PJGHueImage uses Huffman delta encoded 24-bit hue pixel data segments (see class PJGImage) to compress the pixel data. This technique will work well if the image has a continous range of hues, where each pixel's RGB components are the same or nearly the same as the neighboring pixels' RGB components.

To read a PJGHueImage 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 PJGHueImage 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 PJGHueImage is not multiple thread safe.

Nested Class Summary

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

PJGImage.Reader, PJGImage.Writer

Constructor Summary

PJGHueImage()
Construct a new PJG hue image.

PJGHueImage(int theHeight, int theWidth, int[][] theMatrix)
Construct a new PJG hue image with the given height, width, and underlying matrix.

Method Summary

PJGImage.Reader	prepareToRead(InputStream theStream) Prepare to read this image from the given input stream.
PJGImage.Writer	prepareToWrite(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

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

Constructor Detail

PJGHueImage

public PJGHueImage()

Construct a new PJG hue 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.

PJGHueImage

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

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

Parameters:

theHeight - Image height in pixels.

theWidth - Image width in pixels.

theMatrix - Underlying matrix.

Throws:

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

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(OutputStream theStream)
                               throws 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:

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

IOException - Thrown if an I/O error occurred.

prepareToRead

public PJGImage.Reader prepareToRead(InputStream theStream)
                              throws 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:

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

IOException - Thrown if an I/O error occurred.