org.jscience.computing.ai.vision
Class Histogram

java.lang.Object
  org.jscience.computing.ai.vision.Histogram

All Implemented Interfaces:

Visualizable

public class Histogram
extends java.lang.Object
implements Visualizable

This class provides a simple way of calculating a histogram for a given image. This class implements Visualizable, for easy viewing and image output.

TODO: There is still a fair amount to be implemented here, as histograms play an extremely important part in image analysis, machine vision due to their statistical importance.

Another possible expansion is to increase the flexibility by allowing a variable number of bins. HSB support would also be a nice addition.

Field Summary

static int	BAND_ALL All the bands
static int	BAND_BLUE The blue band
static int	BAND_GREEN The green band
static int	BAND_GREY The grey band
static int	BAND_RED The red band
protected java.awt.Color	clrBackground The background colour of the visualized histogram
protected long[][]	colourBins The bins for the three colour bands
protected long[][]	cumulativeBins The cumulative histogram bins.
static int	DO_LINE Draw the histogram as a line
static int	DO_SOLID Draw the histograms as a solid shape.
protected int	drawOptions Additional options for drawing.
protected boolean	isGreyscale Is the image greyscale?

Constructor Summary

Histogram()
Creates a new instance of Histogram

Histogram(java.awt.image.BufferedImage img)
Creates a new instance of Histogram, as well as specifying an image to calculate a histogram for.

Histogram(java.awt.image.BufferedImage img, int options)
As Histogram(BufferedImage) with additional drawing options.

Method Summary

void	create(java.awt.image.BufferedImage img) Create the histogram for a given image.
protected void	createCumulative() Create the cumulative bins.
long[]	getCumulativeFrequencies(int b) Returns the array of cumulative frequencies for the given colour band.
long	getCumulativeFrequency(int i) Return a cumulative frequency at a given index for band 0.
long	getCumulativeFrequency(int i, int b) Retrieve the cumulative histogram data.
long[]	getFrequencies(int b) Return the frequencies for a given band.
long	getFrequency(int i) Retrieve the frequency for a given band (band 0).
long	getFrequency(int i, int b) Retrieve the current histogram data.
long[]	getMaximum() Return the maximum values for each band in the histogram.
double[]	getMean() Returns the mean values for each band in the histogram.
int[]	getMostFrequent() This method returns the most frequent bucket for each band in the histogram.
double[]	getStandardDeviation() Returns the standard deviations for each band in the histogram.
boolean	isGreyscale() Has this histogram been created for a greyscale image?
void	render(java.awt.Graphics gfx, int width, int height) Renders the histogram as a line or group of solids.
void	setBackgroundColour(java.awt.Color bkc) Set the background colour for the visualized histogram.
void	setDrawOptions(int drawOptions) Set the draw option for the histogram.
protected void	writeBand(java.io.File freqFile, int band) Write the given histogram band to a FileWriter.
protected void	writeCumulativeBand(java.io.File cumFreqFile, int band) Write cumulative frequencies for a given colour band.
void	writeCumulativeFrequencies(java.io.File freqFile) Write the cumulative frequencies for a greyscale image.
void	writeCumulativeFrequencies(java.io.File redFile, java.io.File greenFile, java.io.File blueFile) Write the cumulative frequencies for an RGB image.
void	writeFrequencies(java.io.File freqFile) Write frequencies for a greyscale histogram.
void	writeFrequencies(java.io.File redFile, java.io.File greenFile, java.io.File blueFile) Write frequencies for an RGB image.
void	writeImage(java.lang.String filename, int width, int height) Write the visualized histogram to an image file.

Methods inherited from class java.lang.Object

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

Field Detail

BAND_RED

public static final int BAND_RED

The red band

See Also:

Constant Field Values

BAND_GREEN

public static final int BAND_GREEN

The green band

See Also:

Constant Field Values

BAND_BLUE

public static final int BAND_BLUE

The blue band

See Also:

Constant Field Values

BAND_GREY

public static final int BAND_GREY

The grey band

See Also:

Constant Field Values

BAND_ALL

public static final int BAND_ALL

All the bands

See Also:

Constant Field Values

DO_LINE

public static final int DO_LINE

Draw the histogram as a line

See Also:

Constant Field Values

DO_SOLID

public static final int DO_SOLID

Draw the histograms as a solid shape. The class renders the bands in order (RGB), therefore the solid shapes may obscure each other.

See Also:

Constant Field Values

clrBackground

protected java.awt.Color clrBackground

The background colour of the visualized histogram

colourBins

protected long[][] colourBins

The bins for the three colour bands

cumulativeBins

protected long[][] cumulativeBins

The cumulative histogram bins.

isGreyscale

protected boolean isGreyscale

Is the image greyscale?

drawOptions

protected int drawOptions

Additional options for drawing.

See Also:

DO_SOLID, DO_LINE

Constructor Detail

Histogram

public Histogram()

Creates a new instance of Histogram

Histogram

public Histogram(java.awt.image.BufferedImage img)

Creates a new instance of Histogram, as well as specifying an image to calculate a histogram for. The histogram is calculated immediately.

Parameters:

img - the image to calculate the histogram for.

