Feature: histogram equalization

src/ImageSharp/Processing/Normalization/HistogramEqualizationExtension.cs

@@ -0,0 +1,23 @@
+// Copyright (c) Six Labors and contributors.
+// Licensed under the Apache License, Version 2.0.
+
+using SixLabors.ImageSharp.PixelFormats;
+
+namespace SixLabors.ImageSharp.Processing.Normalization
+{
+    /// <summary>
+    /// Adds extension that allows applying an HistogramEqualization to the image.
+    /// </summary>
+    public static class HistogramEqualizationExtension
+    {
+        /// <summary>
+        /// Equalizes the histogram of an image to increases the global contrast.
+        /// </summary>
+        /// <typeparam name="TPixel">The pixel format.</typeparam>
+        /// <param name="source">The image this method extends.</param>
+        /// <returns>A histogram equalized grayscale image.</returns>
+        public static IImageProcessingContext<TPixel> HistogramEqualization<TPixel>(this IImageProcessingContext<TPixel> source)
+            where TPixel : struct, IPixel<TPixel>
+            => source.ApplyProcessor(new HistogramEqualizationProcessor<TPixel>());
+    }
+}

src/ImageSharp/Processing/Normalization/HistogramEqualizationProcessor.cs

@@ -0,0 +1,120 @@
+// Copyright (c) Six Labors and contributors.
+// Licensed under the Apache License, Version 2.0.
+
+using System;
+using SixLabors.ImageSharp.Advanced;
+using SixLabors.ImageSharp.PixelFormats;
+using SixLabors.ImageSharp.Processing.Processors;
+using SixLabors.Memory;
+using SixLabors.Primitives;
+
+namespace SixLabors.ImageSharp.Processing.Normalization
+{
+    /// <summary>
+    /// Applies a global histogram equalization to the image.
+    /// </summary>
+    /// <typeparam name="TPixel">The pixel format.</typeparam>
+    internal class HistogramEqualizationProcessor<TPixel> : ImageProcessor<TPixel>
+        where TPixel : struct, IPixel<TPixel>
+    {
+        /// <inheritdoc/>
+        protected override void OnFrameApply(ImageFrame<TPixel> source, Rectangle sourceRectangle, Configuration configuration)
+        {
+            var rgb48 = default(Rgb48);
+            var rgb24 = default(Rgb24);
+            MemoryAllocator memoryAllocator = configuration.MemoryAllocator;
+            int numberOfPixels = source.Width * source.Height;
+            bool is16bitPerChannel = typeof(TPixel) == typeof(Rgb48) || typeof(TPixel) == typeof(Rgba64);
+
+            // build the histogram of the grayscale levels
+            int luminanceLevels = is16bitPerChannel ? 65536 : 256;
+            Span<int> histogram = memoryAllocator.Allocate<int>(luminanceLevels, clear: true).GetSpan();
+            for (int y = 0; y < source.Height; y++)
+            {
+                Span<TPixel> row = source.GetPixelRowSpan(y);
+                for (int x = 0; x < source.Width; x++)
+                {
+                    TPixel sourcePixel = row[x];
+                    int luminance = this.GetLuminance(sourcePixel, is16bitPerChannel, ref rgb24, ref rgb48);
+                    histogram[luminance]++;
+                }
+            }
+
+            // calculate the cumulative distribution function (which will be the cumulative histogram)
+            Span<int> cdf = memoryAllocator.Allocate<int>(luminanceLevels, clear: true).GetSpan();
+            int histSum = 0;
+            for (int i = 0; i < histogram.Length; i++)
+            {
+                histSum += histogram[i];
+                cdf[i] = histSum;
+            }
+
+            // get the first none zero value of the cumulative histogram
+            int cdfMin = 0;
+            for (int i = 0; i < histogram.Length; i++)
+            {
+                if (histogram[i] != 0)
+                {
+                    cdfMin = cdf[i];
+                    break;
+                }
+            }
+
+            // creating the lookup table: subtracting cdf min, so we do not need to do that inside the for loop
+            for (int i = 0; i < histogram.Length; i++)
+            {
+                cdf[i] = cdf[i] - cdfMin;
+            }
+
+            // apply the cdf to each pixel of the image
+            double numberOfPixelsMinusCdfMin = (double)(numberOfPixels - cdfMin);
+            int luminanceLevelsMinusOne = luminanceLevels - 1;
+            for (int y = 0; y < source.Height; y++)
+            {
+                Span<TPixel> row = source.GetPixelRowSpan(y);
+                for (int x = 0; x < source.Width; x++)
+                {
+                    TPixel sourcePixel = row[x];
+
+                    int luminance = this.GetLuminance(sourcePixel, is16bitPerChannel, ref rgb24, ref rgb48);
+                    double luminanceEqualized = (cdf[luminance] / numberOfPixelsMinusCdfMin) * luminanceLevelsMinusOne;
+                    luminanceEqualized = Math.Round(luminanceEqualized);
+
+                    if (is16bitPerChannel)
+                    {
+                        row[x].PackFromRgb48(new Rgb48((ushort)luminanceEqualized, (ushort)luminanceEqualized, (ushort)luminanceEqualized));
+                    }
+                    else
+                    {
+                        row[x].PackFromRgba32(new Rgba32((byte)luminanceEqualized, (byte)luminanceEqualized, (byte)luminanceEqualized));
+                    }
+                }
+            }
+        }
+
+        /// <summary>
+        /// Convert the pixel values to grayscale using ITU-R Recommendation BT.709.
+        /// </summary>
+        /// <param name="sourcePixel">The pixel to get the luminance from</param>
+        /// <param name="is16bitPerChannel">Flag indicates, if its 16 bits per channel, otherwise its 8</param>
+        /// <param name="rgb24">Will store the pixel values in case of 8 bit per channel</param>
+        /// <param name="rgb48">Will store the pixel values in case of 16 bit per channel</param>
+        private int GetLuminance(TPixel sourcePixel, bool is16bitPerChannel, ref Rgb24 rgb24, ref Rgb48 rgb48)
+        {
+            // Convert to grayscale using ITU-R Recommendation BT.709
+            int luminance;
+            if (is16bitPerChannel)
+            {
+                sourcePixel.ToRgb48(ref rgb48);
+                luminance = Convert.ToInt32((.2126F * rgb48.R) + (.7152F * rgb48.G) + (.0722F * rgb48.B));
+            }
+            else
+            {
+                sourcePixel.ToRgb24(ref rgb24);
+                luminance = Convert.ToInt32((.2126F * rgb24.R) + (.7152F * rgb24.G) + (.0722F * rgb24.B));
+            }
+
+            return luminance;
+        }
+    }
+}

