Compare PNG images in pure Ruby (uses ChunkyPNG) using different algorithms. This is an utility library for image regression testing.

Add this line to your application's Gemfile:

gem 'imatcher'

And then execute:

$ bundle

Or install it yourself as:

$ gem install imatcher

Additionally, you may want to install oily_png to improve performance when using MRI. Just install it globally or add to your Gemfile.

Imatcher supports different ways (modes) of comparing images.

Source images used in examples:

Compare pixels by values, resulting score is a ratio of unequal pixels. Resulting diff represents per-channel difference.

Compare pixels as grayscale (by brightness and alpha), resulting score is a ratio of unequal pixels (with respect to provided tolerance).

Resulting diff contains grayscale version of the first image with different pixels highlighted in red and red bounding box.

Compare pixels using Delta E distance. Resulting diff contains grayscale version of the first image with different pixels highlighted in red (with respect to diff score).

# create new matcher with default threshold equals to 0
# and base (RGB) mode
cmp = Imatcher::Matcher.new
cmp.mode #=> Imatcher::Modes::RGB

# create matcher with specific threshold
cmp = Imatcher::Matcher.new threshold: 0.05
cmp.threshold #=> 0.05

# create zero-tolerance grayscale matcher 
cmp = Imatcher::Matcher.new mode: :grayscale, tolerance: 0
cmp.mode #=> Imatcher::Modes::Grayscale

res = cmp.compare(path_1, path_2)
res #=> Imatcher::Result

res.match? #=> true

res.score #=> 0.0

# Return diff image object
res.difference_image #=> Imatcher::Image

res.difference_image.save(new_path)

# without explicit matcher
res = Imatcher.compare(path_1, path_2, options) 

# equals to
res = Imatcher::Matcher.new(options).compare(path_1, path_2)

You can exclude rectangle from comparing by passing :exclude_rect to compare. E.g., if path_1 and path_2 contain images above

Imatcher.compare(path_1, path_2, exclude_rect: [200, 150, 275, 200]).match? # => true

[200, 150, 275, 200] is array of two vertices of rectangle -- (200, 150) is left-top vertex and (275, 200) is right-bottom.

You can set bounds of comparing by passing :include_rect to compare with array similar to previous example

Bug reports and pull requests are welcome on GitHub at https://github.com/teachbase/imatcher.

The gem is available as open source under the terms of the MIT License.