org.jscience.computing.ai.vision
Class Histogram

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