Class EasyBufferedImage

java.lang.Object
  java.awt.Image
      java.awt.image.BufferedImage
          EasyBufferedImage

All Implemented Interfaces:

java.awt.image.RenderedImage, java.awt.image.WritableRenderedImage, java.awt.Transparency, java.io.Serializable

public class EasyBufferedImage
extends java.awt.image.BufferedImage
implements java.io.Serializable

Represents an image that can be manipulated without a thorough understanding of the built-in image classes. Performance (in terms of memory and speed) is sacrificed in order to provide simplified access to pixel data. Allows direct read/write access to individual pixels and a factory method for creating EasyBufferedImages from files. The image always appears as either a gray-scale image, an RGB image or an RGBA image. The data is never packed or interleaved (at least with respect to the get/set pixel methods).

Please note that grayscale processing of a color image always maintains the color information of the image while altering the intensity channel. To perform operations on a purely gray-scale image, convert any color images to grayscale prior to processing.

Since the EasyBufferedImage class is a sub-class of Image and BufferedImage, it is fully integrated into the standard Swing libraries for viewing and manipulation. To create an EasyBufferedImage you must use the factory method shown below:

EasyBufferedImage image = EasyBufferedImage.createImage(filename);

where the filename is a String representing an image file in either GIF, PNG, or JPEG formats. The following code fragment is an example of how to invert a gray-scale image:

 int[] pixels = image.getPixels1D(EasyBufferedImage.GRAY);
 for(int i=0; i < pixels.length; i++) {
   pixels[i] = 255-pixels[i];
 }
 image.setPixels(pixels);
 

See Also:

Image, BufferedImage, Serialized Form

Field Summary

static int	ALPHA
static int	BLUE
static int	GIF
static int	GRAY
static int	GREEN
static int	JPEG
static int	PNG
static int	RED

Fields inherited from class java.awt.image.BufferedImage

TYPE_3BYTE_BGR, TYPE_4BYTE_ABGR, TYPE_4BYTE_ABGR_PRE, TYPE_BYTE_BINARY, TYPE_BYTE_GRAY, TYPE_BYTE_INDEXED, TYPE_CUSTOM, TYPE_INT_ARGB, TYPE_INT_ARGB_PRE, TYPE_INT_BGR, TYPE_INT_RGB, TYPE_USHORT_555_RGB, TYPE_USHORT_565_RGB, TYPE_USHORT_GRAY

Fields inherited from class java.awt.Image

accelerationPriority, SCALE_AREA_AVERAGING, SCALE_DEFAULT, SCALE_FAST, SCALE_REPLICATE, SCALE_SMOOTH, UndefinedProperty

Fields inherited from interface java.awt.Transparency

BITMASK, OPAQUE, TRANSLUCENT

Method Summary

static int	clamp(double v) Returns the value of v clamped to the range 0-255.
EasyBufferedImage	copy() Returns a copy of the calling EasyBufferedImage.
EasyBufferedImage	copyToGrayScale() Returns an EasyBufferedImage object that is a gray-scale copy of the calling image.
static EasyBufferedImage	createImage(java.awt.image.BufferedImage image)
static EasyBufferedImage	createImage(java.io.File file)
static EasyBufferedImage	createImage(int[][] pixels) Returns an EasyBufferedImage object represented by the specified pixels.
static EasyBufferedImage	createImage(int[][][] pixels) Returns an EasyBufferedImage object represented by the specified pixels.
static EasyBufferedImage	createImage(int[] pixels, int width, int height) Returns an EasyBufferedImage object represented by the specified pixels.
static EasyBufferedImage	createImage(java.lang.String filename) Returns an EasyBufferedImage object by reading the image file specified by the filename.
static EasyBufferedImage	createImage(java.net.URL url) Returns an EasyBufferedImage object by reading the image specified by the url.
int[]	getPixels1D() Returns a 1D array of pixel values corresponding to the specified band.
int[]	getPixels1D(int band) Returns a 1D array of pixel values corresponding to the specified band.
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[]	getSupportedFormats() Returns a String array listing the file formats supported by this class.
boolean	isColor() Returns true if the image is a color image and false otherwise.
static void	main(java.lang.String[] args) A demo application that shows simple ways of using the EasyBufferedImage class.
void	save(java.lang.String filename, int format) Creates an image file having the specified name and of the specified format.
void	setPixels(int[][][] pixels) Sets all of the EasyBufferedImages pixels.
void	setPixels(int[][] pixels, int band) Sets all of the EasyBufferedImages pixels in the specified band.
void	setPixels(int[] pixels, int band) Sets all of the EasyBufferedImages pixels in the specified band.
void	show(java.lang.String title) Creates a window that will display this EasyBufferedImage This method maintains a count of all windows opened via calls to this method and will terminate the application if all such windows are closed.

