Magnum::DebugTools::CompareImageFile class
#include <Magnum/DebugTools/CompareImage.h>

Image file comparator for Corrade::TestSuite.

Similar to CompareImage, but comparing images loaded from files. Example usage:

CORRADE_COMPARE_WITH("actual.png", "expected.png",
    (DebugTools::CompareImageFile{1.5f, 0.01f}));

By default, the comparator uses a local instance of Corrade::PluginManager::Manager to load image files. This might be problematic if the code being tested also uses a plugin manager instance or if you need to use a different plugin directory, for example. For such cases it's possible to supply an external instance:

PluginManager::Manager<Trade::AbstractImporter> manager;

CORRADE_COMPARE_WITH("actual.png", "expected.png",
    (DebugTools::CompareImageFile{manager, 1.5f, 0.01f}));

The comparator uses the AnyImageImporter plugin, which in turn delegates the import to some importer plugin matching the image format(s). Both the AnyImageImporter and the concrete importer plugin(s) need to be available, otherwise the comparison fails. An alternative way is manually skipping the test if the plugins are not available:

PluginManager::Manager<Trade::AbstractImporter> manager;
if(manager.loadState("AnyImageImporter") == PluginManager::LoadState::NotFound ||
   manager.loadState("PngImporter") == PluginManager::LoadState::NotFound)
    CORRADE_SKIP("AnyImageImporter/PngImporter not found, can't compare.");

CORRADE_COMPARE_WITH("actual.png", "expected.png",
    (DebugTools::CompareImageFile{manager, 1.5f, 0.01f}));

See also CompareImageToFile and CompareFileToImage for comparing in-memory images to image files and vice versa.

Saving files for failed comparisons

The comparator supports the --save-diagnostic option — if the comparison fails, it saves actual image data to given directory with a filename and format matching the expected file, using the AnyImageConverter plugin. For this to work, both AnyImageConverter and the concrete converter plugin need to be available. You can use it to perform a manual data comparison with an external tool or for example to quickly update expected test data — point the option to the directory with expected test files and let the test overwrite them with actual results. The CompareImageToFile variant supports the same; the CompareImage / CompareFileToImage variants don't since the comparison is done against in-memory data and so producing a file isn't that helpful as in the other two variants.

Constructors, destructors, conversion operators

CompareImageFile(Float maxThreshold, Float meanThreshold) explicit: Constructor.
CompareImageFile(PluginManager::Manager<Trade::AbstractImporter>& importerManager, Float maxThreshold, Float meanThreshold) explicit: Construct with an explicit plugin manager instance.
CompareImageFile(PluginManager::Manager<Trade::AbstractImporter>& importerManager) explicit: Construct with an explicit plugin manager instance and implicit thresholds.
CompareImageFile(PluginManager::Manager<Trade::AbstractImporter>& importerManager, PluginManager::Manager<Trade::AbstractImageConverter>& converterManager, Float maxThreshold, Float meanThreshold) explicit: Construct with an explicit importer and converter plugin manager instance.
CompareImageFile(PluginManager::Manager<Trade::AbstractImporter>& importerManager, PluginManager::Manager<Trade::AbstractImageConverter>& imageConverterManager) explicit new in Git master: Construct with an explicit importer and converter plugin manager instance and implicit thresholds.
CompareImageFile() explicit: Construct with implicit thresholds.

Function documentation

Magnum::DebugTools::CompareImageFile::CompareImageFile(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::CompareImageFile::CompareImageFile(PluginManager::Manager<Trade::AbstractImporter>& importerManager, Float maxThreshold, Float meanThreshold) explicit

Construct with an explicit plugin manager instance.

Parameters
importerManager	Image importer plugin manager instance
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::CompareImageFile::CompareImageFile(PluginManager::Manager<Trade::AbstractImporter>& importerManager) explicit

Construct with an explicit plugin manager instance and implicit thresholds.

Equivalent to calling CompareImageFile(PluginManager::Manager<Trade::AbstractImporter>&, Float, Float) with zero values.

Magnum::DebugTools::CompareImageFile::CompareImageFile(PluginManager::Manager<Trade::AbstractImporter>& importerManager, PluginManager::Manager<Trade::AbstractImageConverter>& converterManager, Float maxThreshold, Float meanThreshold) explicit

Construct with an explicit importer and converter plugin manager instance.

Parameters
importerManager	Image importer plugin manager instance
converterManager	Image converter plugin manager instance
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

This variant is rarely usable outside of testing environment, as the converterManager is only ever used when saving diagnostic for failed * comparison when the --save-diagnostic command-line option is specified.

Magnum::DebugTools::CompareImageFile::CompareImageFile(PluginManager::Manager<Trade::AbstractImporter>& importerManager, PluginManager::Manager<Trade::AbstractImageConverter>& imageConverterManager) explicit new in Git master

Construct with an explicit importer and converter plugin manager instance and implicit thresholds.

Equivalent to calling CompareImageFile(PluginManager::Manager<Trade::AbstractImporter>&, PluginManager::Manager<Trade::AbstractImageConverter>&, Float, Float) with zero values.

Magnum::DebugTools::CompareImageFile::CompareImageFile() explicit

Construct with implicit thresholds.

Equivalent to calling CompareImageFile(Float, Float) with zero values.

Magnum::DebugTools::CompareImageFile class #include <Magnum/DebugTools/CompareImage.h>