#include <vpHistogram.h>

Public Member Functions
	vpHistogram ()

	vpHistogram (const vpHistogram &h)

	vpHistogram (const vpImage< unsigned char > &I)

virtual	~vpHistogram ()

vpHistogram &	operator= (const vpHistogram &h)

unsigned	operator[] (const unsigned char level) const

unsigned	operator() (const unsigned char level) const

unsigned	get (const unsigned char level) const

void	set (const unsigned char level, unsigned int value)

void	calculate (const vpImage< unsigned char > &I)

void	smooth (const unsigned int fsize=3)

unsigned	getPeaks (std::list< vpHistogramPeak > &peaks)

unsigned	getPeaks (unsigned char dist, vpHistogramPeak &peak1, vpHistogramPeak &peak2)

bool	getPeaks (unsigned char dist, vpHistogramPeak &peakl, vpHistogramPeak &peakr, vpHistogramValey &valey)

unsigned	getValey (std::list< vpHistogramValey > &valey)

bool	getValey (const vpHistogramPeak &peak1, const vpHistogramPeak &peak2, vpHistogramValey &valey)

unsigned	getValey (unsigned char dist, const vpHistogramPeak &peak, vpHistogramValey &valeyl, vpHistogramValey &valeyr)

unsigned	sort (std::list< vpHistogramPeak > &peaks)

bool	write (const std::string &filename)

bool	write (const char *filename)

unsigned	getSize ()

unsigned *	getValues ()

Deprecated functions
vp_deprecated unsigned	getPeaks (vpList< vpHistogramPeak > &peaks)

vp_deprecated unsigned	getValey (vpList< vpHistogramValey > &valey)

vp_deprecated unsigned	sort (vpList< vpHistogramPeak > &peaks)

Detailed Description

Class to compute a gray level image histogram.

Here are two examples showing how to use this class to determine the threshold which can be used to segment two objects.

The code below:

vpImage<unsigned char> I;
...
unsigned char dist = 60;
vpHistogramValey valey;
vpHistogram h(I);
h.smooth();                   // Filter the histogram values
vpHistogramPeak peakl, peakr; // Two highest peaks in the histogram 
                              // - peakl: Peak on the left
                              // - peakr: Peak on the right
h.getPeaks(dist, peakl, peakr, valey);
unsigned char threshold;      // Position of the valey between the two peaks
threshold = valey.getLevel();

has the same behaviour than this one:

vpImage<unsigned char> I;
...
unsigned char dist = 60;
vpHistogram h(I);
h.smooth();                   // Filter the histogram values
vpHistogramPeak peak1, peak2; // Two highest peaks in the histogram 
                              // - peak1: Highest peak
                              // - peakr: Second highest peak
// Get the two highest peaks
h.getPeaks(dist, peak1, peak2);
// Get the valey between the two highest peaks
vpHistogramValey valey;
h.getValey(peak1, peak2, valey);
unsigned char threshold; // Position of the valey between the two peaks
threshold = valey.getLevel();

Examples:: histogram.cpp.

Definition at line 115 of file vpHistogram.h.

Constructor & Destructor Documentation

vpHistogram::vpHistogram ( )

Defaut constructor for a gray level histogram.

Definition at line 68 of file vpHistogram.cpp.

vpHistogram::vpHistogram ( const vpHistogram & h )

Copy constructor of a gray level histogram.

Definition at line 76 of file vpHistogram.cpp.

vpHistogram::vpHistogram ( const vpImage< unsigned char > & I )

Calculates the histrogram from a gray level image.

Parameters

I	: Gray level image.

See also: calculate()

Definition at line 89 of file vpHistogram.cpp.

References calculate().

vpHistogram::~vpHistogram ( )

virtual

Destructor.

Definition at line 100 of file vpHistogram.cpp.

Member Function Documentation

void vpHistogram::calculate ( const vpImage< unsigned char > & I )

Calculate the histogram from a gray level image.

Parameters

I	: Gray level image.

Examples:: histogram.cpp.

Definition at line 161 of file vpHistogram.cpp.

References vpImage< Type >::getHeight(), and vpImage< Type >::getWidth().

Referenced by vpHistogram().

unsigned vpHistogram::get ( const unsigned char level ) const

inline

Return the number of pixels having the gray level.

Parameters

level : Gray level in the histogram.

Returns: Number of pixels having the gray level.

vpImage<unsigned char> I; // A gray level image
vpHistogram h; 
h.calculate(I); // Histogram of the gray level image
// Print the histogram values
for (int i=0; i < h.getSize(); i ++)
  printf("%d: %d\n", i, h.get(i));

Definition at line 194 of file vpHistogram.h.

unsigned vpHistogram::getPeaks ( std::list< vpHistogramPeak > & peaks )

Build a list of all histogram peaks. This peak list is gray level sorted from 0 to 255. That mean that the first peak has a gray level less than the second one, etc.

To sort this list from highest peak value to the lowest one, you can use sort().

Parameters

peaks : List of peaks.

Returns: The number of peaks in the histogram.

See also: sort()

Examples:: histogram.cpp.

Definition at line 237 of file vpHistogram.cpp.

