tools
Class CannyEdgeDetector

java.lang.Object
  extended by tools.CannyEdgeDetector
All Implemented Interfaces:
AnalysisFilter

public class CannyEdgeDetector
extends java.lang.Object
implements AnalysisFilter

This software has been released into the public domain. Please read the notes in this source file for additional information.

This class provides a configurable implementation of the Canny edge detection algorithm. This classic algorithm has a number of shortcomings, but remains an effective tool in many scenarios. This class is designed for single threaded use only.

Sample usage:


 //create the detector
 CannyEdgeDetector detector = new CannyEdgeDetector();
 //adjust its parameters as desired
 detector.setLowThreshold(0.5f);
 detector.setHighThreshold(1f);
 //apply it to an image
 detector.setSourceImage(frame);
 detector.process();
 BufferedImage edges = detector.getEdgesImage();
 

For a more complete understanding of this edge detector's parameters consult an explanation of the algorithm.

Author:
Tom Gibara

Constructor Summary
CannyEdgeDetector()
          Constructs a new detector with default parameters.
 
Method Summary
 java.awt.image.BufferedImage getEdgesImage()
          Obtains an image containing the edges detected during the last call to the process method.
 float getGaussianKernelRadius()
          The radius of the Gaussian convolution kernel used to smooth the source image prior to gradient calculation.
 int getGaussianKernelWidth()
          The number of pixels across which the Gaussian kernel is applied.
 float getHighThreshold()
          The high threshold for hysteresis.
 float getLowThreshold()
          The low threshold for hysteresis.
 java.awt.image.BufferedImage getSourceImage()
          The image that provides the luminance data used by this detector to generate edges.
 boolean isContrastNormalized()
          Whether the luminance data extracted from the source image is normalized by linearizing its histogram prior to edge extraction.
 void process()
           
 void setContrastNormalized(boolean contrastNormalized)
          Sets whether the contrast is normalized
 void setEdgesImage(java.awt.image.BufferedImage edgesImage)
          Sets the edges image.
 void setGaussianKernelRadius(float gaussianKernelRadius)
          Sets the radius of the Gaussian convolution kernel used to smooth the source image prior to gradient calculation.
 void setGaussianKernelWidth(int gaussianKernelWidth)
          The number of pixels across which the Gaussian kernel is applied.
 void setHighThreshold(float threshold)
          Sets the high threshold for hysteresis.
 void setLowThreshold(float threshold)
          Sets the low threshold for hysteresis.
 void setSourceImage(java.awt.image.BufferedImage image)
          Specifies the image that will provide the luminance data in which edges will be detected.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CannyEdgeDetector

public CannyEdgeDetector()
Constructs a new detector with default parameters.

Method Detail

getSourceImage

public java.awt.image.BufferedImage getSourceImage()
The image that provides the luminance data used by this detector to generate edges.

Specified by:
getSourceImage in interface AnalysisFilter
Returns:
the source image, or null

setSourceImage

public void setSourceImage(java.awt.image.BufferedImage image)
Specifies the image that will provide the luminance data in which edges will be detected. A source image must be set before the process method is called.

Specified by:
setSourceImage in interface AnalysisFilter
Parameters:
image - a source of luminance data

getEdgesImage

public java.awt.image.BufferedImage getEdgesImage()
Obtains an image containing the edges detected during the last call to the process method. The buffered image is an opaque image of type BufferedImage.TYPE_INT_ARGB in which edge pixels are white and all other pixels are black.

Returns:
an image containing the detected edges, or null if the process method has not yet been called.

setEdgesImage

public void setEdgesImage(java.awt.image.BufferedImage edgesImage)
Sets the edges image. Calling this method will not change the operation of the edge detector in any way. It is intended to provide a means by which the memory referenced by the detector object may be reduced.

Parameters:
edgesImage - expected (though not required) to be null

getLowThreshold

public float getLowThreshold()
The low threshold for hysteresis. The default value is 2.5.

Returns:
the low hysteresis threshold

setLowThreshold

public void setLowThreshold(float threshold)
Sets the low threshold for hysteresis. Suitable values for this parameter must be determined experimentally for each application. It is nonsensical (though not prohibited) for this value to exceed the high threshold value.

Parameters:
threshold - a low hysteresis threshold

getHighThreshold

public float getHighThreshold()
The high threshold for hysteresis. The default value is 7.5.

Returns:
the high hysteresis threshold

setHighThreshold

public void setHighThreshold(float threshold)
Sets the high threshold for hysteresis. Suitable values for this parameter must be determined experimentally for each application. It is nonsensical (though not prohibited) for this value to be less than the low threshold value.

Parameters:
threshold - a high hysteresis threshold

getGaussianKernelWidth

public int getGaussianKernelWidth()
The number of pixels across which the Gaussian kernel is applied. The default value is 16.

Returns:
the radius of the convolution operation in pixels

setGaussianKernelWidth

public void setGaussianKernelWidth(int gaussianKernelWidth)
The number of pixels across which the Gaussian kernel is applied. This implementation will reduce the radius if the contribution of pixel values is deemed negligable, so this is actually a maximum radius.

Parameters:
gaussianKernelWidth - a radius for the convolution operation in pixels, at least 2.

getGaussianKernelRadius

public float getGaussianKernelRadius()
The radius of the Gaussian convolution kernel used to smooth the source image prior to gradient calculation. The default value is 16.

Returns:
the Gaussian kernel radius in pixels

setGaussianKernelRadius

public void setGaussianKernelRadius(float gaussianKernelRadius)
Sets the radius of the Gaussian convolution kernel used to smooth the source image prior to gradient calculation.


isContrastNormalized

public boolean isContrastNormalized()
Whether the luminance data extracted from the source image is normalized by linearizing its histogram prior to edge extraction. The default value is false.

Returns:
whether the contrast is normalized

setContrastNormalized

public void setContrastNormalized(boolean contrastNormalized)
Sets whether the contrast is normalized

Parameters:
contrastNormalized - true if the contrast should be normalized, false otherwise

process

public void process()