org.openimaj.image.analysis.algorithm

Class HoughLines

java.lang.Object

org.openimaj.image.analysis.algorithm.HoughLines

All Implemented Interfaces:

Iterable<Line2d>, Iterator<Line2d>, ImageAnalyser<FImage>

public class HoughLines
extends Object
implements ImageAnalyser<FImage>, Iterable<Line2d>, Iterator<Line2d>

Implementation of the Hough Transform for lines as an ImageAnalyser. The input image should have the lines to detect zeroed in the image (black). All other values will be ignored. That means you usually need to invert images created with edge detectors.

        
		CannyEdgeDetector2 ced = new CannyEdgeDetector2();
		FImage i = ced.process( ImageUtilities.readF( new File( 'test.jpg' ) );
		
		HoughLines hl = new HoughLines();
		i.inverse().analyse( hl );
		double d = hl.calculatePrevailingAngle();
	
        

The analyser is iterable over the lines that are found within the accumulator space. Iterated lines will be returned in strength order. Once an iterator has been created, the object contains a copy of the accumulator space until clearIterator() is called. You can use the Java 5 for construct:

                int maxLines = 20;
                for( Line2d line: hl ) {
                        System.out.println( "Line: "+line );
                        if( --maxLines == 0 )
                                break;
                }
                hl.clearIterator();
        

To convert a bin into a degree, use bin*360d/getNumberOfSegments(). To convert a degree into a bin, use degree/360d/getNumberOfSegments().

Author:

Jonathon Hare (jsh2@ecs.soton.ac.uk), David Dupplaw (dpd@ecs.soton.ac.uk)

Created:

8 Aug 2011

Constructor Summary

Constructors

Constructor and Description
HoughLines() Default constructor that creates an accumulator space for 360 degrees with a "on value" of 0.0f
HoughLines(float onValue) Constructor that creates a default accumulator space with a specified value for pixels considered to be "on"
HoughLines(int nSegments, float onValue) Constructor that creates an accumulator space for the given number of segments.

Method Summary

Modifier and Type	Method and Description
void	analyseImage(FImage image) Analyse an image.
FImage	calculateHorizontalProjection() Calculates a projection across the accumulator space.
FImage	calculateHorizontalProjection(FImage accum) Calculates a projection across the given accumulator space.
double	calculatePrevailingAngle() Returns the most frequent angle that occurs within the accumulator space by calculating a horizontal projection over the accumulator space and returning the angle with the most votes.
double	calculatePrevailingAngle(FImage accum, int offset, double nDegrees) Returns the most frequent angle that occurs within the given accumulator space by calculating a horizontal projection over the accumulator space and returning the angle with the most votes.
double	calculatePrevailingAngle(float minTheta, float maxTheta) Returns the most frequent angle that occurs within the given accumulator space with a given range of angles (specified in degrees) by calculating a horizontal projection over the given accumulator space and returning the angle with the most votes.
void	clearIterator() Remove the temporary objects created during iteration.
FImage	getAccumulator() Returns the accumulator space.
Line2d	getBestLine() Returns the top line in the accumulator space.
Line2d	getBestLine(FImage accumulatorSpace, int offset) Returns the top line in the given accumulator space.
Line2d	getBestLine(float minTheta, float maxTheta) Returns the best line within a certain angular range.
List<Line2d>	getBestLines(int n) Returns the top n lines from the accumulator space.
List<Line2d>	getBestLines(int n, FImage accumulatorSpace, int offset) Returns the top n lines from the given accumulator space.
List<Line2d>	getBestLines(int n, float minTheta, float maxTheta) Returns the top n lines from the given accumulator space within the range.
Line2d	getLineFromParams(int theta, int dist, int x1, int x2) From a r,theta parameterisation of a line, this returns a Line2d with endpoints at the given x coordinates.
int	getNumberOfSegments() Get the number of directional accumulator bins.
boolean	hasNext()
Iterator<Line2d>	iterator()
Line2d	next()
void	remove()
void	setNumberOfSegments(int numberOfSegments) Set the number of segments used in the accumulator space.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Methods inherited from interface java.util.Iterator

forEachRemaining

Constructor Detail

HoughLines

public HoughLines()

Default constructor that creates an accumulator space for 360 degrees with a "on value" of 0.0f

HoughLines

public HoughLines(float onValue)

Constructor that creates a default accumulator space with a specified value for pixels considered to be "on"

Parameters:

onValue - value of pixels considered on

HoughLines

public HoughLines(int nSegments,
                  float onValue)

Constructor that creates an accumulator space for the given number of segments.

Parameters:

nSegments - The number of segments.

onValue - value of pixels considered on

Method Detail

analyseImage

public void analyseImage(FImage image)

Analyse an image.

Specified by:

analyseImage in interface ImageAnalyser<FImage>

Parameters:

image - The image to process in place.

See Also:

ImageAnalyser.analyseImage(org.openimaj.image.Image)

getAccumulator

public FImage getAccumulator()

Returns the accumulator space.

Returns:

The accumulator space FImage

calculateHorizontalProjection

public FImage calculateHorizontalProjection()

Calculates a projection across the accumulator space. Returns an image that has width getNumberOfSegments() and height of 1. Effectively sums across the distances from origin in the space such that you end up with a representation that gives you the strength of the angles in the image irrespective of where those lines occur.

Returns:

A horizontal projection on the accumulator space as an FImage with dimensions getNumberOfSegments() x 1

calculateHorizontalProjection

public FImage calculateHorizontalProjection(FImage accum)

Calculates a projection across the given accumulator space. Returns an image that has width the same as the input and height of 1. Effectively sums across the distances from origin in the space such that you end up with a representation that gives you the strength of the angles in the image irrespective of where those lines occur.

Parameters:

accum - The accumulator space to project

Returns:

A horizontal projection on the accumulator space as an FImage with same width as input image but only 1 pixel high

calculatePrevailingAngle

public double calculatePrevailingAngle()

Returns the most frequent angle that occurs within the accumulator space by calculating a horizontal projection over the accumulator space and returning the angle with the most votes. The prevailing angle is given in degrees. If it is less than zero, then no angle could be extracted (there was no local maxima in the accumulator).

Returns:

The prevailing angle (degrees) in the accumulator space; or Double.MIN_VALUE if the value cannot be calculated

calculatePrevailingAngle

public double calculatePrevailingAngle(FImage accum,
                                       int offset,
                                       double nDegrees)

Returns the most frequent angle that occurs within the given accumulator space by calculating a horizontal projection over the accumulator space and returning the angle with the most votes. The prevailing angle is given in degrees. If it is less than zero, then no angle could be extracted (there was no local maxima in the accumulator).

Parameters:

accum - The accumulator space to use

offset - The offset into the accumulator of the 0 degree bin

nDegrees - The number of degrees covered by the accumulator space

Returns:

The prevailing angle (degrees) in the accumulator space; or Double.MIN_VALUE if there is no prevailing angle

calculatePrevailingAngle

public double calculatePrevailingAngle(float minTheta,
                                       float maxTheta)

Returns the most frequent angle that occurs within the given accumulator space with a given range of angles (specified in degrees) by calculating a horizontal projection over the given accumulator space and returning the angle with the most votes. The prevailing angle is given in degrees. If it is less than zero, then no angle could be extracted (there was no local maxima in the accumulator).

Parameters:

minTheta - The minimum angle (degrees)

maxTheta - The maximum angle (degrees)

Returns:

The prevailing angle within the given range; or Double.MIN_VALUE if the value cannot be calculated

getBestLine

public Line2d getBestLine()

Returns the top line in the accumulator space. The end points of the line will have x coordinates at -2000 and 2000.

Returns:

The strongest line in the accumulator space

getBestLine

public Line2d getBestLine(FImage accumulatorSpace,
                          int offset)

Returns the top line in the given accumulator space. The end points of the line will have x coordinates at -2000 and 2000.

Parameters:

accumulatorSpace - The accumulator space to look within

offset - The number of bins offset from zero degrees

Returns:

The strongest line in the accumulator space

getBestLine

public Line2d getBestLine(float minTheta,
                          float maxTheta)

Returns the best line within a certain angular range. Angles should be provided in degrees (0..359). If the best line has the maximum or minimum angles it will be returned.

Parameters:

minTheta - Minimum angle of the best line

maxTheta - Maximum angle of the best line

Returns:

The best line that has an angle within the given range.

getBestLines

public List<Line2d> getBestLines(int n,
                                 float minTheta,
                                 float maxTheta)

Returns the top n lines from the given accumulator space within the range. The end points of the lines will have x coordinates at -2000 and 2000.

Parameters:

n - The number of lines to return

minTheta - The minimum angle (degrees)

maxTheta - The maximum angle (degrees)

Returns:

A list of lines

getBestLines

public List<Line2d> getBestLines(int n)

Returns the top n lines from the accumulator space. The end points of the lines will have x coordinates at -2000 and 2000.

Parameters:

n - The number of lines to return

Returns:

A list of lines

getBestLines

public List<Line2d> getBestLines(int n,
                                 FImage accumulatorSpace,
                                 int offset)

Returns the top n lines from the given accumulator space. The end points of the lines will have x coordinates at -2000 and 2000.

Parameters:

n - The number of lines to return

accumulatorSpace - The space to look within

offset - The offset into the accumulator of 0 in this space

Returns:

A list of lines

getLineFromParams

public Line2d getLineFromParams(int theta,
                                int dist,
                                int x1,
                                int x2)

From a r,theta parameterisation of a line, this returns a Line2d with endpoints at the given x coordinates. If theta is 0 this will return a vertical line between -2000 and 2000 with the x-coordinate the appopriate distance from the origin.

Parameters:

theta - The angle bin in which the line lies (x in the accumulator space)

dist - The distance bin in which the line lies (y in the accumulator space)

x1 - The x-coordinate of the start of the line

x2 - The x-coordinate of the end of the line

Returns:

A Line2d

iterator

public Iterator<Line2d> iterator()

Specified by:

iterator in interface Iterable<Line2d>

See Also:

Iterable.iterator()

hasNext

public boolean hasNext()

Specified by:

hasNext in interface Iterator<Line2d>

See Also:

Iterator.hasNext()

next

public Line2d next()

Specified by:

next in interface Iterator<Line2d>

See Also:

Iterator.next()

remove

public void remove()

Specified by:

remove in interface Iterator<Line2d>

See Also:

Iterator.remove()

clearIterator

public void clearIterator()

Remove the temporary objects created during iteration.

setNumberOfSegments

public void setNumberOfSegments(int numberOfSegments)

Set the number of segments used in the accumulator space. By default this value is 360 (one accumulator bin per degree). However, if you require greater accuracy then this can be changed. It is suggested that it is a round multiple of 360.

Parameters:

numberOfSegments - Set the number of directional bins in the accumulator space

getNumberOfSegments

public int getNumberOfSegments()

Get the number of directional accumulator bins.

Returns:

the number of directional bins in the accumulator space.