Class EzImage

java.lang.Object
  extended by 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