Feature: adaptive histogram equalization (#673)

* first version of sliding window adaptive histogram equalization

* going now from top to bottom of the image, added more comments

* using memory allocator to create the histogram and the cdf

* mirroring rows which exceeds the borders

* mirroring also left and right borders

* gridsize and cliplimit are now parameters of the constructor

* using Parallel.For

* only applying clipping once, effect applying it multiple times is neglectable

* added abstract base class for histogram equalization, added option to enable / disable clipping

* small improvements

* clipLimit now in percent of the total number of pixels in the grid

* optimization: only calculating the cdf until the maximum histogram index

* fix: using configuration from the parameter instead of the default

* removed unnecessary loops in CalculateCdf, fixed typo in method name AddPixelsToHistogram

* added different approach for ahe: image is split up in tiles, cdf is computed for each tile. Grey value will be determined by interpolating between 4 tiles

* simplified interpolation between the tiles

* number of tiles is now fixed and depended on the width and height of the image

* moved calculating LUT's into separate method

* number of tiles is now part of the options and will be used with the sliding window approach also, so both methods are comparable

* removed no longer valid xml comment

* attempt fixing the borders

* refactoring to improve readability

* linear interpolation in the border tiles

* refactored processing the borders into separate methods

* fixing corner tiles

* fixed build errors

* fixing mistake during merge from upstream: setting test images to "update Resize reference output because of improved ResizeKernelMap calculations"

* using Parallel.ForEach for all inner tile calculations

* using Parallel.ForEach to calculate the lookup tables

* re-using pre allocated pixel row in GetPixelRow

* fixed issue with the border tiles, when tile width != tile height

* changed default value for ClipHistogram to false again

* alpha channel from the original image is now preserved

* added unit tests for adaptive histogram equalization

* Update External

* 2x faster adaptive tiled processor

* Remove double indexing and bounds checks

* Begin optimizing the global histogram

* Parallelize GlobalHistogramEqualizationProcessor

* Moving sliding window from left to right instead of from top to bottom

* The tile width and height is again depended on the image width: image.Width / Tiles

* Removed keeping track of the maximum histogram position

* Updated reference image for sliding window AHE for moving the sliding window from left to right

* Removed unnecessary call to Span.Clear(), all values are overwritten anyway

* Revert "Moving sliding window from left to right instead of from top to bottom"

This reverts commit 8f19e5e.

# Conflicts:
#	src/ImageSharp/Processing/Processors/Normalization/AdaptiveHistEqualizationSWProcessor.cs

* Split GetPixelRow in two version: one which mirrors the edges (only needed in the borders of the images) and one which does not

* Refactoring and cleanup sliding window processor

* Added an upper limit of 100 tiles

* Performance tweaks

* Update External

Author: brianpopow

src/ImageSharp/Common/Helpers/ImageMaths.cs

@@ -5,7 +5,6 @@
 using System.Runtime.CompilerServices;
 
 using SixLabors.ImageSharp.PixelFormats;
-using SixLabors.ImageSharp.Processing.Processors.Transforms;
 using SixLabors.Primitives;
 
 namespace SixLabors.ImageSharp

src/ImageSharp/Processing/HistogramEqualizationExtension.cs

@@ -12,25 +12,51 @@ namespace SixLabors.ImageSharp.Processing
     public static class HistogramEqualizationExtension
     {
         /// <summary>
-        /// Equalizes the histogram of an image to increases the global contrast using 65536 luminance levels.
+        /// Equalizes the histogram of an image to increases the contrast.
         /// </summary>
         /// <typeparam name="TPixel">The pixel format.</typeparam>
         /// <param name="source">The image this method extends.</param>
         /// <returns>The <see cref="Image{TPixel}"/>.</returns>
         public static IImageProcessingContext<TPixel> HistogramEqualization<TPixel>(this IImageProcessingContext<TPixel> source)
             where TPixel : struct, IPixel<TPixel>
-            => HistogramEqualization(source, 65536);
+            => HistogramEqualization(source, HistogramEqualizationOptions.Default);
 
         /// <summary>
-        /// Equalizes the histogram of an image to increases the global contrast.
+        /// Equalizes the histogram of an image to increases the contrast.
         /// </summary>
         /// <typeparam name="TPixel">The pixel format.</typeparam>
         /// <param name="source">The image this method extends.</param>
-        /// <param name="luminanceLevels">The number of different luminance levels. Typical values are 256 for 8-bit grayscale images
-        /// or 65536 for 16-bit grayscale images.</param>
+        /// <param name="options">The histogram equalization options to use.</param>
         /// <returns>The <see cref="Image{TPixel}"/>.</returns>
-        public static IImageProcessingContext<TPixel> HistogramEqualization<TPixel>(this IImageProcessingContext<TPixel> source, int luminanceLevels)
+        public static IImageProcessingContext<TPixel> HistogramEqualization<TPixel>(this IImageProcessingContext<TPixel> source, HistogramEqualizationOptions options)
             where TPixel : struct, IPixel<TPixel>
-            => source.ApplyProcessor(new HistogramEqualizationProcessor<TPixel>(luminanceLevels));
+            => source.ApplyProcessor(GetProcessor<TPixel>(options));
+
+        private static HistogramEqualizationProcessor<TPixel> GetProcessor<TPixel>(HistogramEqualizationOptions options)
+            where TPixel : struct, IPixel<TPixel>
+        {
+            HistogramEqualizationProcessor<TPixel> processor;
+
+            switch (options.Method)
+            {
+                case HistogramEqualizationMethod.Global:
+                    processor = new GlobalHistogramEqualizationProcessor<TPixel>(options.LuminanceLevels, options.ClipHistogram, options.ClipLimitPercentage);
+                    break;
+
+                case HistogramEqualizationMethod.AdaptiveTileInterpolation:
+                    processor = new AdaptiveHistEqualizationProcessor<TPixel>(options.LuminanceLevels, options.ClipHistogram, options.ClipLimitPercentage, options.Tiles);
+                    break;
+
+                case HistogramEqualizationMethod.AdaptiveSlidingWindow:
+                    processor = new AdaptiveHistEqualizationSWProcessor<TPixel>(options.LuminanceLevels, options.ClipHistogram, options.ClipLimitPercentage, options.Tiles);
+                    break;
+
+                default:
+                    processor = new GlobalHistogramEqualizationProcessor<TPixel>(options.LuminanceLevels, options.ClipHistogram, options.ClipLimitPercentage);
+                    break;
+            }
+
+            return processor;
+        }
     }
 }

