Skip to content

Expose ImageComparer API #1129

Open

Description

@antonfirsov

The image comparison logic implemented in TolerantImageComparer might be interesting for users, eg. for testing purposes.

We should expose a similar feature from the core library.

The current ImageComparer API returns a list of detected pixel differences, which did not turn out to be useful. Shouldn't we return a difference image instead? Or should we return both?

Activity

  1. johanbenschop commented on Feb 26, 2020

    @johanbenschop

    I would be very interested in this feature. What I'm currently looking for is the ability to compare a known good image with one that was just generated in a unit test and look whether they're the same or at least close enough. I would prefer a percentage of how much difference there is (like a summary of what PixelDifference is now).

    A difference image would be useful to see what changed I suppose, but I don't quite see how this is would work inside a test.

  2. antonfirsov commented on Feb 26, 2020

    @antonfirsov
    MemberAuthor

    You can call differnceImage.Save(...) to save it for manual analysis. In our test infrastructure we have a .DebugSave(...) extension method to save images to a dedicated artifact folder locally which is super useful, even without the difference image. On CI that method is a NOP.

    Since our backlog is full of high priority topics (both big and small), I can't promise that this API will become a thing anytime soon. Feel free to borrow our code until then, and thanks for the feedback! 👍

  3. atruskie commented on Apr 19, 2020

    @atruskie
    Contributor

    I would be interested in this. I have had long had my own functions to do this and suffice to say, they are not that great.

    RE difference image, I did a similar thing. I made a "DeltaImageProcesser" which my image comparer method uses. It is not a true difference image, but I've found it be diagnostically more useful, especially for very small differences. It boils down to:

    • return gray if pixels are equal
    • return Black if top is less than bottom
    • otherwise return White

    The code is here if anyone is interested: https://github.com/QutEcoacoustics/audio-analysis/blob/b3741577a39a4a8982472a4ebcdecf8e227849a7/src/Acoustics.Shared/ImageSharp/DeltaPixelBlender.cs#L55-L64

    Here is an example output:

    Actual

    TestNoAADrawLineDiagonalMultiplePoints_actual

    Delta

    TestNoAADrawLineDiagonalMultiplePoints_delta

    Expected

    TestNoAADrawLineDiagonalMultiplePoints_expected

  4. added this to the Future milestone on Apr 24, 2020
  5. brickman1444 commented on Jun 20, 2021

    @brickman1444

    I'd also be interested in this feature. I maintain an application that composes images like this using ImageSharp.
    image

    I have some tests covering the process end to end to make sure nothing breaks during refactors but I had to write the comparison myself and dial down the tolerance because I don't think I wrote it correctly.

  6. bkolo commented on Sep 22, 2022

    @bkolo

    how about the ability to fingerprint image for a large library of images to identify similar images using a stored hash in a database

  7. antonfirsov commented on Sep 22, 2022

    @antonfirsov
    MemberAuthor

    ImageComparer intends to define a numeric similarity metric to measure difference between two images, it's primary use-case
    is testing.

    Image fingerprinting / hashing is a related, but different feature. If this is something you are seriously interested in and you can give us ideas with specific algorithms or examples from other projects in mind, I recommend opening an Idea Discussion providing as much info and context as you can.

  8. JimBobSquarePants commented on Sep 25, 2022

    @JimBobSquarePants
    Member
  9. ndavat commented on Nov 14, 2026

    @ndavat

    I took a pass at this, following the API guidance from discussion #1358. PR: #3276

    The PR adds a public SixLabors.ImageSharp.Comparison namespace to the core library. It follows the four points from the discussion:

    • The API is pixel-agnostic. ImageComparer.CompareImagesOrFrames takes non-generic Image / ImageFrame and returns a non-generic ImageSimilarityReport. The pixel types are resolved by double dispatch through ImageFrame.Accept(IImageFrameVisitor).
    • ImageSimilarityReport.CreateDifferenceImage() returns a non-generic Image.
    • There is no public per-pixel difference list. The report carries the total normalized difference and the compared frames. Users can observe where pixels differ through the difference image.
    • Reports always carry the compared frames, so a difference image is also available for matching frames (it renders as uniform mid-gray there).

    This answers the open question in this issue ("difference image or both?") with: the report carries the metrics, and the difference image is created on demand, so comparisons without a mismatch do not allocate an image.

    The difference image encodes direction per RGB channel: mid-gray where components are equal, white where the actual component is above the expected one, black where it is below. The image is fully opaque so it can be saved without alteration. Alpha differences are reflected in the total difference only. I kept the rendering RGB-only on purpose; happy to fold alpha into the encoding if you prefer.

    The comparison math matches the internal test comparers (same manhattan metric, same normalization, same threshold units). The internal test comparers stay unchanged; re-pointing them to the public API can be a follow-up.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions