Histograms module
#include "diplib/histogram.h"

dip::Histogram class

using CountType = dip::uint64

Type of histogram bins. See dip::DT_COUNT.

using ConfigurationArray = dip::DimensionArray

An array of dip::Histogram::Configuration objects, one per histogram dimension.

Histogram( dip::Image const& input, dip::Image const& mask = {}, dip::Histogram::ConfigurationArray configuration = {}) explicit

The constructor takes an image, an optional mask, and configuration options for each histogram dimension.

configuration should have as many elements as tensor elements in input. If configuration has only one element, it will be used for all histogram dimensions. If it is an empty array, appropriate configuration values for input are chosen based on its data type (see dip::Histogram::Configuration::Configuration).

Histogram( dip::Image const& input, dip::Image const& mask, dip::Histogram::Configuration configuration)

This version of the constructor is identical to the previous one, but with a single configuration parameter instead of an array.

Histogram( dip::Image const& input1, dip::Image const& input2, dip::Image const& mask, dip::Histogram::ConfigurationArray configuration = {})

A version of the constructor that takes two scalar input images, and constructs their joint histogram (a 2D histogram, equal to the one obtained if the two images were the two channels of a tensor image).

Histogram( dip::Measurement::IteratorFeature const& featureValues, dip::Histogram::ConfigurationArray configuration = {}) explicit

The constructor takes an IteratorFeature of a dip::Measurement object, and configuration options for each histogram dimension.

configuration should have as many elements as values in featureValues. If configuration has only one element, it will be used for all histogram dimensions. In the default configuration, the histogram will stretch from lowest to highest value, in 100 bins.

Histogram( dip::Histogram::ConfigurationArray configuration) explicit

An empty histogram with the given configuration. Histogram bins are initialized to 0.

The array must not be empty. The histogram will have configuration->size() dimensions. configuration[ii].lowerIsPercentile and configuration[ii].upperIsPercentile must all be false (since there is no way of determining these percentiles).

The GetImage method returns a const reference to the histogram bins (in the form of an image), but it is possible to modify the values in the bins (modify the pixel values of this image).

Histogram( dip::Histogram::Configuration const& configuration) explicit

An empty histogram with the given configuration. Histogram bins are initialized to 0.

The histogram will have one dimension. configuration.lowerIsPercentile and configuration.upperIsPercentile must both be false (since there is no way of determining these percentiles).

The GetImage method returns a const reference to the histogram bins (in the form of an image), but it is possible to modify the values in the bins (modify the pixel values of this image).

Histogram( dip::Histogram::CountType const* data, dip::Histogram::Configuration const& configuration)

Create a 1D histogram around existing data. No ownership is transferred.

data is a raw pointer to the data that will be encapsulated by the output histogram. Data must be contiguous and of type dip::Histogram::CountType. configuration determines how many bins are pointed to by data.

Even though the data pointer is declared const here, it is possible to obtain a non-const pointer to the data later.

Histogram( ) defaulted

The default-initialized histogram is empty and can only be assigned to.

static dip::Histogram::Configuration OptimalConfiguration( )

Creates a dip::Histogram::Configuration that uses the optimal bin size according to the Freedman–Diaconis rule.

The Freedman–Diaconis rule sets the bin size to , where IQR is the interquartile range (the distance from the lower to the upper quartile), and is the number of samples over which the histogram will be computed.

The histogram limits are chosen to avoid extremely large histograms, by ignoring values 50 IQRs below the lower quartile or above the upper quartile.

static dip::Histogram::Configuration OptimalConfigurationWithFullRange( )

Like dip::Histogram::OptimalConfiguration, but includes the full data range (min to max); note that this can potentially lead to extremely large histograms.

void swap( dip::Histogram& other) noexcept

Swaps this and other.

bool IsInitialized( ) const

Returns false for a default-initialized histogram.

dip::Histogram Copy( ) const

Deep copy, returns a copy of this with its own data segment.

When making a copy of a histogram, the data segment is shared:

Histogram second = first;
second.Smooth(); // modifies `first` also!

In contrast, this function returns a deep copy of this, with its own data segment:

Histogram second = first.Copy();
second.Smooth(); // OK

void ReverseLookup( dip::Image const& input, dip::Image& out, dip::BooleanArray excludeOutOfBoundValues = {false})

Performs a reverse histogram lookup, yielding an image “painted” with the bin values.

The bin corresponding to each pixel in the input image is found in the histogram, and this bin’s value is written to output.

input must be similar to the image used to generate the histogram (at least have the same number of tensor elements, which corresponds to the dimensionality of the histogram). The lookup occurs in the same way as when generating the histogram. The excludeOutOfBoundValues parameter for each dimension indicates if an edge bin is found or no bin is found (yielding a 0 output) if the pixel is not represented in the histogram.

