edu.rit.image

Class PJGGrayImage

java.lang.Object

edu.rit.image.PJGImage

edu.rit.image.PJGGrayImage

public class PJGGrayImage
extends PJGImage

Class PJGGrayImage provides an 8-bit grayscale image that is read from or written to a file in Parallel Java Graphics (PJG) format. For further information about the PJG format, see class PJGImage. The image is layered on top of a byte matrix (type byte[][]). The height and width of the image are equal to the number of rows and columns in the underlying matrix.

To read and write the pixels of an image, use the getIntPixel(), getPixel(), setIntPixel(), and setPixel() methods. These methods represent a pixel value as an integer in the range 0 .. 255 or as a floating point number in the range 0.0 .. 1.0. The image's interpretation attribute specifies how to map between the numerical pixel value and the shade of gray. If the interpretation is ZERO_IS_WHITE, then a value of 0 or 0.0 represents white and 255 or 1.0 represents black. If the interpretation is ZERO_IS_BLACK, then a value of 0 or 0.0 represents black and 255 or 1.0 represents white. The default interpretation is ZERO_IS_BLACK. To change the interpretation, call the setInterpretation() method.

Changing the contents of the underlying matrix directly will also change the image. In the underlying matrix, a value of 0 represents black and a value of 255 represents white.

To write a PJGGrayImage 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 PJGGrayImage uses Huffman delta encoded 8-bit grayscale 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 or nearly identical pixel values.

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PJGGrayImage.Interpretation Enum Interpretation specifies how to interpret a numerical pixel value as a shade of gray in a grayscale image.

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

PJGImage.Reader, PJGImage.Writer

Field Summary

Fields

Modifier and Type	Field and Description
static PJGGrayImage.Interpretation	ZERO_IS_BLACK A pixel value of 0 or 0.0 is black, 255 or 1.0 is white.
static PJGGrayImage.Interpretation	ZERO_IS_WHITE A pixel value of 0 or 0.0 is white, 255 or 1.0 is black.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
void	fill(float val) Set all pixels in this image to the given value.
void	fill(int val) Set all pixels in this image to the given value.
java.awt.image.BufferedImage	getBufferedImage() Obtain a BufferedImage whose pixel data comes from this image's underlying matrix.
Displayable	getDisplayable() Obtain a Displayable object with which to display this image in a Swing UI.
PJGGrayImage.Interpretation	getInterpretation() Get this image's interpretation.
int	getIntPixel(int r, int c) Obtain the pixel at the given row and column in this image.
byte[][]	getMatrix() Obtain this image's underlying matrix.
float	getPixel(int r, int c) Obtain the pixel at the given row and column in this image.
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.
void	setInterpretation(PJGGrayImage.Interpretation theInterpretation) Set this image's interpretation.
void	setIntPixel(int r, int c, int val) Set the pixel at the given row and column in this image.
void	setMatrix(int theHeight, int theWidth, byte[][] theMatrix) Set this image's height, width, and underlying matrix.
void	setPixel(int r, int c, float val) Set the pixel at the given row and column in this image.

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

Field Detail

ZERO_IS_WHITE

public static final PJGGrayImage.Interpretation ZERO_IS_WHITE

A pixel value of 0 or 0.0 is white, 255 or 1.0 is black.

ZERO_IS_BLACK

public static final PJGGrayImage.Interpretation ZERO_IS_BLACK

A pixel value of 0 or 0.0 is black, 255 or 1.0 is white.

Constructor Detail

PJGGrayImage

public PJGGrayImage()

Construct a new PJG grayscale 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. The image's interpretation is ZERO_IS_BLACK.

PJGGrayImage

public PJGGrayImage(int theHeight,
                    int theWidth,
                    byte[][] theMatrix)

Construct a new PJG grayscale image with the given height, width, and underlying matrix. The image's interpretation is ZERO_IS_BLACK.

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

getMatrix

public byte[][] getMatrix()

Obtain this image's underlying matrix.

Returns:

Underlying matrix, or null if none.

setMatrix

public void setMatrix(int theHeight,
                      int theWidth,
                      byte[][] theMatrix)

Set this image's 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.

getInterpretation

public PJGGrayImage.Interpretation getInterpretation()

Get this image's interpretation.

Returns:

ZERO_IS_WHITE or ZERO_IS_BLACK.

setInterpretation

public void setInterpretation(PJGGrayImage.Interpretation theInterpretation)

Set this image's interpretation. If this method is not called, this image's default interpretation is ZERO_IS_BLACK.

Parameters:

theInterpretation - ZERO_IS_WHITE or ZERO_IS_BLACK.

getIntPixel

public int getIntPixel(int r,
                       int c)

Obtain the pixel at the given row and column in this image.

Parameters:

r - Row index.

c - Column index.

Returns:

Pixel[r,c] as an integer in the range 0 .. 255.

Throws:

java.lang.ArrayIndexOutOfBoundsException - (unchecked exception) Thrown if r or c is out of bounds.

getPixel

public float getPixel(int r,
                      int c)

Obtain the pixel at the given row and column in this image.

Parameters:

r - Row index.

c - Column index.

Returns:

Pixel[r,c] as a floating point number in the range 0.0 .. 1.0.

Throws:

java.lang.ArrayIndexOutOfBoundsException - (unchecked exception) Thrown if r or c is out of bounds.

setIntPixel

public void setIntPixel(int r,
                        int c,
                        int val)

Set the pixel at the given row and column in this image. If val is outside the range 0 .. 255, it is pinned to the appropriate boundary.

Parameters:

r - Row index.

c - Column index.

val - New pixel value as an integer in the range 0 .. 255.

Throws:

java.lang.ArrayIndexOutOfBoundsException - (unchecked exception) Thrown if r or c is out of bounds.

setPixel

public void setPixel(int r,
                     int c,
                     float val)

Set the pixel at the given row and column in this image. If val is outside the range 0.0 .. 1.0, it is pinned to the appropriate boundary.

Parameters:

r - Row index.

c - Column index.

val - New pixel value as a floating point number in the range 0.0 .. 1.0.

Throws:

java.lang.ArrayIndexOutOfBoundsException - (unchecked exception) Thrown if r or c is out of bounds.

fill

public void fill(int val)

Set all pixels in this image to the given value. If val is outside the range 0 .. 255, it is pinned to the appropriate boundary.

Parameters:

val - New pixel value as an integer in the range 0 .. 255.

Throws:

java.lang.NullPointerException - (unchecked exception) Thrown if the underlying matrix has no storage allocated.

fill

public void fill(float val)

Set all pixels in this image to the given value. If val is outside the range 0.0 .. 1.0, it is pinned to the appropriate boundary.

Parameters:

val - New pixel value as a floating point number in the range 0.0 .. 1.0.

Throws:

java.lang.NullPointerException - (unchecked exception) Thrown if the underlying matrix has no storage allocated.

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.

getBufferedImage

public java.awt.image.BufferedImage getBufferedImage()

Obtain a BufferedImage whose pixel data comes from this image's underlying matrix.

Specified by:

getBufferedImage in class PJGImage

Returns:

BufferedImage.

getDisplayable

public Displayable getDisplayable()

Obtain a Displayable object with which to display this image in a Swing UI.

Specified by:

getDisplayable in class PJGImage

Returns:

Displayable object.