diff --git a/src/ImageSharp/Advanced/AotCompilerTools.cs b/src/ImageSharp/Advanced/AotCompilerTools.cs index d9d4000225..4940685330 100644 --- a/src/ImageSharp/Advanced/AotCompilerTools.cs +++ b/src/ImageSharp/Advanced/AotCompilerTools.cs @@ -5,6 +5,8 @@ using System.Diagnostics.CodeAnalysis; using System.Numerics; using System.Runtime.CompilerServices; +using SixLabors.ImageSharp.Advanced; +using SixLabors.ImageSharp.Comparison; using SixLabors.ImageSharp.Formats; using SixLabors.ImageSharp.Formats.Ani; using SixLabors.ImageSharp.Formats.Bmp; @@ -158,6 +160,7 @@ private static void Seed() AotCompilePixelMaps(); AotCompileDithers(); AotCompileMemoryManagers(); + AotCompileImageComparison(); _ = Unsafe.SizeOf(); @@ -700,6 +703,24 @@ private static void AotCompileMemoryManagers() AotCompileMemoryManager(); } + /// + /// This method pre-seeds the image comparison in the AoT compiler. + /// + /// + /// The comparison is seeded for the same pixel type on both sides. Comparing different pixel + /// types is resolved at run time by the visitor dispatch and follows the same discovery + /// limits as other cross-type generic APIs. + /// + /// The pixel format. + [Preserve] + private static void AotCompileImageComparison() + where TPixel : unmanaged, IPixel + { + ImageFrame frame = default; + _ = ImageComparisonEngine.CompareFrames(0, frame, frame, 0, 0); + _ = ImageComparisonEngine.CreateDifferenceImage(frame, frame); + } + /// /// This method pre-seeds the in the AoT compiler. /// diff --git a/src/ImageSharp/Comparison/Exceptions/ImageDifferenceIsOverThresholdException.cs b/src/ImageSharp/Comparison/Exceptions/ImageDifferenceIsOverThresholdException.cs new file mode 100644 index 0000000000..74509010aa --- /dev/null +++ b/src/ImageSharp/Comparison/Exceptions/ImageDifferenceIsOverThresholdException.cs @@ -0,0 +1,42 @@ +// Copyright (c) Six Labors. +// Licensed under the Six Labors Split License. + +using System.Globalization; +using System.Text; + +namespace SixLabors.ImageSharp.Comparison.Exceptions; + +/// +/// The exception that is thrown when the difference of a compared image or frame is over the +/// threshold of the comparer. +/// +public class ImageDifferenceIsOverThresholdException : ImagesSimilarityException +{ + /// + /// Initializes a new instance of the class. + /// + /// The reports of the frames which are over the threshold. + public ImageDifferenceIsOverThresholdException(IReadOnlyList reports) + : base("Image difference is over threshold!" + StringifyReports(reports)) + => this.Reports = reports; + + /// + /// Gets the reports of the frames which are over the threshold. + /// + public IReadOnlyList Reports { get; } + + private static string StringifyReports(IReadOnlyList reports) + { + StringBuilder sb = new(); + sb.Append(Environment.NewLine); + + foreach (ImageSimilarityReport report in reports) + { + sb.AppendFormat(CultureInfo.InvariantCulture, "Report ImageFrame {0}: ", report.Index) + .Append(report) + .Append(Environment.NewLine); + } + + return sb.ToString(); + } +} diff --git a/src/ImageSharp/Comparison/Exceptions/ImageDimensionsMismatchException.cs b/src/ImageSharp/Comparison/Exceptions/ImageDimensionsMismatchException.cs new file mode 100644 index 0000000000..4bfbc5d3e8 --- /dev/null +++ b/src/ImageSharp/Comparison/Exceptions/ImageDimensionsMismatchException.cs @@ -0,0 +1,32 @@ +// Copyright (c) Six Labors. +// Licensed under the Six Labors Split License. + +namespace SixLabors.ImageSharp.Comparison.Exceptions; + +/// +/// The exception that is thrown when the dimensions of the compared images or frames do not match. +/// +public class ImageDimensionsMismatchException : ImagesSimilarityException +{ + /// + /// Initializes a new instance of the class. + /// + /// The expected size. + /// The actual size. + public ImageDimensionsMismatchException(Size expectedSize, Size actualSize) + : base($"The image dimensions {actualSize} do not match the expected {expectedSize}!") + { + this.ExpectedSize = expectedSize; + this.ActualSize = actualSize; + } + + /// + /// Gets the expected size of the compared images or frames. + /// + public Size ExpectedSize { get; } + + /// + /// Gets the actual size of the compared images or frames. + /// + public Size ActualSize { get; } +} diff --git a/src/ImageSharp/Comparison/Exceptions/ImageFramesMismatchException.cs b/src/ImageSharp/Comparison/Exceptions/ImageFramesMismatchException.cs new file mode 100644 index 0000000000..95ca6a6c5e --- /dev/null +++ b/src/ImageSharp/Comparison/Exceptions/ImageFramesMismatchException.cs @@ -0,0 +1,32 @@ +// Copyright (c) Six Labors. +// Licensed under the Six Labors Split License. + +namespace SixLabors.ImageSharp.Comparison.Exceptions; + +/// +/// The exception that is thrown when the number of frames of the compared images does not match. +/// +public class ImageFramesMismatchException : ImagesSimilarityException +{ + /// + /// Initializes a new instance of the class. + /// + /// The expected frame count. + /// The actual frame count. + public ImageFramesMismatchException(int expectedCount, int actualCount) + : base($"The image frame count {actualCount} does not match the expected {expectedCount}!") + { + this.ExpectedCount = expectedCount; + this.ActualCount = actualCount; + } + + /// + /// Gets the expected frame count of the compared images. + /// + public int ExpectedCount { get; } + + /// + /// Gets the actual frame count of the compared images. + /// + public int ActualCount { get; } +} diff --git a/src/ImageSharp/Comparison/Exceptions/ImagesSimilarityException.cs b/src/ImageSharp/Comparison/Exceptions/ImagesSimilarityException.cs new file mode 100644 index 0000000000..96d12ed4e0 --- /dev/null +++ b/src/ImageSharp/Comparison/Exceptions/ImagesSimilarityException.cs @@ -0,0 +1,22 @@ +// Copyright (c) Six Labors. +// Licensed under the Six Labors Split License. + +using System; + +namespace SixLabors.ImageSharp.Comparison.Exceptions; + +/// +/// The exception that is thrown when the similarity between two images does not meet the +/// requirements of the comparison. +/// +public class ImagesSimilarityException : Exception +{ + /// + /// Initializes a new instance of the class. + /// + /// The message that describes the error. + public ImagesSimilarityException(string message) + : base(message) + { + } +} diff --git a/src/ImageSharp/Comparison/ImageComparer.cs b/src/ImageSharp/Comparison/ImageComparer.cs new file mode 100644 index 0000000000..37bb2ad9cf --- /dev/null +++ b/src/ImageSharp/Comparison/ImageComparer.cs @@ -0,0 +1,262 @@ +// Copyright (c) Six Labors. +// Licensed under the Six Labors Split License. + +using SixLabors.ImageSharp.Advanced; +using SixLabors.ImageSharp.Comparison.Exceptions; +using SixLabors.ImageSharp.PixelFormats; + +namespace SixLabors.ImageSharp.Comparison; + +/// +/// Compares images and image frames and reports the similarity between them. +/// +/// +/// +/// Comparers are stateless, so a single instance can be reused for multiple comparisons. +/// +/// +/// The comparison is performed against the components of the pixel formats after conversion +/// to . When both formats use associated (premultiplied) alpha, the stored +/// RGB components are compared directly; otherwise the components are converted to +/// unassociated (straight) alpha first, so that differences at low alpha are not amplified. +/// +/// +public abstract class ImageComparer +{ + /// + /// Gets the default image threshold of a tolerant comparer. + /// + /// + /// 1% of all pixels in a 100*100 pixel area are allowed to have a difference of 1 unit + /// 257 = (1 / 255) * 65535. + /// + public const float DefaultImageThreshold = 257F / (100 * 100 * 65535); + + /// + /// Initializes a new instance of the class. + /// + protected ImageComparer() + { + } + + /// + /// Gets an that requires an exact match between the components + /// of two pixels. + /// + public static ImageComparer Exact { get; } = new TolerantImageComparer(0, 0); + + /// + /// Returns an instance of . + /// The individual manhattan pixel difference is only added to the total image difference when + /// the individual difference is over . + /// + /// + /// The maximal tolerated difference represented by a value between 0.0 and 1.0 scaled to 0 and 65535. + /// + /// + /// The threshold of the individual pixels before they accumulate towards the overall difference. + /// + /// An instance. + public static ImageComparer Tolerant( + float imageThreshold = DefaultImageThreshold, + int perPixelManhattanThreshold = 0) => + new TolerantImageComparer(imageThreshold, perPixelManhattanThreshold); + + /// + /// Returns an equivalent to + /// ( / 100). + /// + /// The maximal tolerated difference in percents. + /// + /// The threshold of the individual pixels before they accumulate towards the overall difference. + /// + /// An instance. + public static ImageComparer TolerantPercentage(float imageThresholdInPercents, int perPixelManhattanThreshold = 0) + => Tolerant(imageThresholdInPercents / 100F, perPixelManhattanThreshold); + + /// + /// Compares the root frames of two images. + /// + /// The expected image. + /// The actual image. + /// + /// An describing the difference between the two images. + /// + /// + /// The dimensions of the two images do not match. + /// + public ImageSimilarityReport CompareImagesOrFrames(Image expected, Image actual) + { + Guard.NotNull(expected, nameof(expected)); + Guard.NotNull(actual, nameof(actual)); + + return this.CompareImagesOrFrames(0, expected.Frames.RootFrame, actual.Frames.RootFrame); + } + + /// + /// Compares two image frames. + /// + /// The index of the compared frames, used to identify the report. + /// The expected image frame. + /// The actual image frame. + /// + /// An describing the difference between the two frames. + /// + /// + /// The dimensions of the two frames do not match. + /// + public ImageSimilarityReport CompareImagesOrFrames(int index, ImageFrame expected, ImageFrame actual) + { + Guard.NotNull(expected, nameof(expected)); + Guard.NotNull(actual, nameof(actual)); + + if (expected.Size != actual.Size) + { + throw new ImageDimensionsMismatchException(expected.Size, actual.Size); + } + + FramePairVisitor visitor = new(this, index, actual); + expected.Accept(visitor); + + // The visitor guarantees a report: the acceptance of a valid frame always dispatches the comparison. + return visitor.Report!; + } + + /// + /// Compares all frames of two images in order. + /// + /// The expected image. + /// The actual image. + /// + /// The reports describing the differences of the frames which do not match. Frames which match + /// are not represented in the result. + /// + /// + /// The dimensions of the two images do not match. + /// + /// + /// The images have a different number of frames. + /// + public IReadOnlyList CompareImages(Image expected, Image actual) + { + Guard.NotNull(expected, nameof(expected)); + Guard.NotNull(actual, nameof(actual)); + + if (expected.Size != actual.Size) + { + throw new ImageDimensionsMismatchException(expected.Size, actual.Size); + } + + if (expected.Frames.Count != actual.Frames.Count) + { + throw new ImageFramesMismatchException(expected.Frames.Count, actual.Frames.Count); + } + + List result = []; + for (int i = 0; i < expected.Frames.Count; i++) + { + ImageSimilarityReport report = this.CompareImagesOrFrames(i, expected.Frames[i], actual.Frames[i]); + if (!report.IsEmpty) + { + result.Add(report); + } + } + + return result; + } + + /// + /// Compares two images and throws when any of their frames differ beyond the tolerance of this + /// comparer. + /// + /// The expected image. + /// The actual image. + /// + /// The dimensions of the two images do not match. + /// + /// + /// The images have a different number of frames. + /// + /// + /// The difference of any frame is over the threshold of this comparer. + /// + public void VerifySimilarity(Image expected, Image actual) + { + IReadOnlyList reports = this.CompareImages(expected, actual); + if (reports.Count > 0) + { + throw new ImageDifferenceIsOverThresholdException(reports); + } + } + + /// + /// Provides a pixel-specific implementation for a given comparison. + /// + /// The pixel type of the expected frame. + /// The pixel type of the actual frame. + /// The index of the compared frames, used to identify the report. + /// The expected image frame. + /// The actual image frame. + /// + /// An describing the difference between the two frames. + /// + internal abstract ImageSimilarityReport CompareImagesOrFramesCore( + int index, + ImageFrame expected, + ImageFrame actual) + where TPixelA : unmanaged, IPixel + where TPixelB : unmanaged, IPixel; + + /// + /// Resolves the pixel type of the expected frame, then dispatches the pixel type of the + /// actual frame, so that a pixel-specific comparison of both frames can be performed. + /// + private sealed class FramePairVisitor : IImageFrameVisitor + { + private readonly ImageComparer comparer; + private readonly int index; + private readonly ImageFrame actual; + + public FramePairVisitor(ImageComparer comparer, int index, ImageFrame actual) + { + this.comparer = comparer; + this.index = index; + this.actual = actual; + } + + public ImageSimilarityReport? Report { get; private set; } + + public void Visit(ImageFrame expected) + where TPixelA : unmanaged, IPixel + { + ActualFrameVisitor visitor = new(this.comparer, this.index, expected); + this.actual.Accept(visitor); + this.Report = visitor.Report; + } + } + + /// + /// Resolves the pixel type of the actual frame and performs the comparison of both typed frames. + /// + /// The pixel type of the expected frame. + private sealed class ActualFrameVisitor : IImageFrameVisitor + where TPixelA : unmanaged, IPixel + { + private readonly ImageComparer comparer; + private readonly int index; + private readonly ImageFrame expected; + + public ActualFrameVisitor(ImageComparer comparer, int index, ImageFrame expected) + { + this.comparer = comparer; + this.index = index; + this.expected = expected; + } + + public ImageSimilarityReport? Report { get; private set; } + + public void Visit(ImageFrame actual) + where TPixelB : unmanaged, IPixel + => this.Report = this.comparer.CompareImagesOrFramesCore(this.index, this.expected, actual); + } +} diff --git a/src/ImageSharp/Comparison/ImageComparisonEngine.cs b/src/ImageSharp/Comparison/ImageComparisonEngine.cs new file mode 100644 index 0000000000..7f12abb1f4 --- /dev/null +++ b/src/ImageSharp/Comparison/ImageComparisonEngine.cs @@ -0,0 +1,231 @@ +// Copyright (c) Six Labors. +// Licensed under the Six Labors Split License. + +using System.Numerics; +using System.Runtime.InteropServices; +using SixLabors.ImageSharp.Memory; +using SixLabors.ImageSharp.PixelFormats; + +namespace SixLabors.ImageSharp.Comparison; + +/// +/// Provides the shared comparison and difference image implementations for all comparers. +/// +internal static class ImageComparisonEngine +{ + // Pixels of identical images are rendered as mid-gray. Every differing component of the actual + // image is rendered as white when the component of the actual image is above the component of + // the expected image, and black when it is below. Rendering is per RGB channel, so the channels + // which changed and their direction are immediately visible. The difference image is fully + // opaque, so that it can be saved without alteration; alpha differences are reflected in the + // total difference of the report only. + private static readonly Rgba32 EqualPixelColor = new(128, 128, 128, 255); + + /// + /// Compares two image frames and returns the report describing their difference. + /// + /// The pixel type of the expected frame. + /// The pixel type of the actual frame. + /// The index of the compared frames, used to identify the report. + /// The expected image frame. + /// The actual image frame. + /// The maximal tolerated difference of the comparer. + /// + /// The threshold of the individual pixels before they accumulate towards the overall difference. + /// + /// An describing the difference. + public static ImageSimilarityReport CompareFrames( + int index, + ImageFrame expected, + ImageFrame actual, + float imageThreshold, + int perPixelManhattanThreshold) + where TPixelA : unmanaged, IPixel + where TPixelB : unmanaged, IPixel + { + int width = actual.Width; + + // Reuse floating-point rows so comparison does not quantize or clip the decoded components. + RgbaVector[] aBuffer = new RgbaVector[width]; + RgbaVector[] bBuffer = new RgbaVector[width]; + Span aVectors = MemoryMarshal.Cast(aBuffer.AsSpan()); + Span bVectors = MemoryMarshal.Cast(bBuffer.AsSpan()); + + float totalDifference = 0F; + bool associated = GetAssociated(expected, actual); + Configuration configuration = expected.Configuration; + Buffer2D expectedBuffer = expected.PixelBuffer; + Buffer2D actualBuffer = actual.PixelBuffer; + + for (int y = 0; y < actual.Height; y++) + { + ConvertRow(configuration, expectedBuffer.DangerousGetRowSpan(y), aVectors, associated); + ConvertRow(configuration, actualBuffer.DangerousGetRowSpan(y), bVectors, associated); + + for (int x = 0; x < width; x++) + { + // Equal infinities and matching NaNs have no difference; subtracting them would instead produce NaN. + if (aBuffer[x] == bBuffer[x]) + { + continue; + } + + float d = GetManhattanDistanceInRgbaSpace(ref aBuffer[x], ref bBuffer[x]); + + if (!(d <= perPixelManhattanThreshold)) + { + totalDifference += d; + } + } + } + + float normalizedDifference = totalDifference / (actual.Width * (float)actual.Height); + normalizedDifference /= 4F * 65535F; + + // A non-finite difference must also fail; comparing only with '>' would silently accept NaN. + bool isEmpty = normalizedDifference <= imageThreshold; + return new ImageSimilarityReport(index, expected, actual, normalizedDifference, isEmpty); + } + + /// + /// Creates a difference image for two image frames. Pixels with equal components are rendered + /// as mid-gray. Every component of the actual image which differs is rendered as white when it + /// is above the component of the expected image, and black when it is below. Rendering is per + /// RGB channel; the difference image is fully opaque. + /// + /// The pixel type of the expected frame. + /// The pixel type of the actual frame. + /// The expected image frame. + /// The actual image frame. + /// The difference image. + public static Image CreateDifferenceImage(ImageFrame expected, ImageFrame actual) + where TPixelA : unmanaged, IPixel + where TPixelB : unmanaged, IPixel + { + int width = actual.Width; + Image differenceImage = new(expected.Configuration, width, actual.Height); + Buffer2D differenceBuffer = differenceImage.Frames.RootFrame.PixelBuffer; + + // Reuse floating-point rows so rendering does not quantize or clip the decoded components. + RgbaVector[] aBuffer = new RgbaVector[width]; + RgbaVector[] bBuffer = new RgbaVector[width]; + Span aVectors = MemoryMarshal.Cast(aBuffer.AsSpan()); + Span bVectors = MemoryMarshal.Cast(bBuffer.AsSpan()); + + bool associated = GetAssociated(expected, actual); + Configuration configuration = expected.Configuration; + Buffer2D expectedBuffer = expected.PixelBuffer; + Buffer2D actualBuffer = actual.PixelBuffer; + + for (int y = 0; y < actual.Height; y++) + { + ConvertRow(configuration, expectedBuffer.DangerousGetRowSpan(y), aVectors, associated); + ConvertRow(configuration, actualBuffer.DangerousGetRowSpan(y), bVectors, associated); + + Span differenceRow = differenceBuffer.DangerousGetRowSpan(y); + differenceRow.Fill(EqualPixelColor); + + for (int x = 0; x < width; x++) + { + // Equal infinities and matching NaNs have no difference; a differing component is + // rendered by its direction. Mismatched NaNs compare as equal on the channel level + // because they fail both directional comparisons. + RgbaVector a = aBuffer[x]; + RgbaVector b = bBuffer[x]; + + if (a == b) + { + continue; + } + + differenceRow[x] = new Rgba32( + ToDifferenceLevel(a.R, b.R), + ToDifferenceLevel(a.G, b.G), + ToDifferenceLevel(a.B, b.B), + byte.MaxValue); + } + } + + return differenceImage; + } + + /// + /// Converts a single pixel component of the actual image into the gray level visualizing its + /// difference against the expected image. + /// + /// The component of the expected image. + /// The component of the actual image. + /// The gray level of the component. + private static byte ToDifferenceLevel(float expected, float actual) + { + if (actual > expected) + { + return byte.MaxValue; + } + + if (actual < expected) + { + return 0; + } + + return EqualPixelColor.R; + } + + /// + /// Converts a row of pixels into the floating-point buffer. Two associated formats are converted + /// using their stored associated components; other pairs are converted using unassociated + /// components, matching the conversion used by the comparison. + /// + /// The pixel type of the row. + /// The configuration used by the conversion. + /// The row of pixels. + /// The vector view of the buffer receiving the components. + /// + /// Whether the row is converted using associated components. + /// + private static void ConvertRow( + Configuration configuration, + Span row, + Span vectors, + bool associated) + where TPixel : unmanaged, IPixel + { + if (associated) + { + // Compare stored RGB when both formats are associated. Unassociation would amplify differences at low alpha. + PixelOperations.Instance.ToAssociatedScaledVector4(configuration, row, vectors); + } + else + { + // Mixed alpha representations need straight RGB on both sides before their components can be compared. + PixelOperations.Instance.ToUnassociatedScaledVector4(configuration, row, vectors); + } + } + + /// + /// Determines whether both frames are compared using their stored associated components. + /// + /// The pixel type of the expected frame. + /// The pixel type of the actual frame. + /// The expected image frame. + /// The actual image frame. + /// Whether both frames use associated alpha. + private static bool GetAssociated(ImageFrame expected, ImageFrame actual) + where TPixelA : unmanaged, IPixel + where TPixelB : unmanaged, IPixel + => TPixelA.GetPixelTypeInfo().AlphaRepresentation == PixelAlphaRepresentation.Associated + && TPixelB.GetPixelTypeInfo().AlphaRepresentation == PixelAlphaRepresentation.Associated; + + /// + /// Calculates the sum of absolute RGBA differences in sixteen-bit component units. + /// + /// The first floating-point pixel. + /// The second floating-point pixel. + /// The component distance, including fractional sixteen-bit codes. + private static float GetManhattanDistanceInRgbaSpace(ref RgbaVector a, ref RgbaVector b) + { + // Keep the existing threshold units: one eight-bit code equals 257 sixteen-bit units. + Vector4 delta = Vector4.Abs(a.ToScaledVector4() - b.ToScaledVector4()) * ushort.MaxValue; + return delta.X + delta.Y + delta.Z + delta.W; + } +} diff --git a/src/ImageSharp/Comparison/ImageSimilarityReport.cs b/src/ImageSharp/Comparison/ImageSimilarityReport.cs new file mode 100644 index 0000000000..b8a1239aae --- /dev/null +++ b/src/ImageSharp/Comparison/ImageSimilarityReport.cs @@ -0,0 +1,166 @@ +// Copyright (c) Six Labors. +// Licensed under the Six Labors Split License. + +using System.Globalization; +using SixLabors.ImageSharp.Advanced; +using SixLabors.ImageSharp.PixelFormats; + +namespace SixLabors.ImageSharp.Comparison; + +/// +/// The result of a single image or image frame comparison, containing the similarity metrics and +/// the frames which were compared. +/// +public class ImageSimilarityReport +{ + /// + /// Initializes a new instance of the class. + /// + /// The index of the compared frames. + /// The expected image frame. + /// The actual image frame. + /// + /// The total difference normalized by the image dimensions and the component count. + /// + /// + /// Whether the difference is within the tolerance of the comparer which produced the report. + /// + internal ImageSimilarityReport( + int index, + ImageFrame expectedImageFrame, + ImageFrame actualImageFrame, + float totalNormalizedDifference, + bool isEmpty) + { + this.Index = index; + this.ExpectedImageFrame = expectedImageFrame; + this.ActualImageFrame = actualImageFrame; + this.TotalNormalizedDifference = totalNormalizedDifference; + this.IsEmpty = isEmpty; + } + + /// + /// Gets the index of the compared frames. + /// + public int Index { get; } + + /// + /// Gets the expected image frame of the comparison. + /// + public ImageFrame ExpectedImageFrame { get; } + + /// + /// Gets the actual image frame of the comparison. + /// + public ImageFrame ActualImageFrame { get; } + + /// + /// Gets the total difference of the frames, normalized by the image dimensions and the + /// component count. A value between 0.0 and 1.0, where 0.0 means the frames are equal and 1.0 + /// means every component of every pixel differs by the full component range. + /// + public float TotalNormalizedDifference { get; } + + /// + /// Gets the total difference of the frames as a percentage string. + /// + public string DifferencePercentageString + { + get + { + if (this.TotalNormalizedDifference == 0) + { + return "0%"; + } + + return string.Create(CultureInfo.InvariantCulture, $"{this.TotalNormalizedDifference * 100:0.0000}%"); + } + } + + /// + /// Gets a value indicating whether the difference is within the tolerance of the comparer + /// which produced the report. + /// + public bool IsEmpty { get; } + + /// + /// Creates a difference image for the compared frames. Pixels with equal components are + /// rendered as mid-gray. Every component of the actual image which differs is rendered as + /// white when it is above the component of the expected image, and black when it is below. + /// Rendering is per RGB channel; the difference image is fully opaque, so alpha differences + /// are reflected in the total difference only. + /// + /// The difference image. + /// + /// The report does not contain the compared frames. + /// + public Image CreateDifferenceImage() + { + if (this.ExpectedImageFrame is null || this.ActualImageFrame is null) + { + throw new InvalidOperationException("The report does not contain the compared frames."); + } + + DifferenceImageVisitor visitor = new(this.ExpectedImageFrame, this.ActualImageFrame); + this.ExpectedImageFrame.Accept(visitor); + + // The visitor guarantees an image: the acceptance of a valid frame always dispatches the rendering. + return visitor.DifferenceImage!; + } + + /// + public override string ToString() + { + return this.IsEmpty ? "[SimilarImages]" : $"Total difference: {this.DifferencePercentageString}"; + } + + /// + /// Resolves the pixel type of the expected frame, then dispatches the pixel type of the + /// actual frame, so that a pixel-specific difference image of both frames can be created. + /// + private sealed class DifferenceImageVisitor : IImageFrameVisitor + { + private readonly ImageFrame actual; + + public DifferenceImageVisitor(ImageFrame expectedImageFrame, ImageFrame actualImageFrame) + { + this.ExpectedImageFrame = expectedImageFrame; + this.actual = actualImageFrame; + } + + public ImageFrame ExpectedImageFrame { get; } + + public Image? DifferenceImage { get; private set; } + + public void Visit(ImageFrame expected) + where TPixelA : unmanaged, IPixel + { + ActualFrameVisitor visitor = new(expected, this.actual); + this.actual.Accept(visitor); + this.DifferenceImage = visitor.DifferenceImage; + } + } + + /// + /// Creates the difference image of both typed frames. + /// + /// The pixel type of the expected frame. + private sealed class ActualFrameVisitor : IImageFrameVisitor + where TPixelA : unmanaged, IPixel + { + private readonly ImageFrame expected; + private readonly ImageFrame actual; + + public ActualFrameVisitor(ImageFrame expected, ImageFrame actual) + { + this.expected = expected; + this.actual = actual; + } + + public Image? DifferenceImage { get; private set; } + + public void Visit(ImageFrame actual) + where TPixelB : unmanaged, IPixel + => this.DifferenceImage = ImageComparisonEngine.CreateDifferenceImage(this.expected, actual); + } +} diff --git a/src/ImageSharp/Comparison/TolerantImageComparer.cs b/src/ImageSharp/Comparison/TolerantImageComparer.cs new file mode 100644 index 0000000000..42ebc27b40 --- /dev/null +++ b/src/ImageSharp/Comparison/TolerantImageComparer.cs @@ -0,0 +1,66 @@ +// Copyright (c) Six Labors. +// Licensed under the Six Labors Split License. + +using SixLabors.ImageSharp.PixelFormats; + +namespace SixLabors.ImageSharp.Comparison; + +/// +/// An which tolerates a configurable amount of difference between +/// images and image frames. +/// +public class TolerantImageComparer : ImageComparer +{ + /// + /// Initializes a new instance of the class. + /// + /// + /// The maximal tolerated difference represented by a value between 0.0 and 1.0 scaled to 0 and 65535. + /// + /// + /// The threshold of the individual pixels before they accumulate towards the overall difference. + /// Floating-point component differences are expressed in sixteen-bit units to retain existing + /// threshold values. The value is the sum of the absolute component differences: + /// . + /// + public TolerantImageComparer(float imageThreshold, int perPixelManhattanThreshold = 0) + { + Guard.MustBeGreaterThanOrEqualTo(imageThreshold, 0, nameof(imageThreshold)); + + this.ImageThreshold = imageThreshold; + this.PerPixelManhattanThreshold = perPixelManhattanThreshold; + } + + /// + /// + /// Gets the maximal tolerated difference represented by a value between 0.0 and 1.0 scaled to 0 and 65535. + /// Examples of percentage differences on a single pixel: + /// 1. PixelA = (65535,65535,65535,0) PixelB =(0,0,0,65535) leads to 100% difference on a single pixel + /// 2. PixelA = (65535,65535,65535,0) PixelB =(65535,65535,65535,65535) leads to 25% difference on a single pixel + /// 3. PixelA = (65535,65535,65535,0) PixelB =(32767,32767,32767,32767) leads to 50% difference on a single pixel + /// + /// + /// The total differences is the sum of all pixel differences normalized by image dimensions! + /// The individual distances are calculated using the Manhattan function: + /// + /// ImageThresholdInPercents = 1/255 = 257/65535 means that we allow one unit difference per channel on a 1x1 image + /// ImageThresholdInPercents = 1/(100*100*255) = 257/(100*100*65535) means that we allow only one unit difference per channel on a 100x100 image + /// + /// + public float ImageThreshold { get; } + + /// + /// Gets the threshold of the individual pixels before they accumulate towards the overall difference. + /// Floating-point component differences are expressed in sixteen-bit units to retain existing threshold values. + /// The value is the sum of the absolute component differences: + /// + /// + public int PerPixelManhattanThreshold { get; } + + /// + internal override ImageSimilarityReport CompareImagesOrFramesCore( + int index, + ImageFrame expected, + ImageFrame actual) + => ImageComparisonEngine.CompareFrames(index, expected, actual, this.ImageThreshold, this.PerPixelManhattanThreshold); +} diff --git a/tests/ImageSharp.Tests/Comparison/ImageComparerTests.cs b/tests/ImageSharp.Tests/Comparison/ImageComparerTests.cs new file mode 100644 index 0000000000..11d7753e92 --- /dev/null +++ b/tests/ImageSharp.Tests/Comparison/ImageComparerTests.cs @@ -0,0 +1,276 @@ +// Copyright (c) Six Labors. +// Licensed under the Six Labors Split License. + +using SixLabors.ImageSharp.Comparison; +using SixLabors.ImageSharp.Comparison.Exceptions; +using SixLabors.ImageSharp.Memory; +using SixLabors.ImageSharp.PixelFormats; + +namespace SixLabors.ImageSharp.Tests.Comparison; + +[Trait("Category", "Comparison")] +public class ImageComparerTests +{ + private static readonly Rgba32 Black = new(0, 0, 0, 255); + + [Fact] + public void IdenticalImagesAreEmpty() + { + using Image expected = new(3, 2, Black); + using Image actual = new(3, 2, Black); + + ImageComparer comparer = ImageComparer.Exact; + ImageSimilarityReport report = comparer.CompareImagesOrFrames(expected, actual); + + Assert.True(report.IsEmpty); + Assert.Equal(0F, report.TotalNormalizedDifference); + Assert.Equal("0%", report.DifferencePercentageString); + Assert.Equal("[SimilarImages]", report.ToString()); + Assert.Equal(0, report.Index); + Assert.Equal(expected.Frames.RootFrame, report.ExpectedImageFrame); + Assert.Equal(actual.Frames.RootFrame, report.ActualImageFrame); + } + + [Fact] + public void ExactComparerReportsOneUnitDifference() + { + using Image expected = new(1, 2, Black); + using Image actual = new(1, 2, Black); + actual.Frames.RootFrame.PixelBuffer.DangerousGetRowSpan(0)[0] = new Rgba32(1, 0, 0, 255); + + ImageComparer comparer = ImageComparer.Exact; + ImageSimilarityReport report = comparer.CompareImagesOrFrames(expected, actual); + + Assert.False(report.IsEmpty); + + // One eight-bit unit difference on one pixel of a two-pixel image: + // one unit equals 257 sixteen-bit units, normalized by width * height * 4 * 65535. + float expectedDifference = 257F / (1 * 2 * 4 * 65535F); + Assert.True(MathF.Abs(report.TotalNormalizedDifference - expectedDifference) < 1e-6F); + Assert.Equal("0.0490%", report.DifferencePercentageString); + Assert.Contains("Total difference:", report.ToString()); + } + + [Fact] + public void TolerantComparerSkipsDifferencesBelowPerPixelThreshold() + { + using Image expected = new(4, 4, Black); + using Image actual = new(4, 4, Black); + actual.Frames.RootFrame.PixelBuffer.DangerousGetRowSpan(2)[1] = new Rgba32(1, 0, 0, 255); + + // The per-pixel manhattan difference of one eight-bit unit is about 257 sixteen-bit units, + // so a threshold above that skips the pixel from the total difference. + ImageComparer comparer = ImageComparer.Tolerant(0, perPixelManhattanThreshold: 260); + ImageSimilarityReport report = comparer.CompareImagesOrFrames(expected, actual); + + Assert.True(report.IsEmpty); + } + + [Fact] + public void TolerantComparerAccumulatesDifferencesOverPerPixelThreshold() + { + using Image expected = new(4, 4, Black); + using Image actual = new(4, 4, Black); + actual.Frames.RootFrame.PixelBuffer.DangerousGetRowSpan(2)[1] = new Rgba32(2, 0, 0, 255); + + ImageComparer comparer = ImageComparer.Tolerant(0, perPixelManhattanThreshold: 260); + ImageSimilarityReport report = comparer.CompareImagesOrFrames(expected, actual); + + Assert.False(report.IsEmpty); + } + + [Fact] + public void TolerantComparerDefaultThresholdAllowsOneUnitDifferenceOnLargeImage() + { + using Image expected = new(100, 100, Black); + using Image actual = new(100, 100, Black); + actual.Frames.RootFrame.PixelBuffer.DangerousGetRowSpan(42)[37] = new Rgba32(1, 0, 0, 255); + + ImageComparer comparer = ImageComparer.Tolerant(); + ImageSimilarityReport report = comparer.CompareImagesOrFrames(expected, actual); + + Assert.True(report.IsEmpty); + } + + [Fact] + public void TolerantPercentageComparerMatchesThresholdSemantics() + { + using Image expected = new(1, 1, Black); + using Image actual = new(1, 1, Black); + actual.Frames.RootFrame.PixelBuffer.DangerousGetRowSpan(0)[0] = new Rgba32(1, 0, 0, 255); + + // One eight-bit unit difference on a single pixel is a difference of about 0.098%. + ImageComparer belowThreshold = ImageComparer.TolerantPercentage(1F); + ImageSimilarityReport emptyReport = belowThreshold.CompareImagesOrFrames(expected, actual); + Assert.True(emptyReport.IsEmpty); + + ImageComparer overThreshold = ImageComparer.TolerantPercentage(0.05F); + ImageSimilarityReport report = overThreshold.CompareImagesOrFrames(expected, actual); + Assert.False(report.IsEmpty); + } + + [Fact] + public void DimensionMismatchThrows() + { + using Image expected = new(2, 2, Black); + using Image actual = new(2, 3, Black); + + ImageComparer comparer = ImageComparer.Exact; + + ImageDimensionsMismatchException exception = + Assert.Throws(() => comparer.CompareImagesOrFrames(expected, actual)); + + Assert.Equal(new Size(2, 2), exception.ExpectedSize); + Assert.Equal(new Size(2, 3), exception.ActualSize); + } + + [Fact] + public void FrameCountMismatchThrows() + { + using Image expected = new(2, 1, Black); + using Image actual = new(2, 1, Black); + actual.Frames.CreateFrame(Black); + + ImageComparer comparer = ImageComparer.Exact; + + ImageFramesMismatchException exception = + Assert.Throws(() => comparer.CompareImages(expected, actual)); + + Assert.Equal(1, exception.ExpectedCount); + Assert.Equal(2, exception.ActualCount); + } + + [Fact] + public void VerifySimilarityPassesOnIdenticalImages() + { + using Image expected = new(2, 2, Black); + using Image actual = new(2, 2, Black); + + ImageComparer.Exact.VerifySimilarity(expected, actual); + } + + [Fact] + public void VerifySimilarityThrowsOnDifference() + { + using Image expected = new(1, 2, Black); + using Image actual = new(1, 2, Black); + actual.Frames.RootFrame.PixelBuffer.DangerousGetRowSpan(1)[0] = new Rgba32(1, 0, 0, 255); + + ImageDifferenceIsOverThresholdException exception = + Assert.Throws(() => ImageComparer.Exact.VerifySimilarity(expected, actual)); + + Assert.Single(exception.Reports); + Assert.Equal(0, exception.Reports[0].Index); + Assert.False(exception.Reports[0].IsEmpty); + Assert.Contains("Image difference is over threshold!", exception.Message); + } + + [Fact] + public void CompareImagesReportsFrameIndices() + { + Rgba32 backgroundColor = new(10, 20, 30, 255); + using Image expected = new(2, 1, backgroundColor); + expected.Frames.CreateFrame(backgroundColor); + + using Image actual = new(2, 1, backgroundColor); + actual.Frames.CreateFrame(backgroundColor); + + // Only the root frame differs; the second frame matches. + actual.Frames.RootFrame.PixelBuffer.DangerousGetRowSpan(0)[0] = new Rgba32(11, 20, 30, 255); + + IReadOnlyList reports = ImageComparer.Exact.CompareImages(expected, actual); + + Assert.Single(reports); + Assert.Equal(0, reports[0].Index); + } + + [Fact] + public void DifferenceImageOfIdenticalImagesIsMidGray() + { + using Image expected = new(3, 2, Black); + using Image actual = new(3, 2, Black); + + ImageSimilarityReport report = ImageComparer.Exact.CompareImagesOrFrames(expected, actual); + using Image differenceImage = report.CreateDifferenceImage(); + + Image difference = Assert.IsType>(differenceImage); + Buffer2D buffer = difference.Frames.RootFrame.PixelBuffer; + for (int y = 0; y < difference.Height; y++) + { + Span row = buffer.DangerousGetRowSpan(y); + for (int x = 0; x < difference.Width; x++) + { + Assert.Equal(new Rgba32(128, 128, 128, 255), row[x]); + } + } + } + + [Fact] + public void DifferenceImageEncodesComponentDirection() + { + using Image expected = new(1, 2, Black); + expected.Frames.RootFrame.PixelBuffer.DangerousGetRowSpan(1)[0] = new Rgba32(10, 5, 0, 255); + + using Image actual = new(1, 2, Black); + actual.Frames.RootFrame.PixelBuffer.DangerousGetRowSpan(0)[0] = new Rgba32(10, 0, 0, 255); + actual.Frames.RootFrame.PixelBuffer.DangerousGetRowSpan(1)[0] = new Rgba32(0, 5, 20, 255); + + ImageSimilarityReport report = ImageComparer.Exact.CompareImagesOrFrames(expected, actual); + using Image differenceImage = report.CreateDifferenceImage(); + + Image difference = Assert.IsType>(differenceImage); + Buffer2D buffer = difference.Frames.RootFrame.PixelBuffer; + + // The red component of the actual image is above the expected one, rendered as white; + // the equal green and blue components are rendered as mid-gray. + Assert.Equal(new Rgba32(255, 128, 128, 255), buffer.DangerousGetRowSpan(0)[0]); + + // The red component of the actual image is below the expected one, rendered as black; + // the blue component of the actual image is above the expected one, rendered as white. + Assert.Equal(new Rgba32(0, 128, 255, 255), buffer.DangerousGetRowSpan(1)[0]); + } + + [Fact] + public void ComparisonWorksThroughNonGenericImages() + { + using Image expectedImage = new(1, 2, Black); + using Image actualImage = new(1, 2, Black); + actualImage.Frames.RootFrame.PixelBuffer.DangerousGetRowSpan(0)[0] = new Rgba32(0, 0, 1, 255); + + // Both images are passed through their non-generic base type, so the pixel types are + // resolved by double dispatch at run time. + Image expected = expectedImage; + Image actual = actualImage; + + ImageComparer comparer = ImageComparer.Exact; + ImageSimilarityReport report = comparer.CompareImagesOrFrames(expected, actual); + + Assert.False(report.IsEmpty); + + using Image differenceImage = report.CreateDifferenceImage(); + Assert.IsType>(differenceImage); + } + + [Fact] + public void ComparisonSupportsMixedPixelFormats() + { + using Image expected = new(1, 2, new Rgba32(255, 0, 0, 255)); + using Image actual = new(1, 2, new Rgb24(255, 0, 0)); + + // The formats store identical RGB components and both convert to alpha 1, so the images match. + ImageSimilarityReport emptyReport = ImageComparer.Exact.CompareImagesOrFrames(expected, actual); + Assert.True(emptyReport.IsEmpty); + + actual.Frames.RootFrame.PixelBuffer.DangerousGetRowSpan(1)[0] = new Rgb24(128, 0, 0); + + ImageSimilarityReport report = ImageComparer.Exact.CompareImagesOrFrames(expected, actual); + Assert.False(report.IsEmpty); + + using Image differenceImage = report.CreateDifferenceImage(); + Image difference = Assert.IsType>(differenceImage); + Buffer2D buffer = difference.Frames.RootFrame.PixelBuffer; + + // The red component of the actual image is below the expected one, rendered as black. + Assert.Equal(new Rgba32(0, 128, 128, 255), buffer.DangerousGetRowSpan(1)[0]); + } +}