Refactored the compare method of MagickImage that required the diff image as an argument and changed that to a return value.

Author: dlemstra

src/Magick.NET.Core/IMagickImage.cs

@@ -837,27 +837,6 @@ public partial interface IMagickImage : IDisposable
     /// <exception cref="MagickException">Thrown when an error is raised by ImageMagick.</exception>
     double Compare(IMagickImage image, ErrorMetric metric, Channels channels);
 
-    /// <summary>
-    /// Returns the distortion based on the specified metric.
-    /// </summary>
-    /// <param name="image">The other image to compare with this image.</param>
-    /// <param name="metric">The metric to use.</param>
-    /// <param name="difference">The image that will contain the difference.</param>
-    /// <returns>The distortion based on the specified metric.</returns>
-    /// <exception cref="MagickException">Thrown when an error is raised by ImageMagick.</exception>
-    double Compare(IMagickImage image, ErrorMetric metric, IMagickImage difference);
-
-    /// <summary>
-    /// Returns the distortion based on the specified metric.
-    /// </summary>
-    /// <param name="image">The other image to compare with this image.</param>
-    /// <param name="metric">The metric to use.</param>
-    /// <param name="difference">The image that will contain the difference.</param>
-    /// <param name="channels">The channel(s) to compare.</param>
-    /// <returns>The distortion based on the specified metric.</returns>
-    /// <exception cref="MagickException">Thrown when an error is raised by ImageMagick.</exception>
-    double Compare(IMagickImage image, ErrorMetric metric, IMagickImage difference, Channels channels);
-
     /// <summary>
     /// Compose an image onto another at specified offset using the 'In' operator.
     /// </summary>

src/Magick.NET.Core/IMagickImage{TQuantumType}.cs

@@ -102,26 +102,47 @@ public partial interface IMagickImage<TQuantumType> : IMagickImage, IComparable<
     /// <param name="stopColor">The stop color of the color range.</param>
     void ColorThreshold(IMagickColor<TQuantumType> startColor, IMagickColor<TQuantumType> stopColor);
 
+    /// <summary>
+    /// Returns the distortion based on the specified metric.
+    /// </summary>
+    /// <param name="image">The other image to compare with this image.</param>
+    /// <param name="metric">The metric to use.</param>
+    /// <param name="distortion">The distortion based on the specified metric.</param>
+    /// <returns>The image that contains the difference.</returns>
+    /// <exception cref="MagickException">Thrown when an error is raised by ImageMagick.</exception>
+    IMagickImage<TQuantumType> Compare(IMagickImage image, ErrorMetric metric, out double distortion);
+
+    /// <summary>
+    /// Returns the distortion based on the specified metric.
+    /// </summary>
+    /// <param name="image">The other image to compare with this image.</param>
+    /// <param name="metric">The metric to use.</param>
+    /// <param name="channels">The channel(s) to compare.</param>
+    /// <param name="distortion">The distortion based on the specified metric.</param>
+    /// <returns>The image that contains the difference.</returns>
+    /// <exception cref="MagickException">Thrown when an error is raised by ImageMagick.</exception>
+    IMagickImage<TQuantumType> Compare(IMagickImage image, ErrorMetric metric, Channels channels, out double distortion);
+
     /// <summary>
     /// Returns the distortion based on the specified metric.
     /// </summary>
     /// <param name="image">The other image to compare with this image.</param>
     /// <param name="settings">The settings to use.</param>
-    /// <param name="difference">The image that will contain the difference.</param>
-    /// <returns>The distortion based on the specified metric.</returns>
+    /// <param name="distortion">The distortion based on the specified metric.</param>
+    /// <returns>The image that contains the difference.</returns>
     /// <exception cref="MagickException">Thrown when an error is raised by ImageMagick.</exception>
-    double Compare(IMagickImage image, ICompareSettings<TQuantumType> settings, IMagickImage difference);
+    IMagickImage<TQuantumType> Compare(IMagickImage image, ICompareSettings<TQuantumType> settings, out double distortion);
 
     /// <summary>
     /// Returns the distortion based on the specified metric.
     /// </summary>
     /// <param name="image">The other image to compare with this image.</param>
     /// <param name="settings">The settings to use.</param>
-    /// <param name="difference">The image that will contain the difference.</param>
     /// <param name="channels">The channel(s) to compare.</param>
-    /// <returns>The distortion based on the specified metric.</returns>
+    /// <param name="distortion">The distortion based on the specified metric.</param>
+    /// <returns>The image that contains the difference.</returns>
     /// <exception cref="MagickException">Thrown when an error is raised by ImageMagick.</exception>
