Class EzImage

Object
  EzImage

public class EzImage
extends 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 Integer	ALPHA
static Integer	BLUE
static Integer	GRAY
static Integer	GREEN
static Integer	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(Integer[][] pixels)
Constructs an EzImage object represented by the specified pixels.

EzImage(Integer[][][] pixels)
Constructs an EzImage object represented by the specified pixels.

EzImage(Integer[] pixels, Integer height, Integer width)
Constructs an EzImage object represented by the specified pixels.

EzImage(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.
Integer	getHeight() Returns the height of the image.
Integer[]	getPixels1D() Returns a 1D array of pixel values corresponding to gray values.
Integer[]	getPixels1D(Integer band) Returns a 1D array of pixel values corresponding to the specified band.
Integer[][]	getPixels2D() Returns a 2D array of pixel values corresponding to gray values.
Integer[][]	getPixels2D(Integer band) Returns a 2D array of pixel values corresponding to the specified band.
Integer[][][]	getPixels3D() Returns a 3D array of pixel values.
String[]	getSupportedWritingFormats() Returns a String array listing the file formats supported by this class for writing.
Integer	getWidth() Returns the width of the image.
Boolean	isColor() Returns true if the image is a color image and false otherwise.
static void	main(String[] args) The main method for this class.
Integer	numColorBands() Returns the number of color bands present in the image.
void	save(String filename, String format) Creates an image file having the specified name and of the specified format.
void	setPixels(Integer[] pixels) Sets all of the EzImage pixels.
void	setPixels(Integer[][] pixels) Sets all of the EzImage pixels.
void	setPixels(Integer[][][] pixels) Sets all of the EzImage pixels.
void	setPixels(Integer[][] pixels, Integer band) Sets all of the EzImage pixels in the specified band.
void	setPixels(Integer[] pixels, Integer band) Sets all of the EzImage pixels in the specified band.
void	show() Creates a window that will display this EzImage.
void	show(String title) Creates a window that will display this EzImage.
void	show(String title, Integer row, Integer column) Creates a window that will display this EzImage.

Methods inherited from class Object

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

Field Detail

RED

public static final Integer RED

GREEN

public static final Integer GREEN

BLUE

public static final Integer BLUE

GRAY

public static final Integer GRAY

ALPHA

public static final Integer ALPHA

Constructor Detail

EzImage

public EzImage(Integer[][] 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:

IllegalArgumentException - if pixels is null

EzImage

public EzImage(Integer[][][] 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:

IllegalArgumentException - if pixels is null

EzImage

public EzImage(Integer[] pixels,
               Integer height,
               Integer 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:

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(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 Integer[][][] 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 Integer[][] getPixels2D(Integer 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:

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

getPixels2D

public Integer[][] 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:

UnsupportedOperationException - if image is color

getPixels1D

public Integer[] getPixels1D(Integer 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:

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

getPixels1D

public Integer[] 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:

UnsupportedOperationException - if image is color

setPixels

public void setPixels(Integer[] 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:

UnsupportedOperationException - if image is color

setPixels

public void setPixels(Integer[] pixels,
                      Integer 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:

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

setPixels

public void setPixels(Integer[][] 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:

UnsupportedOperationException - if image is color

setPixels

public void setPixels(Integer[][] pixels,
                      Integer 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:

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

setPixels

public void setPixels(Integer[][][] 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:

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:

IllegalStateException - if the number of bands is nonsensical.

numColorBands

public Integer numColorBands()

Returns the number of color bands present in the image.

Returns:

the number of color bands in this image

getSupportedWritingFormats

public 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 Integer getHeight()

Returns the height of the image.

Returns:

the height of this image

getWidth

public Integer 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(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()

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.

show

public void show(String title,
                 Integer row,
                 Integer 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(String filename,
                 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(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