image-comparison

Introduction: Published on Maven Central Java Library that compares 2 images with the same sizes and shows the differences visually by drawing rectangles. Some parts of the image can be excluded from the comparison. Can be used for automation qa tests.
More: Author   ReportBugs   OfficialWebsite   
Tags:

logo-trans Maven Central Javadocs Codacy Badge Build Status Coverage Status BCH compliance Bintray PRs Welcome

Published on Maven Central Java Library that compares 2 images with the same sizes and shows the differences visually by drawing rectangles. Some parts of the image can be excluded from the comparison. Can be used for automation qa tests. The Usages of the image-comparison can be found here Usage Image Comparison

  • Implementation is using only standard core language and platform features, no 3rd party libraries and plagiarized code is permitted.

  • Pixels (with the same coordinates in two images) can be visually similar, but have different values of RGB. 2 pixels are considered to be "different" if they differ more than 10% from each other.

  • The output of the comparison is a copy of actual images. The differences are outlined with red rectangles as shown below.

  • No third party libraries or borrowed code are in usage.

  • Some parts of the image can be excluded from the comparison and drawn in the result image.

Configurations

Property Description
threshold The threshold which means the max distance between non-equal pixels. Could be changed according size and requirements to the image.
rectangleLineWidth Width of the line that is drawn the rectangle.
destination File of the result destination.
minimalRectangleSize The number of the minimal rectangle size. Count as (width x height). By default it's 1.
maximalRectangleCount Maximal count of the Rectangles, which would be drawn. It means that would get first x biggest rectangles. Default value is -1, that means that all the rectangles would be drawn.
pixelToleranceLevel Level of the pixel tolerance. By default it's 0.1 -> 10% difference. The value can be set from 0.0 to 0.99.
excludedAreas ExcludedAreas contains a List of Rectangles to be ignored when comparing images.
drawExcludedRectangles Flag which says draw excluded rectangles or not.

Release Notes

Can be found in RELEASE_NOTES.

Usage

Using the command-line

This library can be used as a command-line utility to compare two images.

After building with ./gradlew jar, you will find the runnable jar at ${projectDir}/build/libs.

To compare two images in files a.png and b.png, for example, run:

java -jar image-comparison.jar a.png b.png

To save the result image in a third file, say comparison.png, just give that file as a third argument:

java -jar image-comparison.jar a.png b.png comparison.png

To show more usage details, run:

java -jar image-comparison.jar -h

Using as a Java library

Dependency

Maven
<dependency>
    <groupId>com.github.romankh3</groupId>
    <artifactId>image-comparison</artifactId>
    <version>3.3.0</version>
</dependency>
Gradle
compile 'com.github.romankh3:image-comparison:3.3.0'

To compare two images programmatically

class Example {
    public static void main( String[] args ) {
       // load the images to be compared
               BufferedImage expectedImage = ImageComparisonUtil.readImageFromResources("expected.png");
               BufferedImage actualImage = ImageComparisonUtil.readImageFromResources("actual.png");

               // where to save the result (leave null if you want to see the result in the UI)
               File resultDestination = new File( "result.png" );

               //Create ImageComparison object for it.
               ImageComparison imageComparison = new ImageComparison( expectedImage, actualImage, resultDestination );

               //Can be used another constructor for it, without destination.
               new ImageComparison("expected.png", "actual.png");
               //or
               new ImageComparison(expectedImage, actualImage);

               //Also can be configured BEFORE comparing next properties:

               //Threshold - it's the max distance between non-equal pixels. By default it's 5. imageComparison.setThreshold(10);
               imageComparison.getThreshold();

               //RectangleListWidth - Width of the line that is drawn in the rectangle. By default it's 1. imageComparison.setRectangleLineWidth(5);
               imageComparison.getRectangleLineWidth();

               //Destination. Before comparing also can be added destination file for result image.
               imageComparison.setDestination(resultDestination);
               imageComparison.getDestination();

               //MaximalRectangleCount - It means that would get first x biggest rectangles for drawing.
               // by default all the rectangles would be drawn.
               imageComparison.setMaximalRectangleCount(10);
               imageComparison.getMaximalRectangleCount();

               //MinimalRectangleSize - The number of the minimal rectangle size. Count as (width x height).
               // by default it's 1. imageComparison.setMinimalRectangleSize(100);
               imageComparison.getMinimalRectangleSize();

               //Change the level of the pixel tolerance:
               imageComparison.setPixelToleranceLevel(0.2);
               imageComparison.getPixelToleranceLevel();

               //After configuring the ImageComparison object, can be executed compare() method:
               ComparisonResult comparisonResult = imageComparison.compareImages();

               //Can be found ComparisonState.
               ComparisonState comparisonState = comparisonResult.getComparisonState();

               //And Result Image
               BufferedImage resultImage = comparisonResult.getResult();

               //Image can be saved after comparison, using ImageComparisonUtil.
               ImageComparisonUtil.saveImage(resultDestination, resultImage); 
    }
}

Building

To clone and build this project, run the following commands:

git clone https://github.com/romankh3/image-comparison
cd image-comparison
./gradlew check jar

This will compile, run the tests, and create a runnable jar at ${projectDir}/build/libs.

Demo

Run the ./run.sh script to run the demo.

You will get the result of comparing two images. The images, which are using:

Expected Image(ex image1)

expected

Actual Image(ex image 2)

actual

Result

result

Contributing

Please, follow Contributing page.

Code of Conduct

Please, follow Code of Conduct page.

License

This project is unlicense - see the LICENSE file for details

Also if you're interesting - see my other repositories

Apps
About Me
Google+: Trinea trinea
GitHub: Trinea