tests/ImageSharp.Tests/Processing/Normalization/HistogramEqualizationTests.cs

@@ -0,0 +1,66 @@
+// Copyright (c) Six Labors and contributors.
+// Licensed under the Apache License, Version 2.0.
+
+using SixLabors.ImageSharp.PixelFormats;
+using SixLabors.ImageSharp.Processing;
+using SixLabors.ImageSharp.Processing.Normalization;
+using Xunit;
+
+namespace SixLabors.ImageSharp.Tests.Processing.Normalization
+{
+    public class HistogramEqualizationTests
+    {
+        [Fact]
+        public void HistogramEqualizationTest()
+        {
+            // arrange
+            byte[] pixels = new byte[]
+            {
+                52,  55,  61,  59,  70,  61,  76,  61,
+                62,  59,  55, 104,  94,  85,  59,  71,
+                63,  65,  66, 113, 144, 104,  63,  72,
+                64,  70,  70, 126, 154, 109,  71,  69,
+                67,  73,  68, 106, 122,  88,  68,  68,
+                68,  79,  60,  79,  77,  66,  58,  75,
+                69,  85,  64,  58,  55,  61,  65,  83,
+                70,  87,  69,  68,  65,  73,  78,  90
+            };
+            var image = new Image<Rgba32>(8, 8);
+            for (int y = 0; y < 8; y++)
+            {
+                for (int x = 0; x < 8; x++)
+                {
+                    byte luminance = pixels[y * 8 + x];
+                    image[x, y] = new Rgba32(luminance, luminance, luminance);
+                }
+            }
+
+            byte[] expected = new byte[]
+            {
+                0,    12,   53,   32,  146,   53,  174,   53,
+                57,   32,   12,  227,  219,  202,   32,  154,
+                65,   85,   93,  239,  251,  227,   65,  158,
+                73,  146,  146,  247,  255,  235,  154,  130,
+                97,  166,  117,  231,  243,  210,  117,  117,
+                117, 190,   36,  190,  178,   93,   20,  170,
+                130, 202,   73,   20,   12,   53,   85,  194,
+                146, 206,  130,  117,   85,  166,  182,  215
+            };
+
+            // act
+            image.Mutate(x => x.HistogramEqualization());
+
+            // assert
+            for (int y = 0; y < 8; y++)
+            {
+                for (int x = 0; x < 8; x++)
+                {
+                    Rgba32 actual = image[x, y];
+                    Assert.Equal(expected[y * 8 + x], actual.R);
+                    Assert.Equal(expected[y * 8 + x], actual.G);
+                    Assert.Equal(expected[y * 8 + x], actual.B);
+                }
+            }
+        }
+    }
+}