Methods inherited from class java.awt.image.BufferedImage

addTileObserver, coerceData, copyData, createGraphics, flush, getAlphaRaster, getCapabilities, getColorModel, getData, getData, getGraphics, getHeight, getHeight, getMinTileX, getMinTileY, getMinX, getMinY, getNumXTiles, getNumYTiles, getProperty, getProperty, getPropertyNames, getRaster, getRGB, getRGB, getSampleModel, getSource, getSources, getSubimage, getTile, getTileGridXOffset, getTileGridYOffset, getTileHeight, getTileWidth, getTransparency, getType, getWidth, getWidth, getWritableTile, getWritableTileIndices, hasTileWriters, isAlphaPremultiplied, isTileWritable, releaseWritableTile, removeTileObserver, setData, setRGB, setRGB, toString

Methods inherited from class java.awt.Image

getAccelerationPriority, getScaledInstance, setAccelerationPriority

Methods inherited from class java.lang.Object

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

Field Detail

GRAY

public static final int GRAY

See Also:

Constant Field Values

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

ALPHA

public static final int ALPHA

See Also:

Constant Field Values

JPEG

public static final int JPEG

See Also:

Constant Field Values

GIF

public static final int GIF

See Also:

Constant Field Values

PNG

public static final int PNG

See Also:

Constant Field Values

Method Detail

getSupportedFormats

public java.lang.String[] getSupportedFormats()

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

Parameters:

none -

Returns:

an array of strings listing the supported file formats.

createImage

public static EasyBufferedImage createImage(java.awt.image.BufferedImage image)

createImage

public static EasyBufferedImage createImage(java.lang.String filename)
                                     throws java.io.FileNotFoundException

Returns an EasyBufferedImage object by reading the image file specified by the filename. The format of the file may be any one of GIF, PNG, or JPEG. This is a factory method to create EasyBufferedImages. There is no direct constructor access.

Parameters:

filename - the name of the file to load.

Returns:

the EasyBufferedImage stored in the file.

Throws:

java.io.FileNotFoundException

See Also:

Image, BufferedImage

createImage

public static EasyBufferedImage createImage(java.io.File file)
                                     throws java.io.IOException,
                                            java.io.FileNotFoundException

Throws:

java.io.IOException

java.io.FileNotFoundException

createImage

public static EasyBufferedImage createImage(java.net.URL url)

Returns an EasyBufferedImage object by reading the image specified by the url. The format of the file may be any one of GIF, PNG, or JPEG. This is a factory method to create EasyBufferedImages. There is no direct constructor access.

Parameters:

url - is the URL of an image file to load.

Returns:

the EasyBufferedImage stored in the file.

See Also:

Image, BufferedImage

createImage

public static EasyBufferedImage createImage(int[][][] pixels)

Returns an EasyBufferedImage object represented by the specified pixels. The dimensions of the pixel array must be [height][width][bands] where bands may be either 1 (gray-scale) or 3 (red-green-blue). This is a factory method to create EasyBufferedImages. There is no direct constructor access.

Parameters:

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

Returns:

An EasyBufferedImage representation of the pixels.

Throws:

java.lang.IllegalArgumentException - if pixels is null

See Also:

Image, BufferedImage

createImage

public static EasyBufferedImage createImage(int[][] pixels)

Returns an EasyBufferedImage object represented by the specified pixels. The dimensions of the pixel array must be [height][width] and is assumed to be gray-scale. This is a factory method to create EasyBufferedImages. There is no direct constructor access.

Parameters:

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

Returns:

An EasyBufferedImage representation of the pixels.

Throws:

java.lang.IllegalArgumentException - if pixels is null

See Also:

Image, BufferedImage

createImage

public static EasyBufferedImage createImage(int[] pixels,
                                            int width,
                                            int height)

Returns an EasyBufferedImage 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. This is a factory method to create EasyBufferedImages. There is no direct constructor access.

Parameters:

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

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

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

Returns:

An EasyBufferedImage representation of the pixels.

Throws:

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

See Also:

