This is a snapshot of a work-in-progress documentation theme. If you feel lost, miss something, or want to see the original Doxygen docs instead, head over to the archived version of this documentation page.

Magnum::DebugTools::CompareImage class

Image comparator.

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:

In OpenGL ES 2.0 and WebGL 1.0, PixelFormat::Luminance and PixelFormat::LuminanceAlpha are also accepted in place of PixelFormat::Red and PixelFormat::RG.

Supports all PixelStorage parameters except non-default PixelStorage::swapBytes() values. 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 LaTeX Math $ \boldsymbol{a} $ is the actual pixel value, LaTeX Math $ \boldsymbol{e} $ expected pixel value and LaTeX Math $ c $ is channel count), with max and mean delta being taken over the whole picture.

LaTeX Math \[ \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
CompareImage() explicit
Implicit constructor.

Function documentation

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


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.