Histograms module
#include "diplib/histogram.h"
dip::Histogram class

Computes and holds histograms.

Reference

A histogram is computed by the constructor. A default-constructed Histogram is empty and can only be assigned to.

A histogram can have multiple dimensions. In general, a scalar image will yield a classical one-dimensional histogram, and a tensor image will yield a multi-dimensional histogram, with one dimension per tensor element. The first tensor element determines the index along the first dimension, the second tensor element that along the second dimension, etc.

To facilitate usage for one-dimensional histograms, all getter functions that return a value for a given dimension, default to dimension 0, so can be called without arguments.

Constructors, destructors, assignment and conversion operators

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.
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.
Histogram(dip::Histogram::ConfigurationArray configuration) explicit: An empty histogram with the given configuration. Histogram bins are initialized to 0.
Histogram(dip::Histogram::Configuration const& configuration) explicit: An empty histogram with the given configuration. Histogram bins are initialized to 0.
Histogram(dip::Histogram::CountType const* data, dip::Histogram::Configuration const& configuration): Create a 1D histogram around existing data. No ownership is transferred.
Histogram() defaulted: The default-initialized histogram is empty and can only be assigned to.

Classes

struct Configuration: Configuration information for how the histogram is computed.

Aliases

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.

Functions

static auto OptimalConfiguration() -> dip::Histogram::Configuration: Creates a dip::Histogram::Configuration that uses the optimal bin size according to the Freedman–Diaconis rule.
static auto OptimalConfigurationWithFullRange() -> dip::Histogram::Configuration: 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.
auto IsInitialized() const -> bool: Returns false for a default-initialized histogram.
auto Copy() const -> dip::Histogram: Deep copy, returns a copy of this with its own data segment.
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.
auto Dimensionality() const -> dip::uint: Returns the histogram dimensionality.
auto Bins(dip::uint dim = 0) const -> dip::uint: Returns the number of bins along dimension dim
auto BinSize(dip::uint dim = 0) const -> dip::dfloat: Returns the size of the bins along dimension dim
auto LowerBound(dip::uint dim = 0) const -> dip::dfloat: Returns the lower bound of the histogram for dimension dim
auto UpperBound(dip::uint dim = 0) const -> dip::dfloat: Returns the upper bound of the histogram for dimension dim
auto BinBoundaries(dip::uint dim = 0) const -> dip::FloatArray: Returns the bin boundaries along dimension dim (Bins(dim)+1 values).
auto BinCenters(dip::uint dim = 0) const -> dip::FloatArray: Returns the bin centers along dimension dim
auto BinCenter(dip::uint bin, dip::uint dim = 0) const -> dip::dfloat: Returns the bin center for the given bin along dimension dim
auto Bin(dip::dfloat value) const -> dip::uint: Gets the bin for value in a 1D histogram
auto Bin(dip::dfloat x_value, dip::dfloat y_value) const -> dip::UnsignedArray: Gets the bin for {x_value, y_value} in a 2D histogram
auto Bin(dip::dfloat x_value, dip::dfloat y_value, dip::dfloat z_value) const -> dip::UnsignedArray: Gets the bin for {x_value, y_value, z_value} in a 3D histogram
auto Bin(dip::FloatArray const& value) const -> dip::UnsignedArray: Gets the bin for value in an nD histogram
auto At(dip::uint x) const -> dip::Histogram::CountType: Get the value at the given bin in a 1D histogram
auto At(dip::uint x, dip::uint y) const -> dip::Histogram::CountType: Get the value at the given bin in a 2D histogram
auto At(dip::uint x, dip::uint y, dip::uint z) const -> dip::Histogram::CountType: Get the value at the given bin in a 3D histogram
auto At(dip::UnsignedArray const& bin) const -> dip::Histogram::CountType: Get the value at the given bin
auto GetImage() const -> dip::Image const&: Get the image that holds the bin counts. The image is always scalar and of type dip::DT_COUNT.
auto begin() const -> dip::ConstImageIterator: Returns an iterator to the first bin
static auto end() -> dip::ConstImageIterator: Returns an end iterator
auto Origin() const -> dip::Histogram::CountType const*: Returns a pointer to the first bin
auto Count() const -> dip::uint: Returns the total number of elements in the histogram (sum of bins)
auto Cumulative() -> dip::Histogram&: Converts the histogram to a cumulative histogram. For each bin, it will contain the sum of that bin with all the previous ones.
auto GetMarginal(dip::uint dim) const -> dip::Histogram: Returns the marginal histogram for dimension dim.
auto Smooth(dip::FloatArray sigma) -> dip::Histogram&: Smooths the histogram, using Gaussian smoothing with parameters sigma.

Operators

auto operator+=(dip::Histogram const& other) -> dip::Histogram&: Adds a histogram to *this. other must have identical properties.
auto operator-=(dip::Histogram const& other) -> dip::Histogram&: Subtracts a histogram from *this, using saturated subtraction. other must have identical properties.

Function documentation

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::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.

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.

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::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.

Histograms module#include "diplib/histogram.h" dip::Histogram class

Contents