Perceptual compare command

Bob Mottram c286ccf817 Call it a 1.0 5 years ago
man d8038392f0 Too many L's 5 years ago
python d8038392f0 Too many L's 5 years ago
src 2781d36953 Missing underscore 5 years ago
test d8038392f0 Too many L's 5 years ago
LICENSE f05edcb8be Initial 5 years ago
Makefile c286ccf817 Call it a 1.0 5 years ago
README.md d8038392f0 Too many L's 5 years ago

README.md

scrcmp: compare screenshots for UI tests

Description

During automated tests of user interfaces it may be necessary to check the current state of the screen against a reference version to see if some expected event has actually occurred. This utility helps to perform such verification by returning a percentage match value. The resulting value is pushed to stdout and so can be used by any subsequent scripts.

Why not just use ImageMagick? ImageMagick does have a compare command which includes pixel fuzzing. However, that's still really just comparing pixels in RGB space and won't handle small translations well. Because it uses edges this system is more robust to small changes or translations at the pixel level. An edge based comparrisson is closer to the perceptual changes which a human viewer can detect, and is sometimes known as "perceptual difference".

Only png format images are supported.

Installation

On Debian based systems:

sudo apt-get install build-essential
make
sudo make install
cd python
make
sudo make install

Examples

With two png images:

scrcmp --ref test/image1.png --curr test/image2.png

Will return the percentage value, or an error code.

You can also compare based on colour changes. This matches the most similar CIELab vector within a translation neighbourhood.

scrcmp --ref test/image_col1.png --curr test/image_col2.png --colour

Have a region of interest? You can specify the coordinates in pixels with:

--tx <top left> --ty <top> --bx <bottom right> --by <bottom>

and you can also use the --negative option to compare everything except for the specified region.

One interesting observation is that even with purely edge based change detection if only the colour of something changes then the zero crossing points shift slightly and this can still give a meaningful difference in match percentage.

You can then use the resulting return value within testing shell scripts. For example:

screen_match=$(scrcmp --ref test/image1.png --curr test/image2.png)
if [ $screen_match -lt 99.9 ]; then
    echo 'Screen check failed'
fi

You can also use this as a library from C.

#include <stdio.h>
#include "libscrcmp/scrcmp.h"

int main(int argc, char* argv[])
{
	char * current_filename = "image1.png";
	char * reference_filename = "image2.png";
	roi region;
	float match_percent;
	float edge_threshold = 1;
	float edge_radius = 5;
	int translation_tolerance = 3;
	int cielab_vector_tolerance = 10;
	int colour = 0;
	int verbose = 0;

	region.negative = 0;
	region.tx = -1;
	region.ty = -1;
	region.bx = -1;
	region.by = -1;

	match_percent = scrcmp(current_filename, reference_filename,
						   region, edge_threshold, edge_radius,
						   translation_tolerance,
						   cielab_vector_tolerance,
						   colour, verbose);
	printf("Match: %.4f%%\n", match_percent);

    return 0;
}

and also from Python:

#!/usr/bin/python

import scrcmp

scrcmp.setEdgeThreshold(2)
scrcmp.setEdgeRadius(10.0)
scrcmp.useEdges()
#scrcmp.useColour()
scrcmp.setTranslationTolerance(3)
scrcmp.setColourTolerance(10)
scrcmp.setROI([-1,-1,-1,-1])
scrcmp.positiveROI()
#scrcmp.negativeROI()

print scrcmp.ScrCmp("image1.png", "image2.png")