screenshot-compare

README
======

link:https://img.shields.io/github/release/meisterluk/screenshot-compare.svg?style=flat-square[image:https://img.shields.io/github/release/meisterluk/screenshot-compare.svg?style=flat-square[Latest version]]
link:https://godoc.org/github.com/meisterluk/screenshot-compare[image:https://godoc.org/github.com/meisterluk/screenshot-compare?status.svg[GoDoc]]
link:LICENSE[image:https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square[Used LICENSE]]
link:https://travis-ci.org/meisterluk/screenshot-compare[image:https://api.travis-ci.org/meisterluk/screenshot-compare.svg?branch=master[travis test result]]
link:https://goreportcard.com/report/github.com/meisterluk/screenshot-compare[image:https://goreportcard.com/badge/github.com/meisterluk/screenshot-compare[Go Report Card]]

author::
  grml solutions
version::
  1.0.2

What is it about?
-----------------

You can compare two image files and it will show a difference score between 0 and 1.
Using transparent reference PNG images, you can also skip certain areas of the file.
Unlike the title, you can compare arbitrary images, but our usecase is screenshot comparison.

Why should I use it?
--------------------

We take screenshots of running live systems and want to know, whether they are (visually) in a certain state.

Who should use it?
------------------

Especially software developers testing software might find this software useful.
Consider that Mozilla Firefox's just got a link:https://developer.mozilla.org/en-US/Firefox/Headless_mode[headless mode] and soon you will be able to take screenshots.
Chromium link:https://github.com/GoogleChrome/puppeteer[has it already]. So web developer might find it useful as well.
We use it with link:https://www.virtualbox.org/wiki/Downloads[VirtualBox].

How to install
--------------

You can run `go get`:

[source,bash]
go get github.com/meisterluk/screenshot-compare

and start developing! 😊

How to run
----------

1. Go to https://github.com/meisterluk/screenshot-compare
2. Click on the Releases link
   image:run_1.png[github releases]
3. Scroll down, choose the download appropriate for your platform
   image:run_2.png[Downloads]
4. Once the download has finished, extract the files of the tar-gz archive
5. Run the file screenshot-compare on the Terminal (cmd.exe for Windows users)
   image:run_2.png[Terminal]

One terminal example is the comparison of link:tests/grml_booting_totalmemory_kB.png[`grml_booting_totalmemory_kB.png`] and link:tests/grml_booting_totalmemory_MB.png[`grml_booting_totalmemory_MB.png`]:

[code,bash]
----
$ ./screenshot-compare grml_booting_totalmemory_kB.png grml_booting_totalmemory_MB.png
difference percentage:  0.017 %
runtime:                79.263022ms
----

The exit code also shows the difference percentage.
Run `screenshot-compare` without arguments to see the usage description for this.

Understanding the score
-----------------------

* If the dimensions of the two images do not correspond, we reject.
* We look at every individual pixel and determine a difference value between 0 and 1 based on the color.
* We multiply the difference value by the alpha channel value of the reference image.
* We evaluate the average over all pixels of the image. This is our image difference score.

White and black provides the hugest difference (though 100% is not limited to black/white):

image:example_1.png[score 100% for white/black and score 59.7% for black/blue]

These `randimg` images use similar colors, but the structures are slightly (left) or vastly (right) translated.

image:example_2.png[score 37.25% for two similar images where structures are slightly translated and score 43.97% for similar structures but vastly translated]

If you use the `Y'UV` color space, the score slightly changes (RGB provided 59.7% for black/blue):

image:example_3.png[Y'UV score 100% for white/black and Y'UV score 30.51% for black/blue]

This image illustrates the transparency feature:

image:example_4.png[difference 0% illustrating that areas with transparency in the reference areas are skipped]

`PNG` and `JPEG` file formats can be processed.
If you want a binary classifier whether the images are similar,
`0.1` (i.e. `10%`) might be a suitable classifier.

Source Code
-----------

The source code is available at link:https://github.com/meisterluk/screenshot-compare/issues[Github].

License
-------

See link:LICENSE[the LICENSE file] (Hint: MIT license).

Changelog
---------

0.0.1::
  first release: PNG only, transparency support
0.0.2::
  goroutine support, timeout argument, slight performance improvement
1.0.0::
  complete rewrite, `--wait` and `--timeout` parameters, `Y'UV` support
1.0.1::
  improved README with illustrations
1.0.2::
  introduce README section "How to run"

Issues
------

Please report any issues on the link:https://github.com/meisterluk/screenshot-compare/issues[Github issues page].