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

static int	ALPHA
static int	BLUE
static int	GRAY
static int	GREEN
static int	RED

Constructor Summary

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

EzImage	copy() Returns a copy of the calling EzImage.
EzImage	copyToGrayScale() Returns an EzImage object that is a gray-scale copy.
java.awt.image.BufferedImage	getBufferedImage() Returns the image in BufferedImage format.
int	getHeight() Returns the height of the image.
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.
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	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	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

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.

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

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