-    double Compare(IMagickImage image, ICompareSettings<TQuantumType> settings, IMagickImage difference, Channels channels);
+    IMagickImage<TQuantumType> Compare(IMagickImage image, ICompareSettings<TQuantumType> settings, Channels channels, out double distortion);
 
     /// <summary>
     /// Determines the connected-components of the image.

src/Magick.NET/MagickImage.cs

@@ -1729,64 +1729,57 @@ public double Compare(IMagickImage image, ErrorMetric metric, Channels channels)
     /// Returns the distortion based on the specified metric.
     /// </summary>
     /// <param name="image">The other image to compare with this image.</param>
-    /// <param name="settings">The settings to use.</param>
-    /// <param name="difference">The image that will contain the difference.</param>
-    /// <returns>The distortion based on the specified metric.</returns>
+    /// <param name="metric">The metric to use.</param>
+    /// <param name="distortion">The distortion based on the specified metric.</param>
+    /// <returns>The image that contains the difference.</returns>
     /// <exception cref="MagickException">Thrown when an error is raised by ImageMagick.</exception>
-    public double Compare(IMagickImage image, ICompareSettings<QuantumType> settings, IMagickImage difference)
-        => Compare(image, settings, difference, ImageMagick.Channels.Undefined);
+    public IMagickImage<QuantumType> Compare(IMagickImage image, ErrorMetric metric, out double distortion)
+        => Compare(image, metric, ImageMagick.Channels.Undefined, out distortion);
 
     /// <summary>
     /// Returns the distortion based on the specified metric.
     /// </summary>
     /// <param name="image">The other image to compare with this image.</param>
     /// <param name="metric">The metric to use.</param>
-    /// <param name="difference">The image that will contain the difference.</param>
-    /// <returns>The distortion based on the specified metric.</returns>
+    /// <param name="channels">The channel(s) to compare.</param>
+    /// <param name="distortion">The distortion based on the specified metric.</param>
+    /// <returns>The image that contains the difference.</returns>
     /// <exception cref="MagickException">Thrown when an error is raised by ImageMagick.</exception>
-    public double Compare(IMagickImage image, ErrorMetric metric, IMagickImage difference)
-        => Compare(image, metric, difference, ImageMagick.Channels.Undefined);
+    public IMagickImage<QuantumType> Compare(IMagickImage image, ErrorMetric metric, Channels channels, out double distortion)
+        => Compare(image, new CompareSettings { Metric = metric }, channels, out distortion);
 
     /// <summary>
     /// Returns the distortion based on the specified metric.
     /// </summary>
     /// <param name="image">The other image to compare with this image.</param>
-    /// <param name="metric">The metric to use.</param>
-    /// <param name="difference">The image that will contain the difference.</param>
-    /// <param name="channels">The channel(s) to compare.</param>
-    /// <returns>The distortion based on the specified metric.</returns>
+    /// <param name="settings">The settings to use.</param>
+    /// <param name="distortion">The distortion based on the specified metric.</param>
+    /// <returns>The image that contains the difference.</returns>
     /// <exception cref="MagickException">Thrown when an error is raised by ImageMagick.</exception>
-    public double Compare(IMagickImage image, ErrorMetric metric, IMagickImage difference, Channels channels)
-        => Compare(image, new CompareSettings { Metric = metric }, difference, channels);
+    public IMagickImage<QuantumType> Compare(IMagickImage image, ICompareSettings<QuantumType> settings, out double distortion)
+        => Compare(image, settings, ImageMagick.Channels.Undefined, out distortion);
 
     /// <summary>
     /// Returns the distortion based on the specified metric.
     /// </summary>
     /// <param name="image">The other image to compare with this image.</param>
     /// <param name="settings">The settings to use.</param>
-    /// <param name="difference">The image that will contain the difference.</param>
     /// <param name="channels">The channel(s) to compare.</param>
-    /// <returns>The distortion based on the specified metric.</returns>
+    /// <param name="distortion">The distortion based on the specified metric.</param>
+    /// <returns>The image that contains the difference.</returns>
     /// <exception cref="MagickException">Thrown when an error is raised by ImageMagick.</exception>
