teachbase / imatcher

Image comparison library

Imatcher

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

Installation

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.

Modes

Imatcher supports different ways (modes) of comparing images.

Source images used in examples:

Base (RGB) mode

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

Grayscale mode

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.

Delta

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).

Usage

# 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)

Excluding rectangle

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.

Including rectangle

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

Contributing

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

License

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

imatcher's Issues

exclude_area and include_area are not valid arguments

When I call
Imatcher.compare("path/1", "path/2", exclude_area: [700, 800, 1500, 1000]) or Imatcher.compare("path/1", "path/2", include_area: [700, 800, 1500, 1000])

I get
ArgumentError: unknown keyword: exclude_area or
ArgumentError: unknown keyword: include_area

Pretty confused about this one because these two keywords are specifically mentioned in the wiki.

I'm testing this in the Pry console, after I got the same error trying to run it in my ruby/cucumber/watir testing stack:
require 'imatcher'
Imatcher.compare(...)

Warning with Ruby 2.7.1

I am getting this warning in logs for
Ruby: 2.7.1
Rails: 6.0.3.3

imatcher-0.1.9/lib/imatcher/modes/delta.rb:12: warning: Using the last argument as keyword parameters is deprecated; maybe ** should be added to the call