Feature: adaptive histogram equalization

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/GlobalHistogramEqualizationProcessor.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/HistogramEqualizationMethod.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/HistogramEqualizationOptions.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;
+    }
+}