Improves image testing and test output directories

- No longer uses random directories for test output
- No longer places file output for tests in deploy directory (it is now placed in the MSTest standard results directory `TestResults` which is a sibling of the solution)
- OutputDirectoryTest will now place test output in a folder named after the class being tests (named `ClassOutputDirectory`)
- OutputDirectoryTest  will now place test output for individual tests first in a folder named after the test class, and second in a subfolder for the specific test (named TestOutputDirectory`)
- It is hoped we'll move more to using ClassOutputDirectory over TestOutputDirectory as it will reduce IO and folder spam
- MSTest automatically deletes output when all tests pass, so removed the MSBuild task that did extra cleaning of binary output directory (because we used to stick output in there when we should not have)
- Added an `GeneratedImageTest` that inherits from `OutputDirectoryTest` (and all the aforementioned new behaviours). GeneratedImageTest is a helper class that will automatically name and save both actual and expected test images, as  well as produce delta images that show where pixels differ between actual and expected!
- We also add delta image processors and pixel blender to power aforementioned delta image functionality

AudioAnalysis.sln.DotSettings

@@ -4,6 +4,7 @@
 	<s:Boolean x:Key="/Default/CodeInspection/Highlighting/ReadSettingsFromFileLevel/@EntryValue">True</s:Boolean>
 	<s:String x:Key="/Default/CodeStyle/CodeFormatting/CSharpCodeStyle/ThisQualifier/INSTANCE_MEMBERS_QUALIFY_MEMBERS/@EntryValue">15</s:String>
 	<s:Int64 x:Key="/Default/CodeStyle/CodeFormatting/CSharpFormat/BLANK_LINES_BEFORE_SINGLE_LINE_COMMENT/@EntryValue">1</s:Int64>
+	<s:Boolean x:Key="/Default/CodeStyle/CodeFormatting/CSharpFormat/KEEP_EXISTING_INVOCATION_PARENS_ARRANGEMENT/@EntryValue">False</s:Boolean>
 	<s:Int64 x:Key="/Default/CodeStyle/CodeFormatting/CSharpFormat/MAX_ARRAY_INITIALIZER_ELEMENTS_ON_LINE/@EntryValue">1</s:Int64>
 	<s:Int64 x:Key="/Default/CodeStyle/CodeFormatting/CSharpFormat/MAX_FORMAL_PARAMETERS_ON_LINE/@EntryValue">9999</s:Int64>
 	<s:Int64 x:Key="/Default/CodeStyle/CodeFormatting/CSharpFormat/MAX_INITIALIZER_ELEMENTS_ON_LINE/@EntryValue">1</s:Int64>
@@ -13,6 +14,9 @@
 	<s:Boolean x:Key="/Default/CodeStyle/CodeFormatting/CSharpFormat/SPACE_AFTER_TYPECAST_PARENTHESES/@EntryValue">False</s:Boolean>
 	<s:Boolean x:Key="/Default/CodeStyle/CodeFormatting/CSharpFormat/SPACE_WITHIN_SINGLE_LINE_ARRAY_INITIALIZER_BRACES/@EntryValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/CodeStyle/CodeFormatting/CSharpFormat/STICK_COMMENT/@EntryValue">False</s:Boolean>
+	<s:Boolean x:Key="/Default/CodeStyle/CodeFormatting/CSharpFormat/WRAP_AFTER_INVOCATION_LPAR/@EntryValue">True</s:Boolean>
+	<s:String x:Key="/Default/CodeStyle/CodeFormatting/CSharpFormat/WRAP_ARGUMENTS_STYLE/@EntryValue">CHOP_IF_LONG</s:String>
+
 
 
 	<s:String x:Key="/Default/CodeStyle/CSharpFileLayoutPatterns/Pattern/@EntryValue">&lt;?xml version="1.0" encoding="utf-16"?&gt;&#xD;
@@ -194,6 +198,7 @@
 	<s:Boolean x:Key="/Default/CodeStyle/CSharpUsing/AddImportsToDeepestScope/@EntryValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/CodeStyle/CSharpUsing/QualifiedUsingAtNestedScope/@EntryValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/CodeStyle/EditorConfig/EnableStyleCopSupport/@EntryValue">True</s:Boolean>
+	<s:String x:Key="/Default/CodeStyle/Naming/CSharpNaming/Abbreviations/=AA/@EntryIndexedValue">AA</s:String>
 	<s:String x:Key="/Default/CodeStyle/Naming/CSharpNaming/Abbreviations/=XY/@EntryIndexedValue">XY</s:String>
 	<s:String x:Key="/Default/CodeStyle/Naming/CSharpNaming/PredefinedNamingRules/=PrivateInstanceFields/@EntryIndexedValue">&lt;Policy Inspect="True" Prefix="" Suffix="" Style="aaBb" /&gt;</s:String>
 	<s:String x:Key="/Default/CodeStyle/Naming/CSharpNaming/PredefinedNamingRules/=PrivateStaticFields/@EntryIndexedValue">&lt;Policy Inspect="True" Prefix="" Suffix="" Style="aaBb" /&gt;</s:String>

src/Acoustics.Shared/Extensions/FileInfoExtensions.cs

@@ -67,6 +67,16 @@ public static FileInfo CombineFile(this DirectoryInfo directoryInfo, params stri
             return new FileInfo(merged);
         }
 
+        public static string CombinePath(this DirectoryInfo directoryInfo, params string[] str)
+        {
+            Contract.Requires(directoryInfo != null);
+            Contract.Requires(str != null && str.Length > 0);
+
+            string merged = Path.Combine(str.Prepend(directoryInfo.FullName).ToArray());
+
+            return merged;
+        }
+
         public static FileInfo ToFileInfo(this string str)
         {
             if (string.IsNullOrWhiteSpace(str))
@@ -87,6 +97,16 @@ public static DirectoryInfo ToDirectoryInfo(this string str)
             return new DirectoryInfo(str);
         }
 
+        public static DirectoryInfo ToDirectoryInfo(this string str, params string[] subDirectories)
+        {
+            if (string.IsNullOrWhiteSpace(str))
+            {
+                return null;
+            }
+
+            return new DirectoryInfo(Path.Combine(subDirectories.Prepend(str).ToArray()));
+        }
+
         public static bool TryDelete(this FileSystemInfo file, string message = "")
         {
             return TryDelete(file, false, message);

src/Acoustics.Shared/Extensions/MathExtensions.cs

@@ -5,18 +5,148 @@
 // ReSharper disable once CheckNamespace
 namespace System
 {
+    // ReSharper disable once CheckNamespace
+
     using System.Linq;
+    using System.Runtime.CompilerServices;
 
-    public static class Maths
+    public static class MathExtensions
     {
-        public static T Min<T>(params T[] vals)
+
+        public static T Min<T>(params T[] values)
+        {
+            return values.Min();
+        }
+
+        public static T Max<T>(params T[] values)
+        {
+            return values.Max();
+        }
+
+        /// <summary>
+        /// Restricts a <see cref="byte"/> to be within a specified range.
+        /// </summary>
+        /// <param name="value">The The value to clamp.</param>
+        /// <param name="min">The minimum value. If value is less than min, min will be returned.</param>
+        /// <param name="max">The maximum value. If value is greater than max, max will be returned.</param>
+        /// <returns>
+        /// The <see cref="byte"/> representing the clamped value.
+        /// </returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static byte Clamp(this byte value, byte min, byte max)
         {
-            return vals.Min();
+            // Order is important here as someone might set min to higher than max.
+            if (value >= max)
+            {
+                return max;
+            }
+
+            if (value <= min)
+            {
+                return min;
+            }
+
+            return value;
         }
 
-        public static T Max<T>(params T[] vals)
+        /// <summary>
+        /// Restricts a <see cref="uint"/> to be within a specified range.
+        /// </summary>
+        /// <param name="value">The The value to clamp.</param>
+        /// <param name="min">The minimum value. If value is less than min, min will be returned.</param>
+        /// <param name="max">The maximum value. If value is greater than max, max will be returned.</param>
+        /// <returns>
+        /// The <see cref="int"/> representing the clamped value.
+        /// </returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static uint Clamp(this uint value, uint min, uint max)
         {
-            return vals.Max();
+            if (value >= max)
+            {
+                return max;
+            }
+
+            if (value <= min)
+            {
+                return min;
+            }
+
+            return value;
+        }
+
+        /// <summary>
+        /// Restricts a <see cref="int"/> to be within a specified range.
+        /// </summary>
+        /// <param name="value">The The value to clamp.</param>
+        /// <param name="min">The minimum value. If value is less than min, min will be returned.</param>
+        /// <param name="max">The maximum value. If value is greater than max, max will be returned.</param>
+        /// <returns>
+        /// The <see cref="int"/> representing the clamped value.
+        /// </returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static int Clamp(this int value, int min, int max)
+        {
+            if (value >= max)
+            {
+                return max;
+            }
+
+            if (value <= min)
+            {
+                return min;
+            }
+
+            return value;
+        }
+
+        /// <summary>
+        /// Restricts a <see cref="float"/> to be within a specified range.
+        /// </summary>
+        /// <param name="value">The The value to clamp.</param>
+        /// <param name="min">The minimum value. If value is less than min, min will be returned.</param>
+        /// <param name="max">The maximum value. If value is greater than max, max will be returned.</param>
+        /// <returns>
+        /// The <see cref="float"/> representing the clamped value.
+        /// </returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static float Clamp(this float value, float min, float max)
+        {
+            if (value >= max)
+            {
+                return max;
+            }
+
+            if (value <= min)
+            {
+                return min;
+            }
+
+            return value;
+        }
+
+        /// <summary>
+        /// Restricts a <see cref="double"/> to be within a specified range.
+        /// </summary>
+        /// <param name="value">The The value to clamp.</param>
+        /// <param name="min">The minimum value. If value is less than min, min will be returned.</param>
+        /// <param name="max">The maximum value. If value is greater than max, max will be returned.</param>
+        /// <returns>
+        /// The <see cref="double"/> representing the clamped value.
+        /// </returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static double Clamp(this double value, double min, double max)
+        {
+            if (value >= max)
+            {
+                return max;
+            }
+
+            if (value <= min)
+            {
+                return min;
+            }
+
+            return value;
         }
     }
-}
+}

src/Acoustics.Shared/Extensions/RangeExtensions.cs

@@ -130,8 +130,8 @@ public static Range<double> Multiply(this Range<double> rangeA, Range<double> ra
                 a2b2 = rangeA.Maximum * rangeB.Maximum;
 
             return new Range<double>(
-                Maths.Min(a1b1, a1b2, a2b1, a2b2),
-                Maths.Max(a1b1, a1b2, a2b1, a2b2),
+                MathExtensions.Min(a1b1, a1b2, a2b1, a2b2),
+                MathExtensions.Max(a1b1, a1b2, a2b1, a2b2),
                 rangeA.CombineTopology(rangeB));
         }
 

src/Acoustics.Shared/ImageSharp/DeltaImageProcessor.cs

@@ -0,0 +1,58 @@
+// <copyright file="DeltaImageProcessor.cs" company="QutEcoacoustics">
+// All code in this file and all associated files are the copyright and property of the QUT Ecoacoustics Research Group (formerly MQUTeR, and formerly QUT Bioacoustics Research Group).
+// </copyright>
+
+namespace Acoustics.Shared.ImageSharp
+{
+    using System;
+    using SixLabors.ImageSharp;
+    using SixLabors.ImageSharp.Advanced;
+    using SixLabors.ImageSharp.Advanced.ParallelUtils;
+    using SixLabors.ImageSharp.Memory;
+    using SixLabors.ImageSharp.PixelFormats;
+    using SixLabors.ImageSharp.Processing.Processors;
+
+    public class DeltaImageProcessor<TPixelBg, TPixelFg> : ImageProcessor<TPixelBg>
+        where TPixelBg : struct, IPixel<TPixelBg>
+        where TPixelFg : struct, IPixel<TPixelFg>
+    {
+        public DeltaImageProcessor(
+            Configuration configuration,
+            Image<TPixelFg> image,
+            Image<TPixelBg> source,
+            Rectangle sourceRectangle)
+            : base(configuration, source, sourceRectangle)
+        {
+            this.Image = image;
+            this.Blender = new DeltaPixelBlender<TPixelBg>();
+        }
+
+        public DeltaPixelBlender<TPixelBg> Blender { get; }
+
+        public Image<TPixelFg> Image { get; }
+
+        protected override void OnFrameApply(ImageFrame<TPixelBg> source)
+        {
+            var targetBounds = this.Image.Bounds();
+            var sourceBounds = this.Source.Bounds();
+            var maxWidth = Math.Min(targetBounds.Width, sourceBounds.Width);
+
+            void Apply(RowInterval rows)
+            {
+                for (int min = rows.Min; min < rows.Max; ++min)
+                {
+                    Span<TPixelBg> destination = source.GetPixelRowSpan<TPixelBg>(min).Slice(0, maxWidth);
+                    Span<TPixelFg> span = this.Image.GetPixelRowSpan<TPixelFg>(min).Slice(0, maxWidth);
+                    this.Blender.Blend<TPixelFg>(
+                        this.Configuration,
+                        destination,
+                        (ReadOnlySpan<TPixelBg>)destination,
+                        (ReadOnlySpan<TPixelFg>)span,
+                        1f);
+                }
+            }
+
+            ParallelHelper.IterateRows(this.SourceRectangle, this.Configuration, Apply);
+        }
+    }
+}

src/Acoustics.Shared/ImageSharp/DeltaImageProcessor{TPixelFg}.cs

@@ -0,0 +1,33 @@
+// <copyright file="DeltaImageProcessor{TPixelFg}.cs" company="QutEcoacoustics">
+// All code in this file and all associated files are the copyright and property of the QUT Ecoacoustics Research Group (formerly MQUTeR, and formerly QUT Bioacoustics Research Group).
+// </copyright>
+
+namespace Acoustics.Shared.ImageSharp
+{
+    using SixLabors.ImageSharp;
+    using SixLabors.ImageSharp.PixelFormats;
+    using SixLabors.ImageSharp.Processing.Processors;
+
+    public class DeltaImageProcessor<TPixelFg> : IImageProcessor
+        where TPixelFg : struct, IPixel<TPixelFg>
+    {
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DeltaImageProcessor{TPixelFg}"/> class.
+        /// </summary>
+        /// <param name="image">The image to blend.</param>
+        public DeltaImageProcessor(
+            Image<TPixelFg> image)
+        {
+            this.Image = image;
+        }
+
+        public Image<TPixelFg> Image { get; }
+
+        public IImageProcessor<TPixelBg> CreatePixelSpecificProcessor<TPixelBg>(Configuration configuration, Image<TPixelBg> source, Rectangle sourceRectangle)
+            where TPixelBg : struct, IPixel<TPixelBg>
+        {
+            return new DeltaImageProcessor<TPixelBg, TPixelFg>(Configuration.Default, this.Image, source, sourceRectangle);
+        }
+    }
+}

src/Acoustics.Shared/ImageSharp/DeltaPixelBlender.cs

@@ -0,0 +1,65 @@
+// <copyright file="DeltaPixelBlender.cs" company="QutEcoacoustics">
+// All code in this file and all associated files are the copyright and property of the QUT Ecoacoustics Research Group (formerly MQUTeR, and formerly QUT Bioacoustics Research Group).
+// </copyright>
+
+namespace Acoustics.Shared.ImageSharp
+{
+    using System;
+    using System.Numerics;
+    using System.Runtime.CompilerServices;
+    using SixLabors.ImageSharp.PixelFormats;
+
+    /// <summary>
+    /// Blends pixels based on their differences.
+    /// Pixels that are equal return gray.
+    /// Pixels where the source is less than backdrop return black.
+    /// Pixels where the source is greater than the backdrop return white.
+    /// </summary>
+    /// <typeparam name="TPixel">The type of pixel to operate on.</typeparam>
+    public class DeltaPixelBlender<TPixel> : PixelBlender<TPixel>
+        where TPixel : struct, IPixel<TPixel>
+    {
+        private static readonly Vector4 Middle = new Vector4(0.5f);
+        private static readonly Vector4 Bottom = new Vector4(0.0f);
+        private static readonly Vector4 Top = new Vector4(1.0f);
+
+        public override TPixel Blend(TPixel background, TPixel source, float amount)
+        {
+            TPixel dest = default;
+
+            dest.FromScaledVector4(Delta(background.ToScaledVector4(), source.ToScaledVector4(), amount));
+
+            return dest;
+        }
+
+        protected override void BlendFunction(Span<Vector4> destination, ReadOnlySpan<Vector4> background,
+            ReadOnlySpan<Vector4> source, float amount)
+        {
+            amount = amount.Clamp(0, 1);
+            for (int i = 0; i < destination.Length; i++)
+            {
+                destination[i] = Delta(background[i], source[i], amount);
+            }
+        }
+
+        protected override void BlendFunction(Span<Vector4> destination, ReadOnlySpan<Vector4> background,
+            ReadOnlySpan<Vector4> source, ReadOnlySpan<float> amount)
+        {
+            for (int i = 0; i < destination.Length; i++)
+            {
+                destination[i] = Delta(background[i], source[i], amount[i].Clamp(0, 1));
+            }
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        private static Vector4 Delta(Vector4 backdrop, Vector4 source, float amount)
+        {
+            if (backdrop == source)
+            {
+                return Middle;
+            }
+
+            return source.LengthSquared() < backdrop.LengthSquared() ? Bottom : Top;
+        }
+    }
+}

src/AnalysisPrograms/AnalysisPrograms.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
     <ProductVersion>9.0.30729</ProductVersion>
     <OutputType>Exe</OutputType>