References vpImageException::notInitializedError, vpHistogramPeak::set(), and vpERROR_TRACE.

Referenced by getPeaks(), and getValey().

unsigned vpHistogram::getPeaks	(	unsigned char	dist,
		vpHistogramPeak &	peak1,
		vpHistogramPeak &	peak2
	)

Find the two highest peaks in the histogram. Usually, the first one correspond to the image background, the second one to the object.

Parameters

dist	: Minimal distance between two significative histogram peaks.
peak1	: Highest peak in the histogram.
peak2	: Second highest peak in the histogram.

Returns

The number of highest peaks:

2: If the histogram is bimodal
1: If no second highest peak was found.
0: if no peaks were found.

Definition at line 319 of file vpHistogram.cpp.

References vpHistogramPeak::getLevel(), getPeaks(), vpHistogramPeak::set(), and sort().

bool vpHistogram::getPeaks	(	unsigned char	dist,
		vpHistogramPeak &	peakl,
		vpHistogramPeak &	peakr,
		vpHistogramValey &	valey
	)

Determine the two highest peaks in the histogram and compute a threshold to separate the two objects. Here we dont know which is the highest peak. It could be peakl or peakr.

Parameters

dist	: Distance between two significative histogram maxima
peakl	: Position of the left histogram peak.
peakr	: Position of the right histogram peak.
valey	: Valey between the two peaks peakl and peakr.

Returns: true if the histogram is bimodal, false otherwise.

Definition at line 376 of file vpHistogram.cpp.

References vpHistogramPeak::getLevel(), vpHistogramPeak::getValue(), vpHistogramPeak::set(), and vpHistogramValey::set().

unsigned vpHistogram::getPeaks ( vpList< vpHistogramPeak > & peaks )

Deprecated:: This method is deprecated. You should use getPeaks(std::list<vpHistogramPeak> &) instead.

Build a list of all histogram peaks. This peak list is gray level sorted from 0 to 255. That mean that the first peak has a gray level less than the second one, etc.

To sort this list from highest peak value to the lowest one, you can use sort().

Parameters

peaks : List of peaks.

Returns: The number of peaks in the histogram.

See also: sort()

Definition at line 922 of file vpHistogram.cpp.

References vpList< type >::addRight(), vpList< type >::empty(), vpList< type >::front(), vpList< type >::kill(), vpImageException::notInitializedError, vpHistogramPeak::set(), and vpERROR_TRACE.

unsigned vpHistogram::getSize ( )

inline

Get the histogram size.

Returns: The size of the histogram, or the image maximum gray levels numbers.

See also: getValues()

Definition at line 252 of file vpHistogram.h.

unsigned vpHistogram::getValey ( std::list< vpHistogramValey > & valey )

Build a list of all histogram valey. This valey list is gray level sorted from 0 to 255. That mean that the first valey has a gray level less than the second one, etc.

Parameters

valey : List of valey.

Returns: The number of valey in the histogram.

See also: sort()

Examples:: histogram.cpp.

Definition at line 536 of file vpHistogram.cpp.

References vpImageException::notInitializedError, vpHistogramValey::set(), and vpERROR_TRACE.

bool vpHistogram::getValey	(	const vpHistogramPeak &	peak1,
		const vpHistogramPeak &	peak2,
		vpHistogramValey &	valey
	)

Find the valey between two peaks. It starts at the lowest peak and works its way up to the highest peak. Along the way, it looks at each point in the histogram to find the location of the smallest histogram point which is the valey point.

Parameters

peak1	: A peak in the histogram.
peak2	: A other peak in the histogram.
valey	: Low point of the valey between two peaks in a histogram.

Returns: true if a valey was found, false otherwise.

Definition at line 609 of file vpHistogram.cpp.

References vpHistogramPeak::getLevel(), vpHistogramPeak::getValue(), and vpHistogramValey::set().

unsigned vpHistogram::getValey	(	unsigned char	dist,
		const vpHistogramPeak &	peak,
		vpHistogramValey &	valeyl,
		vpHistogramValey &	valeyr
	)

Find the two valey around an histogram peak. It starts at the peak position and works its way down and up to find the left and right valey around the peak.

Parameters

dist	: Minimal distance between two significative histogram peaks.
peak	: A peak in the histogram.
valeyl	: The valey on the left of the peak.
valeyr	: The valey on the right of the peak.

Returns: 0x00 : If no valey was found.; 0x01 : If only the right valey was found.; 0x10 : If only the left valey was found.; 0x11 : If two valeys around the peak were found.

Definition at line 678 of file vpHistogram.cpp.

References vpHistogramPeak::getLevel(), getPeaks(), vpHistogramPeak::getValue(), vpHistogramPeak::set(), and vpHistogramValey::set().

unsigned vpHistogram::getValey ( vpList< vpHistogramValey > & valey )

Deprecated:: This method is deprecated. You should use getValey(std::list<vpHistogramValey> &) instead.

Build a list of all histogram valey. This valey list is gray level sorted from 0 to 255. That mean that the first valey has a gray level less than the second one, etc.

Parameters

valey : List of valey.