src/ImageSharp/Processing/Processors/Normalization/AdaptiveHistEqualizationProcessor.cs

@@ -0,0 +1,106 @@
+// Copyright (c) Six Labors and contributors.
+// Licensed under the Apache License, Version 2.0.
+
+using System;
+using System.Buffers;
+using System.Numerics;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+using SixLabors.ImageSharp.Advanced;
+using SixLabors.ImageSharp.Memory;
+using SixLabors.ImageSharp.ParallelUtils;
+using SixLabors.ImageSharp.PixelFormats;
+using SixLabors.Memory;
+using SixLabors.Primitives;
+
+namespace SixLabors.ImageSharp.Processing.Processors.Normalization
+{
+    /// <summary>
+    /// Applies a global histogram equalization to the image.
+    /// </summary>
+    /// <typeparam name="TPixel">The pixel format.</typeparam>
+    internal class GlobalHistogramEqualizationProcessor<TPixel> : HistogramEqualizationProcessor<TPixel>
+        where TPixel : struct, IPixel<TPixel>
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GlobalHistogramEqualizationProcessor{TPixel}"/> class.
+        /// </summary>
+        /// <param name="luminanceLevels">
+        /// The number of different luminance levels. Typical values are 256 for 8-bit grayscale images
+        /// or 65536 for 16-bit grayscale images.
+        /// </param>
+        /// <param name="clipHistogram">Indicating whether to clip the histogram bins at a specific value.</param>
+        /// <param name="clipLimitPercentage">Histogram clip limit in percent of the total pixels. Histogram bins which exceed this limit, will be capped at this value.</param>
+        public GlobalHistogramEqualizationProcessor(int luminanceLevels, bool clipHistogram, float clipLimitPercentage)
+            : base(luminanceLevels, clipHistogram, clipLimitPercentage)
+        {
+        }
+
+        /// <inheritdoc/>
+        protected override void OnFrameApply(ImageFrame<TPixel> source, Rectangle sourceRectangle, Configuration configuration)
+        {
+            MemoryAllocator memoryAllocator = configuration.MemoryAllocator;
+            int numberOfPixels = source.Width * source.Height;
+            Span<TPixel> pixels = source.GetPixelSpan();
+            var workingRect = new Rectangle(0, 0, source.Width, source.Height);
+
+            using (IMemoryOwner<int> histogramBuffer = memoryAllocator.Allocate<int>(this.LuminanceLevels, AllocationOptions.Clean))
+            using (IMemoryOwner<int> cdfBuffer = memoryAllocator.Allocate<int>(this.LuminanceLevels, AllocationOptions.Clean))
+            {
+                // Build the histogram of the grayscale levels.
+                ParallelHelper.IterateRows(
+                    workingRect,
+                    configuration,
+                    rows =>
+                    {
+                        ref int histogramBase = ref MemoryMarshal.GetReference(histogramBuffer.GetSpan());
+                        for (int y = rows.Min; y < rows.Max; y++)
+                        {
+                            ref TPixel pixelBase = ref MemoryMarshal.GetReference(source.GetPixelRowSpan(y));
+
+                            for (int x = 0; x < workingRect.Width; x++)
+                            {
+                                int luminance = GetLuminance(Unsafe.Add(ref pixelBase, x), this.LuminanceLevels);
+                                Unsafe.Add(ref histogramBase, luminance)++;
+                            }
+                        }
+                    });
+
+                Span<int> histogram = histogramBuffer.GetSpan();
+                if (this.ClipHistogramEnabled)
+                {
+                    this.ClipHistogram(histogram, this.ClipLimitPercentage, numberOfPixels);
+                }
+
+                // Calculate the cumulative distribution function, which will map each input pixel to a new value.
+                int cdfMin = this.CalculateCdf(
+                    ref MemoryMarshal.GetReference(cdfBuffer.GetSpan()),
+                    ref MemoryMarshal.GetReference(histogram),
+                    histogram.Length - 1);
+
+                float numberOfPixelsMinusCdfMin = numberOfPixels - cdfMin;
+
+                // Apply the cdf to each pixel of the image
+                ParallelHelper.IterateRows(
+                    workingRect,
+                    configuration,
+                    rows =>
+                    {
+                        ref int cdfBase = ref MemoryMarshal.GetReference(cdfBuffer.GetSpan());
+                        for (int y = rows.Min; y < rows.Max; y++)
+                        {
+                            ref TPixel pixelBase = ref MemoryMarshal.GetReference(source.GetPixelRowSpan(y));
+
+                            for (int x = 0; x < workingRect.Width; x++)
+                            {
+                                ref TPixel pixel = ref Unsafe.Add(ref pixelBase, x);
+                                int luminance = GetLuminance(pixel, this.LuminanceLevels);
+                                float luminanceEqualized = Unsafe.Add(ref cdfBase, luminance) / numberOfPixelsMinusCdfMin;
+                                pixel.FromVector4(new Vector4(luminanceEqualized, luminanceEqualized, luminanceEqualized, pixel.ToVector4().W));
+                            }
+                        }
+                    });
+            }
+        }
+    }
+}

