Class EzImage

java.lang.Object

EzImage

public class EzImage
extends java.lang.Object

The EzImage class makes accessing and manipulating images straightforward. Images can be loaded from files in GIF, JPEG, or PNG format and manipulated through a variety of array operations. Both gray-scale and color images are supported.
The ideas and much of the code are largely from the class EasyBufferedImage by Kenny Hunt at UW-Lacrosse.

Field Summary

Fields

Modifier and Type	Field and Description
static int	ALPHA
static int	BLUE
static int	GRAY
static int	GREEN
static int	RED

Constructor Summary

Constructors

Constructor and Description
EzImage(java.awt.image.BufferedImage image) Constructs an EzImage object by wrapping around a BufferedImage object.
EzImage(java.io.File file) Constructs an EzImage object from the File object indicated.
EzImage(int[][] pixels) Constructs an EzImage object represented by the specified pixels.
EzImage(int[][][] pixels) Constructs an EzImage object represented by the specified pixels.
EzImage(int[] pixels, int height, int width) Constructs an EzImage object represented by the specified pixels.
EzImage(java.lang.String filename) Constructs an EzImage object by reading the image file specified by the filename.
EzImage(java.net.URL url) Constructs an EzImage object by reading the image specified by the url.

Method Summary

Modifier and Type	Method and Description
EzImage	appendToRight(EzImage image) Creates a new image that has this image on the left and the input image on the right (with no space in between.
EzImage	copy() Returns a copy of the calling EzImage.
EzImage	copyToGrayScale() Returns an EzImage object that is a gray-scale copy.
int	getBluePixel(int h, int w) Returns a single pixel value in the BLUE band.
java.awt.image.BufferedImage	getBufferedImage() Returns the image in BufferedImage format.
int	getGrayPixel(int h, int w) Returns a single pixel value in the GRAY band.
int	getGreenPixel(int h, int w) Returns a single pixel value in the GREEN band.
int	getHeight() Returns the height of the image.
int	getPixel(int h, int w, int band) Returns a single pixel value.
int[]	getPixels1D() Returns a 1D array of pixel values corresponding to gray values.
int[]	getPixels1D(int band) Returns a 1D array of pixel values corresponding to the specified band.
int[][]	getPixels2D() Returns a 2D array of pixel values corresponding to gray values.
int[][]	getPixels2D(int band) Returns a 2D array of pixel values corresponding to the specified band.
int[][][]	getPixels3D() Returns a 3D array of pixel values.
int	getRedPixel(int h, int w) Returns a single pixel value in the RED band.
java.lang.String[]	getSupportedWritingFormats() Returns a String array listing the file formats supported by this class for writing.
int	getWidth() Returns the width of the image.
boolean	isColor() Returns true if the image is a color image and false otherwise.
static void	main(java.lang.String[] args) The main method for this class.
int	numColorBands() Returns the number of color bands present in the image.
void	save(java.lang.String filename, java.lang.String format) Creates an image file having the specified name and of the specified format.
void	setBluePixel(int h, int w, int value) Sets a single blue EzImage pixel value in the specified band to the specified value.
void	setGrayPixel(int h, int w, int value) Sets a single gray EzImage pixel value in the specified band to the specified value.
void	setGreenPixel(int h, int w, int value) Sets a single green EzImage pixel value in the specified band to the specified value.
void	setPixel(int h, int w, int band, int value) Sets a single EzImage pixel value in the specified band to the specified value.
void	setPixels(int[] pixels) Sets all of the EzImage pixels.
void	setPixels(int[][] pixels) Sets all of the EzImage pixels.
void	setPixels(int[][][] pixels) Sets all of the EzImage pixels.
void	setPixels(int[][] pixels, int band) Sets all of the EzImage pixels in the specified band.
void	setPixels(int[] pixels, int band) Sets all of the EzImage pixels in the specified band.
void	setRedPixel(int h, int w, int value) Sets a single red EzImage pixel value in the specified band to the specified value.
void	show(java.lang.String title) Creates a window that will display this EzImage.
void	show(java.lang.String title, int row, int column) Creates a window that will display this EzImage.

Methods inherited from class java.lang.Object

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

Field Detail

RED

public static final int RED

See Also:

Constant Field Values

GREEN

public static final int GREEN

See Also:

Constant Field Values

BLUE

public static final int BLUE

See Also:

Constant Field Values

GRAY

public static final int GRAY

See Also:

Constant Field Values

ALPHA

public static final int ALPHA

See Also:

Constant Field Values

Constructor Detail

EzImage

public EzImage(int[][] pixels)

Constructs an EzImage object represented by the specified pixels. The dimensions of the pixel array must be [height][width] and is assumed to be gray-scale.

Parameters:

pixels - an array of [height][width] pixels that represents the image

Throws:

java.lang.IllegalArgumentException - if pixels is null

EzImage

public EzImage(int[][][] pixels)

Constructs an EzImage object represented by the specified pixels. The dimensions of the pixel array must be [height][width][3] (red-green-blue).

Parameters:

pixels - an array of [height][width][bands] pixels that represents the image.

Throws:

java.lang.IllegalArgumentException - if pixels is null

EzImage

public EzImage(int[] pixels,
               int height,
               int width)

Constructs an EzImage object represented by the specified pixels. The dimensions of the pixel array must be [height * width] and layed out in row-major format. The image is assumed to be gray-scale.

Parameters:

pixels - an array of [height * width] pixels that represents the image.

width - the width (in pixels) of the image.

height - the height (in pixels) of the image.

Throws:

java.lang.IllegalArgumentException - if pixels is null or the length is not width * height.

EzImage

public EzImage(java.awt.image.BufferedImage image)

Constructs an EzImage object by wrapping around a BufferedImage object.

Parameters:

image - a BufferedImage object

EzImage

public EzImage(java.lang.String filename)
        throws java.io.FileNotFoundException,
               java.io.IOException

Constructs an EzImage object by reading the image file specified by the filename. The format of the file may be any one of the formats that Java has readers for, such as GIF, PNG, or JPEG.

Parameters:

filename - the name of the file to load

Throws:

java.io.FileNotFoundException

java.io.IOException

EzImage

public EzImage(java.io.File file)
        throws java.io.IOException,
               java.io.FileNotFoundException

Constructs an EzImage object from the File object indicated. The format of the file may be any one of the formats that Java has readers for, such as GIF, PNG, or JPEG.

Parameters:

file - the File object to load

Throws:

IOException,FileNotFoundException

java.io.IOException

java.io.FileNotFoundException

EzImage

public EzImage(java.net.URL url)
        throws java.io.IOException

Constructs an EzImage object by reading the image specified by the url. The format of the file may be any one of the formats that Java has readers for, such as GIF, PNG, or JPEG.

Parameters:

url - the URL of an image file to load.

Throws:

java.io.IOException

Method Detail

copyToGrayScale

public EzImage copyToGrayScale()

Returns an EzImage object that is a gray-scale copy.

Returns:

an EzImage that is a gray-scale copy

getPixels3D

public int[][][] getPixels3D()

Returns a 3D array of pixel values. The dimensions of the array correspond to the [height][width][bands] of the EzImage. The number of bands will be 1 for a gray-scale or binary image, 3 for a color image without transparency, and 4 for a color image with transparency. The bands are (in order) RED (or GRAY), GREEN, BLUE, ALPHA. Pixel values are in the range 0-255.

Returns:

an array of pixels

getPixels2D

public int[][] getPixels2D(int band)

Returns a 2D array of pixel values corresponding to the specified band. The dimensions of the array correspond to the [height][width] of the EzImage. The number of bands will be 1 for a gray-scale or binary image, 3 for a color image without transparency, and 4 for a color image with transparency. The bands are (in order) RED (or GRAY), GREEN, BLUE, ALPHA. Pixel values are in the range 0-255.

Parameters:

band - is either RED, GREEN, BLUE, ALPHA, or GRAY

Returns:

an array of pixels.

Throws:

java.lang.IllegalArgumentException - if gray band is requested from color image, or vice-versa

getPixels2D

public int[][] getPixels2D()

Returns a 2D array of pixel values corresponding to gray values. This method is only valid if the image is gray. The dimensions of the array correspond to the [height][width] of the EzImage. Pixel values are in the range 0-255.

Returns:

an array of pixels.

Throws:

java.lang.UnsupportedOperationException - if image is color

getPixels1D

public int[] getPixels1D(int band)

Returns a 1D array of pixel values corresponding to the specified band. The array is layed out in row-major format and contains height*width pixel values. The number of bands will be 1 for a gray-scale or binary image, 3 for a color image without transparency, and 4 for a color image with transparency. The bands are (in order) RED (or GRAY), GREEN, BLUE, ALPHA. Pixel values are in the range 0-255.

Parameters:

band - is either RED, GREEN, BLUE, ALPHA, or GRAY

Returns:

an array of pixels.

Throws:

java.lang.IllegalArgumentException - if gray band is requested from color image, or vice-versa

getPixels1D

public int[] getPixels1D()

Returns a 1D array of pixel values corresponding to gray values. This method is only valid if the image is gray. The array is layed out in row-major format and contains height*width pixel values. Pixel values are in the range 0-255.

Returns:

an array of pixels.

Throws:

java.lang.UnsupportedOperationException - if image is color

getPixel

public int getPixel(int h,
                    int w,
                    int band)

Returns a single pixel value.

Parameters:

h - the pixel's height value

w - the pixel's width value

band - one of GRAY, RED, GREEN, BLUE, or ALPHA

Returns:

the pixel value at the specified location

Throws:

java.lang.IndexOutOfBoundsException - if the height and width are outside the image's dimensions.

getRedPixel

public int getRedPixel(int h,
                       int w)

Returns a single pixel value in the RED band.

Parameters:

h - the pixel's height value

w - the pixel's width value

Returns:

the RED pixel value at the specified location.

getGreenPixel

public int getGreenPixel(int h,
                         int w)

Returns a single pixel value in the GREEN band.

Parameters:

h - the pixel's height value

w - the pixel's width value

Returns:

the GREEN pixel value at the specified location.

getBluePixel

public int getBluePixel(int h,
                        int w)

Returns a single pixel value in the BLUE band.

Parameters:

h - the pixel's height value

w - the pixel's width value

Returns:

the BLUE pixel value at the specified location.

getGrayPixel

public int getGrayPixel(int h,
                        int w)

Returns a single pixel value in the GRAY band.

Parameters:

h - the pixel's height value

w - the pixel's width value

Returns:

the GRAY pixel value at the specified location.

setPixels

public void setPixels(int[] pixels)

Sets all of the EzImage pixels. This method is only valid if the image is gray. The array is layed out in row-major format and contains height*width pixel values. Pixel values are in the range 0-255.

Parameters:

pixels - an array of pixels.

Throws:

java.lang.UnsupportedOperationException - if image is color

setPixels

public void setPixels(int[] pixels,
                      int band)

Sets all of the EzImage pixels in the specified band. The number of elements in the array must be equal to height*width of the EzImage. The band must be GRAY if the image is gray-scale, or RED, GREEN, BLUE, or ALPHA is the image is color. Pixel values not in the range 0-255 will be stripped of their higher-order bits.

Parameters:

pixels - an array of the "new" image for the specified band.

band - one of GRAY, RED, GREEN, BLUE, or ALPHA

Throws:

java.lang.IllegalArgumentException - if the pixels array is not compatible with the image, or if an illegal color band is specified.

setPixels

public void setPixels(int[][] pixels)

Sets all of the EzImage pixels. This method is only valid if the image is gray. The array is layed out in row-major format and contains height*width pixel values. Pixel values are in the range 0-255.

Parameters:

pixels - an array of pixels.

Throws:

java.lang.UnsupportedOperationException - if image is color

setPixels

public void setPixels(int[][] pixels,
                      int band)

Sets all of the EzImage pixels in the specified band. The number of elements in the array must be equal to height*width of the EzImage. The band must be GRAY if the image is gray-scale, or RED, GREEN, BLUE, or ALPHA is the image is color. Pixel values not in the range 0-255 will be stripped of their higher-order bits.

Parameters:

pixels - an array of the "new" image for the specified band.

band - one of GRAY, RED, GREEN, BLUE, or ALPHA

Throws:

java.lang.IllegalArgumentException - if the pixels array is not compatible with the image, or if an illegal color band is specified.

setPixels

public void setPixels(int[][][] pixels)

Sets all of the EzImage pixels. The dimensions of the pixels array must correspond to [height][width][bands] of the EzImage. The number of bands will be 1 for a gray-scale or binary image, 3 for a color image without transparency, and 4 for a color image with transparency. The bands are (in order) RED (or GRAY), GREEN, BLUE, ALPHA. Pixel values not in the range 0-255 will be stripped of their higher-order bits.

Parameters:

pixels - a 3D array of HEIGHT by WIDTH by DEPTH pixels of the image

Throws:

java.lang.IllegalArgumentException - if the pixels array is not compatible with the image.

setPixel

public void setPixel(int h,
                     int w,
                     int band,
                     int value)

Sets a single EzImage pixel value in the specified band to the specified value. The number of bands will be 1 for a gray-scale or binary image, 3 for a color image without transparency, and 4 for a color image with transparency. The bands are (in order) RED (or GRAY), GREEN, BLUE, ALPHA. Pixel values not in the range 0-255 will be stripped of their higher-order bits.

Parameters:

h - the height value of the pixel to be modified

w - the width value of the pixel to be modified

band - one of GRAY, RED, GREEN, BLUE, or ALPHA

value - the new pixel value

Throws:

java.lang.IndexOutOfBoundsException - if the user specifies an invalid color band or a pixel values that's outside the range of the EzImage dimensions.

setRedPixel

public void setRedPixel(int h,
                        int w,
                        int value)

Sets a single red EzImage pixel value in the specified band to the specified value. Pixel values not in the range 0-255 will be stripped of their higher-order bits.

Parameters:

h - the height value of the pixel to be modified

w - the width value of the pixel to be modified

value - the new pixel value

Throws:

java.lang.IndexOutOfBoundsException - if the user specifies a pixel value that's outside the range of the EzImage dimensions.

setGreenPixel

public void setGreenPixel(int h,
                          int w,
                          int value)

Sets a single green EzImage pixel value in the specified band to the specified value. Pixel values not in the range 0-255 will be stripped of their higher-order bits.

Parameters:

h - the height value of the pixel to be modified

w - the width value of the pixel to be modified

value - the new pixel value

Throws:

java.lang.IndexOutOfBoundsException - if the user specifies a pixel value that's outside the range of the EzImage dimensions.

setBluePixel

public void setBluePixel(int h,
                         int w,
                         int value)

Sets a single blue EzImage pixel value in the specified band to the specified value. Pixel values not in the range 0-255 will be stripped of their higher-order bits.

Parameters:

h - the height value of the pixel to be modified

w - the width value of the pixel to be modified

value - the new pixel value

Throws:

java.lang.IndexOutOfBoundsException - if the user specifies a pixel value that's outside the range of the EzImage dimensions.

setGrayPixel

public void setGrayPixel(int h,
                         int w,
                         int value)

Sets a single gray EzImage pixel value in the specified band to the specified value. Pixel values not in the range 0-255 will be stripped of their higher-order bits.

Parameters:

h - the height value of the pixel to be modified

w - the width value of the pixel to be modified

value - the new pixel value

Throws:

java.lang.IndexOutOfBoundsException - if the user specifies a pixel value that's outside the range of the EzImage dimensions.

isColor

public boolean isColor()

Returns true if the image is a color image and false otherwise.

Returns:

true if the image is a color image and false otherwise.

Throws:

java.lang.IllegalStateException - if the number of bands is nonsensical.

numColorBands

public int numColorBands()

Returns the number of color bands present in the image.

Returns:

the number of color bands in this image

getSupportedWritingFormats

public java.lang.String[] getSupportedWritingFormats()

Returns a String array listing the file formats supported by this class for writing.

Returns:

an array of strings listing the supported file formats.

getBufferedImage

public java.awt.image.BufferedImage getBufferedImage()

Returns the image in BufferedImage format.

Returns:

the image in BufferedImage format

getHeight

public int getHeight()

Returns the height of the image.

Returns:

the height of this image

getWidth

public int getWidth()

Returns the width of the image.

Returns:

the height of this image

appendToRight

public EzImage appendToRight(EzImage image)

Creates a new image that has this image on the left and the input image on the right (with no space in between. If one image is taller than the other, white space will be added as buffer. If one image is grayscale and the other is not, the new image will be in grayscale.

Parameters:

image - the input image to be on the right

Returns:

the newly created image

copy

public EzImage copy()

Returns a copy of the calling EzImage.

Returns:

A copy of the EzImage.

show

public void show(java.lang.String title)

Creates a window that will display this EzImage. EzImage maintains a count of all windows shown and will terminate the application if all such windows are closed.

Parameters:

title - the title of the window

show

public void show(java.lang.String title,
                 int row,
                 int column)

Creates a window that will display this EzImage. EzImage maintains a count of all windows shown and will terminate the application if all such windows are closed.

Parameters:

title - the title of the window

row - the row coordinate of the upper left corner of the window

column - the column coordinate of the upper left corner of the window

save

public void save(java.lang.String filename,
                 java.lang.String format)
          throws java.io.IOException

Creates an image file having the specified name and of the specified format.

Parameters:

filename - the name of the file to be saved

format - String containing one of the supported Java file types

Throws:

java.io.IOException - if the file cannot be created, IllegalArgumentException if the file type is not supported

main

public static void main(java.lang.String[] args)
                 throws java.io.IOException

The main method for this class. Used for testing purposes only! It is highly recommended that you write your own main method in a separate class file to use the EzImage class.

Throws:

java.io.IOException