Histogram¶

class Histogram(*args, **kwargs)¶

Bases: pybind11_object

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();

Overloaded function.

__init__(self: visp._visp.core.Histogram) -> None

Default constructor for a gray level histogram.

__init__(self: visp._visp.core.Histogram, h: visp._visp.core.Histogram) -> None

Copy constructor of a gray level histogram.

__init__(self: visp._visp.core.Histogram, I: visp._visp.core.ImageGray) -> None

Calculates the histogram from a gray level image.

Note

See calculate()

Parameters:

I: Gray level image.

Methods

`__init__`	Overloaded function.
`calculate`	Calculate the histogram from a gray level image.
`display`	Display the histogram distribution in an image, the minimal image size is 36x36 px.
`equalize`
`get`	Return the number of pixels having the gray level .
`getPeaks`	Overloaded function.
`getSize`	Get the histogram size.
`getTotal`	Get the total number of pixels in the input image.
`getValey`	Overloaded function.
`set`	Set the number of pixels having the gray level .
`smooth`	Smoothes the histogram.
`sort`	Sort a list of histogram peaks from highest to the lowest.
`write`	Overloaded function.

Inherited Methods

Operators

`__doc__`
`__init__`	Overloaded function.
`__module__`

Attributes

`__annotations__`

__init__(*args, **kwargs)¶

Overloaded function.

__init__(self: visp._visp.core.Histogram) -> None

Default constructor for a gray level histogram.

__init__(self: visp._visp.core.Histogram, h: visp._visp.core.Histogram) -> None

Copy constructor of a gray level histogram.

__init__(self: visp._visp.core.Histogram, I: visp._visp.core.ImageGray) -> None

Calculates the histogram from a gray level image.

Note

See calculate()

Parameters:

I: Gray level image.

calculate(self, I: visp._visp.core.ImageGray, nbins: int = 256, nbThreads: int = 1) → None¶

Calculate the histogram from a gray level image.

Parameters:

I: visp._visp.core.ImageGray¶: Gray level image.
nbins: int = 256¶: Number of bins to compute the histogram.
nbThreads: int = 1¶: Number of threads to use for the computation.

display(self: visp._visp.core.Histogram, I: visp._visp.core.ImageGray, color: visp._visp.core.Color = vpColor::white, thickness: int = 2, maxValue_: int = 0) → None¶

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.

equalize(self, I: visp._visp.core.ImageGray, Iout: visp._visp.core.ImageGray) → None¶

get(self, level: int) → int¶

Return the 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));

Parameters:

level: int¶: Gray level in the histogram.

Returns:

Number of pixels having the gray level.

getPeaks(*args, **kwargs)¶

Overloaded function.

getPeaks(self: visp._visp.core.Histogram) -> tuple[int, list[visp._visp.core.HistogramPeak]]

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() .

Note

See sort()

Returns:

A tuple containing:

The number of peaks in the histogram.
peaks: List of peaks.

getPeaks(self: visp._visp.core.Histogram, dist: int, peak1: visp._visp.core.HistogramPeak, peak2: visp._visp.core.HistogramPeak) -> int

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.

getPeaks(self: visp._visp.core.Histogram, dist: int, peakl: visp._visp.core.HistogramPeak, peakr: visp._visp.core.HistogramPeak, valey: visp._visp.core.HistogramValey) -> bool

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.

getSize(self) → int¶

Get the histogram size.

Note

See getValues()

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

getTotal(self) → int¶

Get the total number of pixels in the input image.

Returns:: unsigned int Cumulated number of pixels in the input image.

getValey(*args, **kwargs)¶

Overloaded function.

getValey(self: visp._visp.core.Histogram) -> tuple[int, list[visp._visp.core.HistogramValey]]

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.

Note

See sort()

Returns:

A tuple containing:

The number of valey in the histogram.
valey: List of valey.

getValey(self: visp._visp.core.Histogram, peak1: visp._visp.core.HistogramPeak, peak2: visp._visp.core.HistogramPeak, valey: visp._visp.core.HistogramValey) -> bool

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.

getValey(self: visp._visp.core.Histogram, dist: int, peak: visp._visp.core.HistogramPeak, valeyl: visp._visp.core.HistogramValey, valeyr: visp._visp.core.HistogramValey) -> int

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.

set(self, level: int, value: int) → None¶

Set the 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

Parameters:

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

smooth(self, fsize: int = 3) → None¶

Smoothes the histogram.

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) \]

Note

See calculate()

Parameters:

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

sort(self, peaks: list[visp._visp.core.HistogramPeak]) → tuple[int, list[visp._visp.core.HistogramPeak]]¶

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

Note

See getPeak()

Parameters:

peaks: list[visp._visp.core.HistogramPeak]¶: List of histogram peaks.

Returns:

A tuple containing:

The number of peaks in the histogram.
peaks: List of histogram peaks.

write(*args, **kwargs)¶

Overloaded function.

write(self: visp._visp.core.Histogram, filename: str) -> bool

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.

write(self: visp._visp.core.Histogram, filename: str) -> bool

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.