src/ImageSharp/Processing/Processors/Normalization/AdaptiveHistEqualizationSWProcessor.cs

@@ -0,0 +1,26 @@
+// Copyright (c) Six Labors and contributors.
+// Licensed under the Apache License, Version 2.0.
+
+namespace SixLabors.ImageSharp.Processing.Processors.Normalization
+{
+    /// <summary>
+    /// Enumerates the different types of defined histogram equalization methods.
+    /// </summary>
+    public enum HistogramEqualizationMethod : int
+    {
+        /// <summary>
+        /// A global histogram equalization.
+        /// </summary>
+        Global,
+
+        /// <summary>
+        /// Adaptive histogram equalization using a tile interpolation approach.
+        /// </summary>
+        AdaptiveTileInterpolation,
+
+        /// <summary>
+        /// Adaptive histogram equalization using sliding window. Slower then the tile interpolation mode, but can yield to better results.
+        /// </summary>
+        AdaptiveSlidingWindow,
+    }
+}

src/ImageSharp/Processing/Processors/Normalization/GlobalHistogramEqualizationProcessor.cs

@@ -0,0 +1,43 @@
+// Copyright (c) Six Labors and contributors.
+// Licensed under the Apache License, Version 2.0.
+
+namespace SixLabors.ImageSharp.Processing.Processors.Normalization
+{
+    /// <summary>
+    /// Data container providing the different options for the histogram equalization.
+    /// </summary>
+    public class HistogramEqualizationOptions
+    {
+        /// <summary>
+        /// Gets the default <see cref="HistogramEqualizationOptions"/> instance.
+        /// </summary>
+        public static HistogramEqualizationOptions Default { get; } = new HistogramEqualizationOptions();
+
+        /// <summary>
+        /// Gets or sets the histogram equalization method to use. Defaults to global histogram equalization.
+        /// </summary>
+        public HistogramEqualizationMethod Method { get; set; } = HistogramEqualizationMethod.Global;
+
+        /// <summary>
+        /// Gets or sets the number of different luminance levels. Typical values are 256 for 8-bit grayscale images
+        /// or 65536 for 16-bit grayscale images. Defaults to 256.
+        /// </summary>
+        public int LuminanceLevels { get; set; } = 256;
+
+        /// <summary>
+        /// Gets or sets a value indicating whether to clip the histogram bins at a specific value. Defaults to false.
+        /// </summary>
+        public bool ClipHistogram { get; set; } = false;
+
+        /// <summary>
+        /// Gets or sets the histogram clip limit in percent of the total pixels in a tile. Histogram bins which exceed this limit, will be capped at this value.
+        /// Defaults to 0.035f.
+        /// </summary>
+        public float ClipLimitPercentage { get; set; } = 0.035f;
+
+        /// <summary>
+        /// Gets or sets the number of tiles the image is split into (horizontal and vertically) for the adaptive histogram equalization. Defaults to 10.
+        /// </summary>
+        public int Tiles { get; set; } = 10;
+    }
+}