Visual Servoing Platform  version 3.5.0 under development (2022-02-15)
vpHistogram Class Reference

#include <visp3/core/vpHistogram.h>

Public Member Functions

 vpHistogram ()
 
 vpHistogram (const vpHistogram &h)
 
 vpHistogram (const vpImage< unsigned char > &I)
 
virtual ~vpHistogram ()
 
vpHistogramoperator= (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, unsigned int nbins=256, unsigned int nbThreads=1)
 
void display (const vpImage< unsigned char > &I, const vpColor &color=vpColor::white, unsigned int thickness=2, unsigned int maxValue_=0)
 
void smooth (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 () const
 
unsigned * getValues ()
 

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:

...
unsigned char dist = 60;
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:

...
unsigned char dist = 60;
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
h.getValey(peak1, peak2, valey);
unsigned char threshold; // Position of the valey between the two peaks
threshold = valey.getLevel();
Examples:
histogram.cpp, and testHistogram.cpp.

Definition at line 112 of file vpHistogram.h.

Constructor & Destructor Documentation

◆ vpHistogram() [1/3]

vpHistogram::vpHistogram ( )

Defaut constructor for a gray level histogram.

Definition at line 151 of file vpHistogram.cpp.

◆ vpHistogram() [2/3]

vpHistogram::vpHistogram ( const vpHistogram h)

Copy constructor of a gray level histogram.

Definition at line 156 of file vpHistogram.cpp.

◆ vpHistogram() [3/3]

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

Calculates the histrogram from a gray level image.

Parameters
I: Gray level image.
See also
calculate()

Definition at line 169 of file vpHistogram.cpp.

References calculate().

◆ ~vpHistogram()

vpHistogram::~vpHistogram ( )
virtual

Destructor.

Definition at line 179 of file vpHistogram.cpp.

Member Function Documentation

◆ calculate()

void vpHistogram::calculate ( const vpImage< unsigned char > &  I,
unsigned int  nbins = 256,
unsigned int  nbThreads = 1 
)

Calculate the histogram from a gray level image.

Parameters
I: Gray level image.
nbins: Number of bins to compute the histogram.
nbThreads: Number of threads to use for the computation.
Examples:
histogram.cpp, and testHistogram.cpp.

Definition at line 238 of file vpHistogram.cpp.

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

Referenced by vp::equalizeHistogram(), and vpHistogram().

◆ display()

void vpHistogram::display ( const vpImage< unsigned char > &  I,
const vpColor color = vpColor::white,
unsigned int  thickness = 2,
unsigned int  maxValue_ = 0 
)

Display the histogram distribution in an image, the minimal image size is 36x36 px.

Parameters
I: Image with the histogram distribution displayed.
color: Color used for the display.
thickness: Thickness of the line.
maxValue_: Maximum value in the histogram, if 0 it will be computed from the current histogram. Useful to plot a 3 channels histogram for a RGB image for example to keep a coherent vertical scale between the channels.

Definition at line 352 of file vpHistogram.cpp.

References vpDisplay::displayLine(), vpException::divideByZeroError, vpImage< Type >::getHeight(), and vpImage< Type >::getWidth().

◆ get()

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
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 202 of file vpHistogram.h.

References vpException::dimensionError.

◆ getPeaks() [1/3]

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 449 of file vpHistogram.cpp.

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

Referenced by getPeaks(), and getValey().

◆ getPeaks() [2/3]

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 527 of file vpHistogram.cpp.

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

◆ getPeaks() [3/3]

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 579 of file vpHistogram.cpp.

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

◆ getSize()

unsigned vpHistogram::getSize ( ) const
inline

Get the histogram size.

Returns
The size of the histogram, or the image maximum gray levels numbers.
See also
getValues()
Examples:
testHistogram.cpp.

Definition at line 267 of file vpHistogram.h.

◆ getValey() [1/3]

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 732 of file vpHistogram.cpp.

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

◆ getValey() [2/3]

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 801 of file vpHistogram.cpp.

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

◆ getValey() [3/3]

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 865 of file vpHistogram.cpp.

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

◆ getValues()

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
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 290 of file vpHistogram.h.

◆ operator()()

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
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 172 of file vpHistogram.h.

References vpException::dimensionError.

◆ operator=()

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

Copy operator.

Parameters
h: Histogram to copy.

Definition at line 202 of file vpHistogram.cpp.

◆ operator[]()

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
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 142 of file vpHistogram.h.

References vpException::dimensionError.

◆ set()

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.
// 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 230 of file vpHistogram.h.

References vpException::dimensionError, and vpColor::white.

◆ smooth()

void vpHistogram::smooth ( 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 409 of file vpHistogram.cpp.

References vpImageException::notInitializedError, and vpERROR_TRACE.

◆ sort()

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 1028 of file vpHistogram.cpp.

Referenced by getPeaks().

◆ write() [1/2]

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 1052 of file vpHistogram.cpp.

◆ write() [2/2]

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 1066 of file vpHistogram.cpp.