-    public double Compare(IMagickImage image, ICompareSettings<QuantumType> settings, IMagickImage difference, Channels channels)
+    public IMagickImage<QuantumType> Compare(IMagickImage image, ICompareSettings<QuantumType> settings, Channels channels, out double distortion)
     {
         Throw.IfNull(nameof(image), image);
         Throw.IfNull(nameof(settings), settings);
-        Throw.IfNull(nameof(difference), difference);
-
-        if (difference is not MagickImage differenceImage)
-            throw new NotSupportedException();
 
         using var temporaryDefines = new TemporaryDefines(this);
         temporaryDefines.SetArtifact("compare:highlight-color", settings.HighlightColor);
         temporaryDefines.SetArtifact("compare:lowlight-color", settings.LowlightColor);
         temporaryDefines.SetArtifact("compare:masklight-color", settings.MasklightColor);
 
-        var result = _nativeInstance.Compare(image, settings.Metric, channels, out var distortion);
-        if (result != IntPtr.Zero)
-            differenceImage._nativeInstance.Instance = result;
-
-        return distortion;
+        var result = _nativeInstance.Compare(image, settings.Metric, channels, out distortion);
+        return Create(result, _settings);
     }
 
     /// <summary>

tests/Magick.NET.Tests/MagickImageTests/TheCompareMethod.cs

@@ -43,35 +43,16 @@ public void ShouldThrowAnExceptionWhenImageIsNullAndErrorMetricIsSpecified()
         public void ShouldThrowAnExceptionWhenImageIsNullAndSettingsAreNotNull()
         {
             using var image = new MagickImage();
-            using var diff = new MagickImage();
 
-            Assert.Throws<ArgumentNullException>("image", () => image.Compare(null, new CompareSettings(), diff));
+            Assert.Throws<ArgumentNullException>("image", () => image.Compare(null, new CompareSettings(), out var distortion));
         }
 
         [Fact]
         public void ShouldThrowAnExceptionWhenSettingsIsNull()
         {
             using var image = new MagickImage();
-            using var diff = new MagickImage();
-
-            Assert.Throws<ArgumentNullException>("settings", () => image.Compare(image, null, diff));
-        }
-
-        [Fact]
-        public void ShouldThrowAnExceptionWhenDifferenceIsNull()
-        {
-            using var image = new MagickImage();
-
-            Assert.Throws<ArgumentNullException>("difference", () => image.Compare(image, new CompareSettings(), null));
-        }
-
-        [Fact]
-        public void ShouldThrowAnExceptionWhenDifferenceIsNotMagickImage()
-        {
-            using var image = new MagickImage();
-            var diff = Substitute.For<IMagickImage<QuantumType>>();
 
-            Assert.Throws<NotSupportedException>(() => image.Compare(image, new CompareSettings(), diff));
+            Assert.Throws<ArgumentNullException>("settings", () => image.Compare(image, null, out var distortion));
         }
 
         [Fact]
@@ -97,8 +78,7 @@ public void ShouldReturnZeroWhenTheImagesAreEqual()
 
             using var image = new MagickImage(Files.Builtin.Logo);
             using var other = new MagickImage(Files.Builtin.Logo);
-            using var diff = new MagickImage();
-            var result = image.Compare(other, settings, diff);
+            using var diff = image.Compare(other, settings, out var result);
 
             Assert.Equal(0, result);
         }
@@ -108,8 +88,7 @@ public void ShouldReturnZeroWhenTheImagesAreEqualAndErrorMetricIsRootMeanSquared
         {
             using var image = new MagickImage(Files.Builtin.Logo);
             using var other = new MagickImage(Files.Builtin.Logo);
-            using var diff = new MagickImage();
-            var result = image.Compare(other, ErrorMetric.RootMeanSquared, diff);
+            using var diff = image.Compare(other, ErrorMetric.RootMeanSquared, out var result);
 
             Assert.Equal(0, result);
         }
@@ -150,8 +129,7 @@ public void ShouldReturnNonZeroValueWhenTheImagesAreNotEqual()
             using var other = new MagickImage(Files.Builtin.Logo);
             other.Rotate(180);
 
-            using var diff = new MagickImage();
-            var result = image.Compare(other, settings, diff);
+            using var diff = image.Compare(other, settings, out var result);
 
             Assert.InRange(result, 0.36, 0.37);
             ColorAssert.Equal(MagickColors.Yellow, diff, 150, 50);
@@ -164,9 +142,8 @@ public void ShouldUseTheColorFuzz()
         {
             using var image = new MagickImage(new MagickColor("#f1d3bc"), 1, 1);
             using var other = new MagickImage(new MagickColor("#24292e"), 1, 1);
-            using var diff = new MagickImage();
             image.ColorFuzz = new Percentage(81);
-            var result = image.Compare(other, ErrorMetric.Absolute, diff);
+            using var diff = image.Compare(other, ErrorMetric.Absolute, out var result);
 
             Assert.Equal(0, result);
             ColorAssert.Equal(new MagickColor("#fd2ff729f28b"), diff, 0, 0);