Into

Modules

Documentation

classPiiMultiVariableHistogram

#include <PiiMultiVariableHistogram.h>

An operation that builds histograms out of correlated variables.

Inherits PiiDefaultOperation

Description

The most typical use of this operation may be in creating a 2-D or 3-D color histogram out of color channels, but the operation can create multi-dimensional distributions out of any data quantized to integers. Assume you have separated the color channels of a 2-by-2 RGB image like this: 

  R     G     B
+---+ +---+ +---+
|0 1| |1 0| |3 2|
|2 3| |2 3| |0 1|
+---+ +---+ +---+

Assume also that the maximum value for each channel is 3, i.e. there are 4 distinct values. The length of the resulting histogram in JointDistribution would be 4 * 4 * 4 = 64. The indices of the three-dimensional colors in the resulting histogram would be (from upper left corner) 0 + 4 * 1 + 4 * 4 * 3 = 52, 1 + 4 * 0 + 4 * 4 * 2 = 32 etc. In MarginalDistributions mode the histograms are calculated for each cannel separately, and concatenated together. In the example above, the length of the histogram would be 4 + 4 + 4 = 12.

Inputs

matrixXinput matrices. X is a zero-based index, and its maximum value depends on the number of levels. Any real-valued matrix will be accepted. For maximum performance, input integer matrices.

Outputs

histograma multi-dimensional histogram folded into a one-dimensional row matrix, or multiple one-dimensional histograms concatenated into a row matrix (PiiMatrix<int>).

Properties

DistributionType
distributionType

The type of distribution to create.

QVariantList
levels

A quantization level for each dimension.

bool
normalized

Output normalization.

QVariantList
scales

Scaling factors for each dimension.

Public types

enum
DistributionType
{ JointDistribution, MarginalDistributions }

Output distribution types.

Constructors and destructor

PiiMultiVariableHistogram
( )
~PiiMultiVariableHistogram
( )

Public member functions

DistributionType
distributionType
( )
QVariantList
levels
( )
bool
normalized
( )
QVariantList
scales
( )
void
setDistributionType
( )
void
setLevels
(
  • const QVariantList & levels
)
void
setNormalized
(
  • bool normalize
)
void
setScales
(
  • const QVariantList & scales
)

Protected member functions

virtual void
check
(
  • bool reset
)

Checks the operation for execution.

virtual void
process
( )

Executes one round of processing.

Property details

  • DistributionType distributionType

    [read, write]

    The type of distribution to create.

    The default is JointDistribution.

  • QVariantList levels

    [read, write]

    A quantization level for each dimension.

    In the example above, this list would have been created like this: 

     histogram->setProperty("levels", QVariantList() << 4 << 4 << 4);

    The minimum number of levels is one. There can be at most eight levels. In JointDistribution mode, the product of the levels can be at most 2^24 (16M), which is already too much for practical use. In theory, this allows one to create a three-dimensional color histogram out of three 8-bit color channels. In MarginalDistributions mode, the same limit holds for the sum of levels.

  • bool normalized

    [read, write]

    Output normalization.

    If set to true output histograms will be normalized.

  • QVariantList scales

    [read, write]

    Scaling factors for each dimension.

    Each element in the input matrices will be multiplied by the corresponding scale factor before placing into the histogram. This makes it possible to quantize the input at the same time. Set this property to an empty list to disable scaling.

    If the RGB images in the example above had 256 levels, one should scale the input channels down: 

     histogram->setProperty("scales", QVariantList() << 4.0/256 << 4.0/256 << 4.0/256);

Enumeration details

  • enum DistributionType

    Output distribution types.

    • JointDistribution - a joint distribution will be created. The length of the histogram will be , where represents the ith entry in the levels list. Note that one should use a low number of levels to avoid exhaustive memory usage and an mostly empty histograms.

    • MarginalDistributions - marginal distributions will be created for each input and concatenated together. The length of the histogram will be .

Function details

  • PiiMultiVariableHistogram

    ()

  • ~PiiMultiVariableHistogram

    ()

  • DistributionType distributionType

    ()

  • QVariantList levels

    ()

  • bool normalized

    ()

  • QVariantList scales

    ()

  • void setDistributionType

    ( )

  • void setLevels

    (
    • const QVariantList & levels
    )

  • void setNormalized

    (
    • bool normalize
    )

  • void setScales

    (
    • const QVariantList & scales
    )

  • virtual void check

    (
    • bool reset
    )
    [protected, virtual]

    Checks the operation for execution.

    This function creates a suitable flow controller by calling createFlowController(). It then sets the flow controller to the active processor and sets the processor as the input controller for all inputs.

    If you change socket groupings in your overridden implementation, please call PiiDefaultOperation::check() after that. Otherwise, your new groupings will not be in effect.

    Reimplemented from PiiDefaultOperation.

  • virtual void process

    ()
    [protected, virtual]

    Executes one round of processing.

    This function is invoked by the processor if the necessary preconditions for a new processing round are met. This function does all the necessary calculations to create output objects and sends them to output sockets.

    Calls to process(), syncEvent(), and setProperty() are synchronized and cannot occur simultaneously. PiiDefaultOperation ensures this by locking processLock() for reading before calling process().

    Note: With time-consuming operations, one should occasionally check that the operation hasn't been interrupted, i.e. that state() returns Running.

    Exceptions
    PiiExecutionException

    whenever an unrecoverable error occurs during a processing round, the operation is interrupted, or finishes execution due to end of input data.

    Reimplemented from PiiDefaultOperation.

Notes (0)

Add a note

Not a single note added yet. Be the first, add yours.