Histogram

public Histogram(java.awt.image.BufferedImage img,
                 int options)

As Histogram(BufferedImage) with additional drawing options.

Parameters:

img - the image to calculate the histogram for.

options - additional drawing options.

See Also:

Histogram(BufferedImage)

Method Detail

create

public void create(java.awt.image.BufferedImage img)

Create the histogram for a given image. The class detects whether the input image is greyscale or colour, and creates the histogram accordingly.

Parameters:

img - the image to calculate the histogram for.

createCumulative

protected void createCumulative()

Create the cumulative bins.

isGreyscale

public boolean isGreyscale()

Has this histogram been created for a greyscale image?

Returns:

whether the histogram is greyscale.

setDrawOptions

public void setDrawOptions(int drawOptions)

Set the draw option for the histogram.

Parameters:

drawOptions - the draw options.

setBackgroundColour

public void setBackgroundColour(java.awt.Color bkc)

Set the background colour for the visualized histogram.

Parameters:

bkc - the colour (default is Color.lightGray)

getFrequency

public long getFrequency(int i,
                         int b)

Retrieve the current histogram data.

Parameters:

i - the index of the colour bin (0-255).

b - the colour band (BAND_RED, BAND_GREEN, BAND_BLUE or BAND_GREY).

Returns:

the histogram data for the given bin and band.

getFrequency

public long getFrequency(int i)

Retrieve the frequency for a given band (band 0). The method is defined as: return getFrequency(i, 0);

Parameters:

i - the grey level index.

Returns:

the frequency at level i.

getFrequencies

public long[] getFrequencies(int b)

Return the frequencies for a given band.

Parameters:

b - the band (red, green or blue).

Returns:

the frequencies of the band.

getCumulativeFrequency

public long getCumulativeFrequency(int i,
                                   int b)

Retrieve the cumulative histogram data.

Parameters:

i - the index of the cumulative bin.

b - the colour band.

Returns:

the cumulative frequency for the index and band.

getCumulativeFrequency

public long getCumulativeFrequency(int i)

Return a cumulative frequency at a given index for band 0.

Parameters:

i - the index.

Returns:

the cumulative frequency at index i.

getCumulativeFrequencies

public long[] getCumulativeFrequencies(int b)

Returns the array of cumulative frequencies for the given colour band.

Parameters:

b - the colour band.

Returns:

the cumulative frequencies for the colour band.

getMaximum

public long[] getMaximum()

Return the maximum values for each band in the histogram.

Returns:

the maximum values.

getMostFrequent

public int[] getMostFrequent()

This method returns the most frequent bucket for each band in the histogram. If multiple buckets are equal in frequency, the first is returned.

Returns:

the most frequent buckets for each band.

getMean

public double[] getMean()

Returns the mean values for each band in the histogram.

Returns:

the mean values.

getStandardDeviation

public double[] getStandardDeviation()

Returns the standard deviations for each band in the histogram.

Returns:

the standard deviations.

render

public void render(java.awt.Graphics gfx,
                   int width,
                   int height)

Renders the histogram as a line or group of solids. Note that the histogram is auto-scaled, using the maximum histogram bin value. If the render function is to draw the histogram using lines, it simply joins the values together to form a continuous line. If a solid object is to be drawn, the render function interpolates the histogram data across the width of the image, sometimes causing a slight discrepancy.

Specified by:

render in interface Visualizable

Parameters:

gfx - the graphics context

width - width of the histogram image

height - height of the histogram image

writeImage

public void writeImage(java.lang.String filename,
                       int width,
                       int height)

Write the visualized histogram to an image file.

Specified by:

writeImage in interface Visualizable

Parameters:

filename - the filename of the image to write.

width - width of the image.

height - height of the image.

writeBand

protected void writeBand(java.io.File freqFile,
                         int band)

Write the given histogram band to a FileWriter.

Parameters:

freqFile - the file writer.

band - the band to write.

writeFrequencies

public void writeFrequencies(java.io.File freqFile)

Write frequencies for a greyscale histogram.

Parameters:

freqFile - the greyscale frequency file.

writeFrequencies

public void writeFrequencies(java.io.File redFile,
                             java.io.File greenFile,
                             java.io.File blueFile)

Write frequencies for an RGB image.

Parameters:

redFile - the red frequency file.

greenFile - the green frequency file.

blueFile - the blue frequency file.

writeCumulativeBand

protected void writeCumulativeBand(java.io.File cumFreqFile,
                                   int band)

Write cumulative frequencies for a given colour band.

Parameters:

cumFreqFile - the cumulative frequency file.

band - the band.

writeCumulativeFrequencies

public void writeCumulativeFrequencies(java.io.File freqFile)

Write the cumulative frequencies for a greyscale image.

Parameters:

freqFile - the greyscale cumulative frequency file.

writeCumulativeFrequencies

public void writeCumulativeFrequencies(java.io.File redFile,
                                       java.io.File greenFile,
                                       java.io.File blueFile)

Write the cumulative frequencies for an RGB image.

Parameters:

redFile - the red cumulative frequency file.

greenFile - the green cumulative frequency file.

blueFile - the blue cumulative frequency file.