Image, BufferedImage

clamp

public static int clamp(double v)

Returns the value of v clamped to the range 0-255. This is a convenience method for working with image pixel values.

Parameters:

v - is the value of a pixel to be clamped.

Returns:

the value v clamped to the range 0-255.

copyToGrayScale

public EasyBufferedImage copyToGrayScale()

Returns an EasyBufferedImage object that is a gray-scale copy of the calling image.

Parameters:

None -

Returns:

an EasyBufferedImage that is a gray-scale copy of the caller.

getPixels3D

public int[][][] getPixels3D()

Returns a 3D array of pixel values. The dimensions of the array correspond to the [height][width][bands] of the EasyBufferedImage. 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:

None -

Returns:

an array of pixels accessed.

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 EasyBufferedImage. 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.

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.

getPixels1D

public int[] getPixels1D()

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.

Returns:

an array of pixels.

setPixels

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

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

Parameters:

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

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

Throws:

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

setPixels

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

Sets all of the EasyBufferedImages pixels in the specified band. The dimensions of the pixels array must correspond to [height][width] of the EasyBufferedImage. The band must be either GRAY, RED, GREEN, BLUE, or ALPHA. Pixel values not in the range 0-255 will be stripped of their higher-order bits.

Parameters:

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

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

Throws:

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

setPixels

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

Sets all of the EasyBufferedImages pixels. The dimensions of the pixels array must correspond to [height][width][bands] of the EasyBufferedImage. 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 - is 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.

Parameters:

None -

Returns:

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

copy

public EasyBufferedImage copy()

Returns a copy of the calling EasyBufferedImage.

Parameters:

None -

Returns:

A copy of the EasyBufferedImage.

show

public void show(java.lang.String title)

Creates a window that will display this EasyBufferedImage This method maintains a count of all windows opened via calls to this method and will terminate the application if all such windows are closed.

Parameters:

None -

save

public void save(java.lang.String filename,
                 int 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 - one of EasyBufferedImage.PNG, EasyBufferedImage.GIF or EasyBufferedImage.JPEG

Throws:

java.io.IOException - if the file cannot be created.

main

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

A demo application that shows simple ways of using the EasyBufferedImage class. Execute from the command line by typing

java EasyBufferedImage ImageFileName AlphaValue

where the AlphaValue is a percentage value in the range [0..100] and serves as a brightness control. Values in the range [0..1) will darken the image while values above 1 will brighten the input image. This application also saves the processed file in GIF format to a file named "Sample.gif".

    public static void main(String[] args) throws IOException
    {
        EasyBufferedImage image = EasyBufferedImage.createImage(args[0]);
        double alpha = Double.parseDouble(args[1]);
        EasyBufferedImage copy = image.copy();

        int[][] data = image.getPixels2D(EasyBufferedImage.RED);
        for(int i=0; i < image.getHeight(); i++)
        { 
            for(int j=0; j < image.getWidth(); j++)
            { 
                data[i][j] = clamp(data[i][j] * alpha);
            }
        }
        image.setPixels(data, EasyBufferedImage.RED);

        data = image.getPixels2D(EasyBufferedImage.GREEN);
        for(int i=0; i < image.getHeight(); i++)
        { 
            for(int j=0; j < image.getWidth(); j++)
            {
                data[i][j] = clamp(data[i][j] * alpha);
            }
        }
        image.setPixels(data, EasyBufferedImage.GREEN);

        data = image.getPixels2D(EasyBufferedImage.BLUE);
        for(int i=0; i < image.getHeight(); i++){ 
            for(int j=0; j < image.getWidth(); j++){ 
                data[i][j] = clamp(data[i][j] * alpha);
            }
        }
        image.setPixels(data, EasyBufferedImage.BLUE);
        image.show(args[0]);

        data = copy.getPixels2D(EasyBufferedImage.GRAY);
        for(int i=0; i < copy.getHeight(); i++){ 
            for(int j=0; j < copy.getWidth(); j++){ 
                data[i][j] = clamp(data[i][j] * alpha);
            }
        }
        copy.setPixels(data, EasyBufferedImage.GRAY);
        copy.show("GRAY SCALE PROCESSING");

        image.save("Sample.gif", EasyBufferedImage.GIF);
    }
     

Parameters:

args - is an array of two strings. The first is the filename of the file to process and the second is a perctage value to brighten/darken an image.

Throws:

IOException.

java.io.IOException