image lightness filter

src/ImageSharp/Processing/Extensions/LightnessExtension.cs

@@ -0,0 +1,35 @@
+// Copyright (c) Six Labors and contributors.
+// Licensed under the Apache License, Version 2.0.
+using SixLabors.ImageSharp.Processing.Processors.Filters;
+using SixLabors.Primitives;
+
+namespace SixLabors.ImageSharp.Processing
+{
+    /// <summary>
+    /// Defines extensions that allow the alteration of the hue component of an <see cref="Image"/>
+    /// using Mutate/Clone.
+    /// </summary>
+    public static class LightnessExtension
+    {
+        /// <summary>
+        /// Alters the hue component of the image.
+        /// </summary>
+        /// <param name="source">The image this method extends.</param>
+        /// <param name="lightness">Lightness parameter of image in HSL color scheme.</param>
+        /// <returns>The <see cref="IImageProcessingContext"/> to allow chaining of operations.</returns>
+        public static IImageProcessingContext Lightness(this IImageProcessingContext source, float lightness)
+            => source.ApplyProcessor(new LightnessProcessor(lightness));
+
+        /// <summary>
+        /// Alters the hue component of the image.
+        /// </summary>
+        /// <param name="source">The image this method extends.</param>
+        /// <param name="lightness">Lightness parameter of image in HSL color scheme.</param>
+        /// <param name="rectangle">
+        /// The <see cref="Rectangle"/> structure that specifies the portion of the image object to alter.
+        /// </param>
+        /// <returns>The <see cref="IImageProcessingContext"/> to allow chaining of operations.</returns>
+        public static IImageProcessingContext Lightness(this IImageProcessingContext source, float lightness, Rectangle rectangle)
+            => source.ApplyProcessor(new LightnessProcessor(lightness), rectangle);
+    }
+}

src/ImageSharp/Processing/KnownFilterMatrices.cs

@@ -432,6 +432,48 @@ namespace SixLabors.ImageSharp.Processing
             return m;
         }
 
+        /// <summary>
+        /// Create a lightness filter matrix using the given amount.
+        /// </summary>
+        /// <remarks>
+        /// A value of 0 will create an image that is completely black. A value of 1 makes the image completely white.
+        /// Other values are linear multipliers on the effect. Values of an amount over 1 are allowed, providing brighter results.
+        /// </remarks>
+        /// <param name="amount">The proportion of the conversion. Must be greater than or equal to 0.</param>
+        /// <returns>The <see cref="ColorMatrix"/></returns>
+        public static ColorMatrix CreateLightnessFilter(float amount)
+        {
+            Guard.MustBeBetweenOrEqualTo(amount, 0, 1F, nameof(amount));
+
+
+            /// James Jackson-South @JimBobSquarePants 03:54
+            /// Our colormatrix is a column-major version of the Android colormatrix
+            ///     ```
+            ///     // | 0| 1| 2| 3| 4|   |0|5|10|15|   |M11|M12|M13|M14|
+            ///     // | 5| 6| 7| 8| 9|   |1|6|11|16|   |M21|M22|M23|M24|
+            ///     // |10|11|12|13|14| = |2|7|12|17| = |M31|M32|M33|M34|
+            ///     // |15|16|17|18|19|   |3|8|13|18|   |M41|M42|M43|M44|
+            ///     //                    |4|9|14|19|   |M51|M52|M53|M54|
+            ///     ```
+            /// 
+            /// James Jackson-South @JimBobSquarePants 03:54
+            /// So given the information you have supplied and the stackoverflow answer (which has one too many rows in the code) you would use
+            /// the identity matrix and change 4, 9, 14 in the android matrix. In our matrix you would use identity again but change M51, M52, M53.
+            /// We use column major layout as that matches the system drawing matrix.
+            ///
+            // See https://en.wikipedia.org/wiki/HSL_and_HSV#Lightness and https://stackoverflow.com/questions/9175088/adjusting-lightness-using-colormatrix#answer-27179516
+            return new ColorMatrix
+                   {
+                       M11 = 1F,
+                       M22 = 1F,
+                       M33 = 1F,
+                       M44 = 1F,
+                       M51 = amount,
+                       M52 = amount,
+                       M53 = amount
+                   };
+        }
+
         /// <summary>
         /// Create a sepia filter matrix using the given amount.
         /// The formula used matches the svg specification. <see href="http://www.w3.org/TR/filter-effects/#sepiaEquivalent"/>

src/ImageSharp/Processing/Processors/Filters/LightnessProcessor.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Six Labors and contributors.
+// Licensed under the Apache License, Version 2.0.
+namespace SixLabors.ImageSharp.Processing.Processors.Filters
+{
+    /// <summary>
+    /// Applies a lightness filter matrix using
+    /// </summary>
+    public sealed class LightnessProcessor : FilterProcessor
+    {
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="LightnessProcessor"/> class.
+        /// </summary>
+        /// <param name="lightness">Lightness of image in HSL color scheme</param>
+        public LightnessProcessor(float lightness)
+        : base(KnownFilterMatrices.CreateLightnessFilter(lightness))
+        {
+            this.Lightness = lightness;
+        }
+
+        /// <summary>
+        /// Gets Lightness of image in HSL color scheme.
+        /// The "brightness relative to the brightness of a similarly illuminated white" https://en.wikipedia.org/wiki/HSL_and_HSV#Lightness
+        /// </summary>
+        public float Lightness { get; }
+    }
+}