README.md

Nkar image comparison and differences highlighting C++ API

Nkar (Armenian: նկար) is an image processing and comparison utility. The comparison of two images of the same size based on comparing each pixel of one image with the corresponding pixel of another one. After all differences are identified, algorithm generates contours (polygons) that outlines the differences. The API provides both error reporting and differences analysis. For instance results contains information on the number of difference contours generated (see usage example below).

According to stb single-file public domain libraries we use for image loading/decoding/saving the following image formats are supported: JPG, PNG, TGA, BMP, PSD, GIF, HDR, PIC.

Installation

No installation required. Just incorporate header and source files from src/ directory in your project and compile them. Use nkar::Comparator class to compare two images. All library classes are in nkar namespace.

Integration with CMake projects

However, if you use CMake and want to integrate the library into your project you might want to install it first by invoking a CMake command from the build directory:

cmake --install . --prefix=<install_path> --config=Release

Once the library is installed you can use it from in your project by adjusting its CMake script. For example:

[..]
find_package(nkar REQUIRED)

add_executable(example main.cpp)
target_link_libraries(example nkar)
[..]

Prerequisites

There are no special requirements and dependencies except C++11 compliant compiler. For more details see the CI badges (GitHub Actions, AppVeyor CI etc.).

Usage Example:

// A simple application that compares two image files and saves differences in a third one.

#include <string>

#include "comparator.h"
#include "image.h"

using namespace nkar;

int main(int argc, char **argv)
{
  if (argc != 4) {
    fprintf(stderr, "Incorrect number of arguments\n");
    return -1;
  }

  // Compare two image files.
  auto highlightColor = Color{0, 255, 0}; // The diff outline color.
  auto result = Comparator::compare(argv[1], argv[2], highlightColor);

  if (result.error() != Result::Error::NoError) {
    // An error occurred during comparison.
    fprintf(stderr, "%s\n", result.errorMessage().c_str());
    return -1;
  }

  if (result.status() == Result::Status::Different) {
    if (result.resultImage().save(argv[3])) {
      fprintf(stdout, "Images are different: %d contours found. Image with highlighting is saved to '%s'\n",
              result.contourCount(), argv[3]);
      return -1;
    } else {
      fprintf(stderr, "Failed to save result image\n");
      return -1;
    }
  }

  fprintf(stdout, "Images are identical\n");
  return 0;
}

Test

There are unit tests provided for nkar::Comparator class. You can find them in the test/ directory. To run them you have to build and run the test application. For doing that you must invoke the following commands from the terminal, assuming that compiler and environment are already configured:

Linux (gcc)

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DENABLE_TESTING=True
cmake --build .
ctest

Windows (MSVC Toolchain)

mkdir build && cd build
cmake .. -DENABLE_TESTING=True -A x64
cmake --build . --config=Release
ctest -C Release

For x86 builds use -A Win32 option instead.

Examples

Below are some examples of image comparison with results. Third image in each row represents an image generated by Comparator and contains contours (red outlines) that highlight the differences:

expected	actual	diff with contours

See Also

For reading and writing image files we used stb single-file public domain libraries