output is a scalar image with data type dip::Histogram::CountType, containing the histogram bin values.

This function is particularly interesting when applied to a histogram resulting from clustering algorithms such as dip::KMeansClustering or dip::MinimumVariancePartitioning.

dip::uint Dimensionality( ) const

Returns the histogram dimensionality.

dip::uint Bins( dip::uint dim = 0) const

Returns the number of bins along dimension dim

dip::dfloat BinSize( dip::uint dim = 0) const

Returns the size of the bins along dimension dim

dip::dfloat LowerBound( dip::uint dim = 0) const

Returns the lower bound of the histogram for dimension dim

dip::dfloat UpperBound( dip::uint dim = 0) const

Returns the upper bound of the histogram for dimension dim

dip::FloatArray BinBoundaries( dip::uint dim = 0) const

Returns the bin boundaries along dimension dim (Bins(dim)+1 values).

dip::FloatArray BinCenters( dip::uint dim = 0) const

Returns the bin centers along dimension dim

dip::dfloat BinCenter( dip::uint bin, dip::uint dim = 0) const

Returns the bin center for the given bin along dimension dim

dip::uint Bin( dip::dfloat value) const

Gets the bin for value in a 1D histogram

dip::UnsignedArray Bin( dip::dfloat x_value, dip::dfloat y_value) const

Gets the bin for {x_value, y_value} in a 2D histogram

dip::UnsignedArray Bin( dip::dfloat x_value, dip::dfloat y_value, dip::dfloat z_value) const

Gets the bin for {x_value, y_value, z_value} in a 3D histogram

dip::UnsignedArray Bin( dip::FloatArray const& value) const

Gets the bin for value in an nD histogram

dip::Histogram::CountType At( dip::uint x) const

Get the value at the given bin in a 1D histogram

dip::Histogram::CountType At( dip::uint x, dip::uint y) const

Get the value at the given bin in a 2D histogram

dip::Histogram::CountType At( dip::uint x, dip::uint y, dip::uint z) const

Get the value at the given bin in a 3D histogram

dip::Histogram::CountType At( dip::UnsignedArray const& bin) const

Get the value at the given bin

dip::Image const& GetImage( ) const

Get the image that holds the bin counts. The image is always scalar and of type dip::DT_COUNT.

dip::ConstImageIterator begin( ) const

Returns an iterator to the first bin

static dip::ConstImageIterator end( )

Returns an end iterator

dip::Histogram::CountType const* Origin( ) const

Returns a pointer to the first bin

dip::uint Count( ) const

Returns the total number of elements in the histogram (sum of bins)

dip::Histogram& Cumulative( )

Converts the histogram to a cumulative histogram. For each bin, it will contain the sum of that bin with all the previous ones.

The cumulative histogram has this->Count() as the right-most bin. The Count method applied to the cumulative histogram is meaningless, as are Mean and the other statistics functions.

For a multi-dimensional histogram, the cumulative histogram has bin(i,j,k) equal to the sum of all bins with indices equal or smaller to i, j and k: bin(1..i,1..j,1..k). It is computed through the dip::CumulativeSum function.

dip::Histogram GetMarginal( dip::uint dim) const

Returns the marginal histogram for dimension dim.

The marginal histogram represents the marginal intensity distribution. It is a 1D histogram determined by summing over all dimensions except dim, and is equivalent to the histogram for tensor element dim.

dip::Histogram& Smooth( dip::FloatArray sigma)

Smooths the histogram, using Gaussian smoothing with parameters sigma.

Set a single sigma value, or one value per histogram dimension. The value is in bins, yielding a Gaussian kernel of size 2 * std::ceil( 3 * sigma ) + 1 bins. See dip::GaussFIR for information on the smoothing operation applied. sigma defaults to 1.

The histogram is extended by std::ceil( 3 * sigma ) below and above the original bounds, to prevent the histogram count to change.

dip::Histogram& operator+=( dip::Histogram const& other)

Adds a histogram to *this. other must have identical properties.

Adding multiple histograms together can be useful, for example, when accumulating pixel values from multiple images, or in multiple threads.

dip::Histogram& operator-=( dip::Histogram const& other)

Subtracts a histogram from *this, using saturated subtraction. other must have identical properties.

dip::Histogram dip::operator+( dip::Histogram const& lhs, dip::Histogram const& rhs)

Adds two histograms.

dip::Histogram dip::operator-( dip::Histogram const& lhs, dip::Histogram const& rhs)

Subtracts two histograms.

dip::DataType const dip::DT_COUNT constexpr

Data type of histogram bins. See dip::Histogram::CountType.