Magnum::DebugTools::CompareImage class

Image comparator.

Contents

To be used with Corrade::TestSuite. Basic use is really simple:

void ProcessingTest::process() {
    Image2D actual = doProcessing();
    Image2D expected = loadExpectedImage();

    CORRADE_COMPARE_WITH(actual, expected,
        (DebugTools::CompareImage{170.0f, 96.0f}));
}

Based on actual images used, in case of commparison failure the comparator can give for example the following result:

Starting ProcessingTest with 1 test cases...
  FAIL [1] process() at …/debugtools-compareimage.cpp on line 77
        Images actual and expected have max delta above threshold, actual 189
        but at most 170 expected. Mean delta 13.5776 is below threshold 96.
        Delta image:
          |                                |
          |                                |
          |         ~8070DNMN8$ZD7         |
          |       ?I0:   :++~.  .I0Z       |
          |      7I   ?$D8ZZ0DZ8,  +?      |
          |     ~+   +I        ,7NZZ$      |
          |     :    ~                     |
          |     .    .                     |
          |     ,    :                     |
          |     ~.   +.         +ID8?.     |
          |      ?.  .Z0:     +0I  :7      |
          |      .$$.  ~D8$Z0DZ.  =Z+      |
          |        =8$DI=,. .:+ZDI$        |
          |           :70DNMND$+.          |
          |                                |
          |                                |
        Top 10 out of 66 pixels above max/mean threshold:
          [16,5] #000000ff, expected #fcfcfcff (Δ = 189)
          [16,27] #fbfbfbff, expected #000000ff (Δ = 188.25)
          [15,27] #f2f2f2ff, expected #000000ff (Δ = 181.5)
          [17,5] #000000ff, expected #f1f1f1ff (Δ = 180.75)
          [15,5] #000000ff, expected #efefefff (Δ = 179.25)
          [17,27] #eeeeeeff, expected #000000ff (Δ = 178.5)
          [22,20] #000000ff, expected #e7e7e7ff (Δ = 173.25)
          [18,23] #060606ff, expected #eaeaeaff (Δ = 171)
          [18,9] #e5e5e5ff, expected #040404ff (Δ = 168.75)
          [21,26] #efefefff, expected #0f0f0fff (Δ = 168)
Finished ProcessingTest with 1 errors out of 1 checks.

Supports the following formats:

PixelFormat::RGBA16F and other half-float formats are not supported at the moment. Implementation-specific pixel formats can't be supported.

Supports all PixelStorage parameters. The images don't need to have the same pixel storage parameters, meaning you are able to compare different subimages of a larger image as long as they have the same size.

The comparator first compares both images to have the same pixel format/type combination and size. Each pixel is then first converted to Float vector of corresponding channel count and then the per-pixel delta is calculated as simple sum of per-channel deltas (where $ \boldsymbol{a} $ is the actual pixel value, $ \boldsymbol{e} $ expected pixel value and $ c $ is channel count), with max and mean delta being taken over the whole picture.

\[ \Delta_{\boldsymbol{p}} = \sum\limits_{i=1}^c \dfrac{a_i - e_i}{c} \]

The two parameters passed to the CompareImage(Float, Float) constructor are max and mean delta threshold. If the calculated values are above these threshold, the comparison fails. In case of comparison failure the diagnostic output contains calculated max/meanvalues, delta image visualization and a list of top deltas. The delta image is an ASCII-art representation of the image difference with each block being a maximum of pixel deltas in some area, printed as characters of different perceived brightness. Blocks with delta over the max threshold are colored red, blocks with delta over the mean threshold are colored yellow. The delta list contains X,Y pixel position (with origin at bottom left), actual and expected pixel value and calculated delta.

Constructors, destructors, conversion operators

CompareImage(Float maxThreshold, Float meanThreshold) explicit
Constructor.
CompareImage() explicit
Implicit constructor.

Function documentation

Magnum::DebugTools::CompareImage::CompareImage(Float maxThreshold, Float meanThreshold) explicit

Constructor.

Parameters
maxThreshold Max threshold. If any pixel has delta above this value, this comparison fails
meanThreshold Mean threshold. If mean delta over all pixels is above this value, the comparison fails

Magnum::DebugTools::CompareImage::CompareImage() explicit

Implicit constructor.

Equivalent to calling the above with zero values.