edu.rit.image

Class BaseColorImage

java.lang.Object

edu.rit.image.PJGImage

edu.rit.image.BaseColorImage

Direct Known Subclasses:

PJGColorImage, PJGHueImage

public abstract class BaseColorImage
extends PJGImage

Class BaseColorImage is the abstract superclass for a color image file in Parallel Java Graphics (PJG) format. 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 BaseColorImage 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.

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

Nested Class Summary

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

PJGImage.Reader, PJGImage.Writer

Method Summary

Modifier and Type	Method and Description
void	fill(java.awt.Color color) Set all pixels in this image to the given color.
void	fill(float red, float green, float blue) Set all pixels in this image to the given color.
void	fill(HSB color) Set all pixels in this image to the given color.
void	fill(int red, int green, int blue) Set all pixels in this image to the given color.
void	fill(IntRGB color) Set all pixels in this image to the given color.
void	fill(RGB color) Set all pixels in this image to the given color.
void	fillHSB(float hue, float sat, float bri) Set all pixels in this image to the given color.
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.
int[][]	getMatrix() Obtain this image's underlying matrix.
void	getPixel(int r, int c, HSB color) Obtain the pixel at the given row and column in this image.
void	getPixel(int r, int c, IntRGB color) Obtain the pixel at the given row and column in this image.
void	getPixel(int r, int c, RGB color) Obtain the pixel at the given row and column in this image.
java.awt.Color	getPixelColor(int r, int c) Obtain the pixel at the given row and column in this image.
void	setMatrix(int theHeight, int theWidth, int[][] theMatrix) Set this image's height, width, and underlying matrix.
void	setPixel(int r, int c, float red, float green, float blue) Set the pixel at the given row and column in this image.
void	setPixel(int r, int c, HSB color) Set the pixel at the given row and column in this image.
void	setPixel(int r, int c, int red, int green, int blue) Set the pixel at the given row and column in this image.
void	setPixel(int r, int c, IntRGB color) Set the pixel at the given row and column in this image.
void	setPixel(int r, int c, RGB color) Set the pixel at the given row and column in this image.
void	setPixelColor(int r, int c, java.awt.Color color) Set the pixel at the given row and column in this image.
void	setPixelHSB(int r, int c, float hue, float sat, float bri) 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, prepareToRead, prepareToWrite, readFromStream, setCreationTime

Methods inherited from class java.lang.Object

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

Method Detail

getMatrix

public int[][] getMatrix()

Obtain this image's underlying matrix.

Returns:

Underlying matrix, or null if none.

setMatrix

public void setMatrix(int theHeight,
                      int theWidth,
                      int[][] 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.

getPixel

public void getPixel(int r,
                     int c,
                     RGB color)

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

Parameters:

r - Row index.

c - Column index.

color - Floating point RGB color object in which to store the pixel's color components.

Throws:

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

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

getPixel

public void getPixel(int r,
                     int c,
                     IntRGB color)

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

Parameters:

r - Row index.

c - Column index.

color - Integer RGB color object in which to store the pixel's color components.

Throws:

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

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

getPixel

public void getPixel(int r,
                     int c,
                     HSB color)

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

Parameters:

r - Row index.

c - Column index.

color - Floating point HSB color object in which to store the pixel's color components.

Throws:

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

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

getPixelColor

public java.awt.Color getPixelColor(int r,
                                    int c)

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

Parameters:

r - Row index.

c - Column index.

Returns:

AWT color of pixel.

Throws:

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

setPixel

public void setPixel(int r,
                     int c,
                     RGB color)

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

Parameters:

r - Row index.

c - Column index.

color - Floating point RGB color object containing the pixel's color components.

Throws:

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

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

setPixel

public void setPixel(int r,
                     int c,
                     IntRGB color)

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

Parameters:

r - Row index.

c - Column index.

color - Integer RGB color object containing the pixel's color components.

Throws:

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

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

setPixel

public void setPixel(int r,
                     int c,
                     HSB color)

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

Parameters:

r - Row index.

c - Column index.

color - Floating point HSB color object containing the pixel's color components.

Throws:

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

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

setPixelColor

public void setPixelColor(int r,
                          int c,
                          java.awt.Color color)

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

Parameters:

r - Row index.

c - Column index.

color - The pixel's AWT color.

Throws:

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

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

setPixel

public void setPixel(int r,
                     int c,
                     float red,
                     float green,
                     float blue)

Set the pixel at the given row and column in this image. If any value red, green, or blue is outside the range 0.0 .. 1.0, it is pinned to the appropriate boundary.

Parameters:

r - Row index.

c - Column index.

red - Pixel's red component.

green - Pixel's green component.

blue - Pixel's blue component.

Throws:

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

setPixel

public void setPixel(int r,
                     int c,
                     int red,
                     int green,
                     int blue)

Set the pixel at the given row and column in this image. If any value red, green, or blue is outside the range 0 .. 255, it is pinned to the appropriate boundary.

Parameters:

r - Row index in the range matrix().rowRange().

c - Column index in the range matrix().colRange().

red - Pixel's red component.

green - Pixel's green component.

blue - Pixel's blue component.

Throws:

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

setPixelHSB

public void setPixelHSB(int r,
                        int c,
                        float hue,
                        float sat,
                        float bri)

Set the pixel at the given row and column in this image. If any value hue, sat, or bri is outside the range 0.0 .. 1.0, it is pinned to the appropriate boundary.

Parameters:

r - Row index in the range matrix().rowRange().

c - Column index in the range matrix().colRange().

hue - Pixel's hue component.

sat - Pixel's saturation component.

bri - Pixel's brightness component.

Throws:

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

fill

public void fill(RGB color)

Set all pixels in this image to the given color. If any component of color is outside the range 0.0 .. 1.0, it is pinned to the appropriate boundary.

Parameters:

color - Floating point RGB color object containing the pixel's color components.

Throws:

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

fill

public void fill(IntRGB color)

Set all pixels in this image to the given color. If any component of color is outside the range 0 .. 255, it is pinned to the appropriate boundary.

Parameters:

color - Integer RGB color object containing the pixel's color components.

Throws:

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

fill

public void fill(HSB color)

Set all pixels in this image to the given color. If any component of color is outside the range 0.0 .. 1.0, it is pinned to the appropriate boundary.

Parameters:

color - Floating point HSB object containing the pixel's color components.

Throws:

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

fill

public void fill(java.awt.Color color)

Set all pixels in this image to the given color.

Parameters:

color - The pixel's AWT color.

Throws:

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

fill

public void fill(float red,
                 float green,
                 float blue)

Set all pixels in this image to the given color. If any value red, green, or blue is outside the range 0.0 .. 1.0, it is pinned to the appropriate boundary.

Parameters:

red - Pixel's red component.

green - Pixel's green component.

blue - Pixel's blue component.

fill

public void fill(int red,
                 int green,
                 int blue)

Set all pixels in this image to the given color. If any value red, green, or blue is outside the range 0 .. 255, it is pinned to the appropriate boundary.

Parameters:

red - Pixel's red component.

green - Pixel's green component.

blue - Pixel's blue component.

fillHSB

public void fillHSB(float hue,
                    float sat,
                    float bri)

Set all pixels in this image to the given color. If any value hue, sat, or bri is outside the range 0.0 .. 1.0, it is pinned to the appropriate boundary.

Parameters:

hue - Pixel's hue component.

sat - Pixel's saturation component.

bri - Pixel's brightness component.

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.