Returns: The number of valey in the histogram.

See also: sort()

Definition at line 1003 of file vpHistogram.cpp.

References vpList< type >::addRight(), vpList< type >::empty(), vpList< type >::front(), vpList< type >::kill(), vpImageException::notInitializedError, vpHistogramValey::set(), and vpERROR_TRACE.

unsigned* vpHistogram::getValues ( )

inline

Get the histogram values.

Returns: A pointer to the array of histogram values. The size of this array is given by getSize().

vpImage<unsigned char> I; // A gray level image
vpHistogram h; 
h.calculate(I); // Histogram of the gray level image
// Print the histogram values
unsigned char *values = h.getValues();
for (int i=0; i < h.getSize(); i ++)
  printf("%d: %d\n", i, values[i]);

See also: getSize()

Definition at line 278 of file vpHistogram.h.

unsigned vpHistogram::operator() ( const unsigned char level ) const

inline

Return the number of pixels having the gray level.

Parameters

level : Gray level in the histogram.

Returns: Number of pixels having the gray level.

vpImage<unsigned char> I; // A gray level image
vpHistogram h; 
h.calculate(I); // Histogram of the gray level image
// Print the histogram values
for (int i=0; i < h.getSize(); i ++)
  printf("%d: %d\n", i, h(i));

Definition at line 170 of file vpHistogram.h.

vpHistogram & vpHistogram::operator= ( const vpHistogram & h )

Copy operator.

Parameters

h	: Histogram to copy.

vpImage<unsigned char> I;
vpHistogram h(I);
vpHistogram hcopied = h;

Definition at line 124 of file vpHistogram.cpp.

unsigned vpHistogram::operator[] ( const unsigned char level ) const

inline

Return the number of pixels having the gray level.

Parameters

level : Gray level in the histogram.

Returns: Number of pixels having the gray level.

vpImage<unsigned char> I; // A gray level image
vpHistogram h; 
h.calculate(I); // Histogram of the gray level image
// Print the histogram values
for (int i=0; i < h.getSize(); i ++)
  printf("%d: %d\n", i, h[i]);

Definition at line 145 of file vpHistogram.h.

void vpHistogram::set	(	const unsigned char	level,
		unsigned int	value
	)

inline

Set the number of pixels having the gray level.

Parameters

level	: Gray level in the histogram. Level is in [0:255]
value	: Number of pixels having the gray level.

vpHistogram h; 
// Set histogram values
for (int i=0; i < h.getSize(); i ++)
  h.set(i, i*2); // for each level i, set a value of 2*i

Definition at line 216 of file vpHistogram.h.

void vpHistogram::smooth ( const unsigned int fsize = 3 )

Smoothes the histogram and returns it.

A simple average scheme is used where each value $h(i)$ in the histogram is replaced by the average of itself and the neighbours.

$h(i) = \sum_{j=i-\frac{fsize}{2}}^{i+\frac{fsize}{2}} h(j)$

Parameters

fsize : Filter size. Corresponds to the number of values around each point used to compute the mean value.

Returns: Smoothed histogram.

Exceptions

vpImageException::notInitializedError : Histogram array not initialsed. Means that the histogram was not calculated before.

See also: calculate()

Examples:: histogram.cpp.

Definition at line 193 of file vpHistogram.cpp.

References vpImageException::notInitializedError, and vpERROR_TRACE.

unsigned vpHistogram::sort ( std::list< vpHistogramPeak > & peaks )

Sort a list of histogram peaks from highest to the lowest.

Parameters

peaks : List of histogram peaks.

Returns: The number of peaks in the histogram.

See also: getPeak()

Examples:: histogram.cpp.

Definition at line 848 of file vpHistogram.cpp.

Referenced by getPeaks().

unsigned vpHistogram::sort ( vpList< vpHistogramPeak > & peaks )

Deprecated:: This method is deprecated. You should use sort(std::list<vpHistogramPeak> &) instead.

Sort a list of histogram peaks from highest to the lowest.

Parameters

peaks : List of histogram peaks.

Returns: The number of peaks in the histogram.

See also: getPeak()

Definition at line 1074 of file vpHistogram.cpp.

References vpList< type >::addLeft(), vpList< type >::addRight(), vpList< type >::empty(), vpList< type >::front(), vpHistogramPeak::getValue(), vpList< type >::kill(), vpList< type >::next(), vpList< type >::nextOutside(), vpList< type >::outside(), and vpList< type >::value().

bool vpHistogram::write ( const std::string & filename )

Write the histogram values in a file.

In the file, on each line you will find first the gray level and than the number of pixels which have this gray level.

Parameters

filename : File name to write with histogram values.

Returns: true if the file could be written, false otherwise.

Examples:: histogram.cpp.

Definition at line 873 of file vpHistogram.cpp.

bool vpHistogram::write ( const char * filename )

Write the histogram values in a file.

In the file, on each line you will find first the gray level and than the number of pixels which have this gray level.

Parameters

filename : File name to write with histogram values.

Returns: true if the file could be written, false otherwise.

Definition at line 891 of file vpHistogram.cpp.

Public Member Functions

Deprecated functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation