#include "diplib/histogram.h"
dip::Histogram::Configuration struct

Configuration information for how the histogram is computed.

Contents

Constructors exist to set different subsets of the configuration; write upper bound and bin size as a floating point number so the right constructor can be selected (they differ in the location of the integer value). For example, note the difference between the following constructor calls, where 10 indicates 10 bins, 100.0 indicates the upper bound, and 1.0 indicates the bin size:

dip::Histogram::Configuration conf1( 0.0, 100.0, 1.0 );
dip::Histogram::Configuration conf1( 0.0, 100.0, 10 );
dip::Histogram::Configuration conf2( 0.0, 10, 1.0 );

An additional constructor takes a dip::DataType, and selects appropriate values for an image of the given data type; see dip::Histogram::Configuration::Configuration.

The functions dip::Histogram::OptimalConfiguration and dip::Histogram::OptimalConfigurationWithFullRange create configurations that are expected to be robust for arbitrary data. They choose the bin size based on the Freedman–Diaconis rule. The former chooses histogram bounds to exclude only extreme outliers, the latter always includes the full range. Note that including the full range can potentially lead to an extremely large histogram.

Here are the rules followed to complete the configuration given:

  • Any illegal values in the configuration will silently be replaced with the default values.

  • For integer images, the bin size and bounds will be forced to integer values.

  • For integer images, if mode == Mode::COMPUTE_BINSIZE, the upper bound will be adjusted so that a whole number of integer-sized bins fit within the bounds.

  • If mode == Mode::COMPUTE_BINS, the bin size is adjusted to that a whole number of bins fit within the given bounds. Except for integer images, where the bin size must be an integer as well. In this case, the upper bound is adjusted instead.

  • If mode == Mode::COMPUTE_BINS, binSize was set to zero or a negative value, and the input image is of an integer type, then binSize will be computed to be an integer power of two, and such that there are no more than 256 bins in the histogram.

  • For integer images, if the bin centers are not whole numbers, the bounds are shifted down by half to make the bin centers whole numbers. This should not affect the computed histogram, but make the display prettier.

Constructors, destructors, assignment and conversion operators

Configuration() defaulted noexcept
Default-constructed configuration defines 256 bins in the range [0,256].
Configuration(dip::dfloat lowerBound, dip::dfloat upperBound, dip::dfloat binSize)
A constructor takes a lower and upper bounds, and the bin size. The number of bins are computed.
Configuration(dip::dfloat lowerBound, dip::dfloat upperBound, dip::uint nBins = 256)
A constructor takes a lower and upper bounds, and the number of bins. The bin size is computed.
Configuration(dip::dfloat lowerBound, dip::dfloat upperBound, int nBins)
A constructor takes a lower and upper bounds, and the number of bins. The bin size is computed.
Configuration(dip::dfloat lowerBound, dip::uint nBins, dip::dfloat binSize)
A constructor takes a lower bound, the number of bins and the bin size. The upper bound is computed.
Configuration(dip::dfloat lowerBound, int nBins, dip::dfloat binSize)
A constructor takes a lower bound, the number of bins and the bin size. The upper bound is computed.
Configuration(dip::DataType dataType) explicit
A constructor takes an image data type, yielding a default histogram configuration for that data type.

Enums

enum class Mode: uint8{ COMPUTE_BINSIZE, COMPUTE_BINS, COMPUTE_LOWER, COMPUTE_UPPER, ESTIMATE_BINSIZE, ESTIMATE_BINSIZE_AND_LIMITS }
How to complete the configuration

Functions

auto IsOutOfRange(dip::dfloat value) const -> bool
Returns true if the value should not be included in the histogram.
auto FindBin(dip::dfloat value) const -> dip::sint
Returns the bin that the value belongs in, assuming !IsOutOfRange(value).

Variables

dip::dfloat lowerBound
Lower bound for this dimension, corresponds to the lower bound of the first bin.
dip::dfloat upperBound
Upper bound for this dimension, corresponds to the upper bound of the last bin.
dip::uint nBins
Number of bins for this dimension.
dip::dfloat binSize
Size of each bin for this dimension.
dip::Histogram::Configuration::Mode mode
The given value is ignored and replaced by the computed value.
bool lowerIsPercentile
If set, lowerBound is replaced by the given percentile pixel value.
bool upperIsPercentile
If set, upperBound is replaced by the given percentile pixel value.
bool excludeOutOfBoundValues
If set, pixels outside of the histogram bounds are not counted.

Enum documentation

enum class Mode: uint8

How to complete the configuration

Enumerators
COMPUTE_BINSIZE = 0 Compute binSize from the other three values
COMPUTE_BINS = 1 Compute nBins from the other three values
COMPUTE_LOWER = 2 Compute lowerBound from the other three values
COMPUTE_UPPER = 3 Compute upperBound from the other three values
ESTIMATE_BINSIZE = 4 Choose binSize using the Freedman–Diaconis rule, then compute nBins.
ESTIMATE_BINSIZE_AND_LIMITS = 5 Like ESTIMATE_BINSIZE, but also determines the lower and upper limits

Function documentation

Configuration(dip::DataType dataType) explicit

A constructor takes an image data type, yielding a default histogram configuration for that data type.

  • For 8-bit images, the histogram has 256 bins, one for each possible input value.
  • For other integer-valued images, the histogram has up to 256 bins, stretching from the lowest value in the image to the highest, and with bin size a power of two. This is the simplest way of correctly handling data from 10-bit, 12-bit and 16-bit sensors that can put data in the lower or the upper bits of the 16-bit words, and will handle other integer data correctly as well.
  • For floating-point images, the histogram always has 256 bins, stretching from the lowest value in the image to the highest.