Add options for color lookup.

Author: JimBobSquarePants

src/ImageSharp/ImageSharp.csproj

@@ -13,6 +13,13 @@
     <PackageTags>Image Resize Crop Gif Jpg Jpeg Bitmap Pbm Png Tga Tiff WebP NetCore</PackageTags>
     <Description>A new, fully featured, fully managed, cross-platform, 2D graphics API for .NET</Description>
     <Configurations>Debug;Release</Configurations>
+
+    <!--
+    Enable preview features so we can use them for internal operations
+    but don't require downstream users to enable them.
+    -->
+    <EnablePreviewFeatures>True</EnablePreviewFeatures>
+    <GenerateRequiresPreviewFeaturesAttribute>False</GenerateRequiresPreviewFeaturesAttribute>
   </PropertyGroup>
 
   <!--  This enables the nullable analysis and treats all nullable warnings as error-->

src/ImageSharp/Processing/Processors/Dithering/PaletteDitherProcessor{TPixel}.cs

@@ -80,7 +80,7 @@ protected override void Dispose(bool disposing)
         Justification = "https://github.com/dotnet/roslyn-analyzers/issues/6151")]
     internal readonly struct DitherProcessor : IPaletteDitherImageProcessor<TPixel>, IDisposable
     {
-        private readonly EuclideanPixelMap<TPixel> pixelMap;
+        private readonly PixelMap<TPixel> pixelMap;
 
         [MethodImpl(InliningOptions.ShortMethod)]
         public DitherProcessor(
@@ -89,7 +89,7 @@ public DitherProcessor(
             float ditherScale)
         {
             this.Configuration = configuration;
-            this.pixelMap = new EuclideanPixelMap<TPixel>(configuration, palette);
+            this.pixelMap = PixelMapFactory.Create(configuration, palette, ColorMatchingMode.Hybrid);
             this.Palette = palette;
             this.DitherScale = ditherScale;
         }
@@ -103,7 +103,7 @@ public DitherProcessor(
         [MethodImpl(InliningOptions.ShortMethod)]
         public TPixel GetPaletteColor(TPixel color)
         {
-            this.pixelMap.GetClosestColor(color, out TPixel match);
+            _ = this.pixelMap.GetClosestColor(color, out TPixel match);
             return match;
         }
 

src/ImageSharp/Processing/Processors/Quantization/ColorMatchingMode.cs

@@ -0,0 +1,28 @@
+// Copyright (c) Six Labors.
+// Licensed under the Six Labors Split License.
+
+namespace SixLabors.ImageSharp.Processing.Processors.Quantization;
+
+/// <summary>
+/// Defines the precision level used when matching colors during quantization.
+/// </summary>
+public enum ColorMatchingMode
+{
+    /// <summary>
+    /// Uses a coarse caching strategy optimized for performance at the expense of exact matches.
+    /// This provides the fastest matching but may yield approximate results.
+    /// </summary>
+    Coarse,
+
+    /// <summary>
+    /// Enables an exact color match cache for the first 512 unique colors encountered,
+    /// falling back to coarse matching thereafter.
+    /// </summary>
+    Hybrid,
+
+    /// <summary>
+    /// Performs exact color matching without any caching optimizations.
+    /// This is the slowest but most accurate matching strategy.
+    /// </summary>
+    Exact
+}

src/ImageSharp/Processing/Processors/Quantization/EuclideanPixelMap{TPixel,TCache}.cs

@@ -0,0 +1,219 @@
+// Copyright (c) Six Labors.
+// Licensed under the Six Labors Split License.
+
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+using System.Runtime.Versioning;
+using SixLabors.ImageSharp.PixelFormats;
+
+namespace SixLabors.ImageSharp.Processing.Processors.Quantization;
+
+/// <summary>
+/// Gets the closest color to the supplied color based upon the Euclidean distance.
+/// </summary>
+/// <typeparam name="TPixel">The pixel format.</typeparam>
+/// <typeparam name="TCache">The cache type.</typeparam>
+/// <para>
+/// This class is not thread safe and should not be accessed in parallel.
+/// Doing so will result in non-idempotent results.
+/// </para>
+internal sealed class EuclideanPixelMap<TPixel, TCache> : PixelMap<TPixel>
+    where TPixel : unmanaged, IPixel<TPixel>
+    where TCache : struct, IColorIndexCache<TCache>
+{
+    private Rgba32[] rgbaPalette;
+    private int transparentIndex;
+    private readonly TPixel transparentMatch;
+
+    // Do not make readonly. It's a mutable struct.
+#pragma warning disable IDE0044 // Add readonly modifier
+    private TCache cache;
+#pragma warning restore IDE0044 // Add readonly modifier
+    private readonly Configuration configuration;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="EuclideanPixelMap{TPixel, TCache}"/> class.
+    /// </summary>
+    /// <param name="configuration">The configuration.</param>
+    /// <param name="palette">The color palette to map from.</param>
+    /// <param name="transparentIndex">An explicit index at which to match transparent pixels.</param>
+    [RequiresPreviewFeatures]
+    public EuclideanPixelMap(
+        Configuration configuration,
+        ReadOnlyMemory<TPixel> palette,
+        int transparentIndex = -1)
+    {
+        this.configuration = configuration;
+        this.cache = TCache.Create(configuration.MemoryAllocator);
+
+        this.Palette = palette;
+        this.rgbaPalette = new Rgba32[palette.Length];
+        PixelOperations<TPixel>.Instance.ToRgba32(configuration, this.Palette.Span, this.rgbaPalette);
+
+        this.transparentIndex = transparentIndex;
+        Unsafe.SkipInit(out this.transparentMatch);
+        this.transparentMatch.FromRgba32(default);
+    }
+
+    /// <inheritdoc/>
+    [MethodImpl(InliningOptions.ShortMethod)]
+    public override int GetClosestColor(TPixel color, out TPixel match)
+    {
+        ref TPixel paletteRef = ref MemoryMarshal.GetReference(this.Palette.Span);
+        Unsafe.SkipInit(out Rgba32 rgba);
+        color.ToRgba32(ref rgba);
+
+        // Check if the color is in the lookup table
+        if (this.cache.TryGetValue(rgba, out short index))
+        {
+            match = Unsafe.Add(ref paletteRef, (ushort)index);
+            return index;
+        }
+
+        return this.GetClosestColorSlow(rgba, ref paletteRef, out match);
+    }
+
+    /// <inheritdoc/>
+    public override void Clear(ReadOnlyMemory<TPixel> palette)
+    {
+        this.Palette = palette;
+        this.rgbaPalette = new Rgba32[palette.Length];
+        PixelOperations<TPixel>.Instance.ToRgba32(this.configuration, this.Palette.Span, this.rgbaPalette);
+        this.transparentIndex = -1;
+        this.cache.Clear();
+    }
+
+    /// <inheritdoc/>
+    public override void SetTransparentIndex(int index)
+    {
+        if (index != this.transparentIndex)
+        {
+            this.cache.Clear();
+        }
+
+        this.transparentIndex = index;
+    }
+
+    [MethodImpl(InliningOptions.ColdPath)]
+    private int GetClosestColorSlow(Rgba32 rgba, ref TPixel paletteRef, out TPixel match)
+    {
+        // Loop through the palette and find the nearest match.
+        int index = 0;
+
+        if (this.transparentIndex >= 0 && rgba == default)
+        {
+            // We have explicit instructions. No need to search.
+            index = this.transparentIndex;
+            _ = this.cache.TryAdd(rgba, (short)index);
+            match = this.transparentMatch;
+            return index;
+        }
+
+        float leastDistance = float.MaxValue;
+        for (int i = 0; i < this.rgbaPalette.Length; i++)
+        {
+            Rgba32 candidate = this.rgbaPalette[i];
+            float distance = DistanceSquared(rgba, candidate);
+
+            // If it's an exact match, exit the loop
+            if (distance == 0)
+            {
+                index = i;
+                break;
+            }
+
+            if (distance < leastDistance)
+            {
+                // Less than... assign.
+                index = i;
+                leastDistance = distance;
+            }
+        }
+
+        // Now I have the index, pop it into the cache for next time
+        _ = this.cache.TryAdd(rgba, (short)index);
+        match = Unsafe.Add(ref paletteRef, (uint)index);
+
+        return index;
+    }
+
+    [MethodImpl(InliningOptions.ShortMethod)]
+    private static float DistanceSquared(Rgba32 a, Rgba32 b)
+    {
+        float deltaR = a.R - b.R;
+        float deltaG = a.G - b.G;
+        float deltaB = a.B - b.B;
+        float deltaA = a.A - b.A;
+        return (deltaR * deltaR) + (deltaG * deltaG) + (deltaB * deltaB) + (deltaA * deltaA);
+    }
+
+    /// <inheritdoc/>
+    public override void Dispose() => this.cache.Dispose();
+}
+
+/// <summary>
+/// Represents a map of colors to indices.
+/// </summary>
+/// <typeparam name="TPixel">The pixel format.</typeparam>
+internal abstract class PixelMap<TPixel> : IDisposable
+    where TPixel : unmanaged, IPixel<TPixel>
+{
+    /// <summary>
+    /// Gets the color palette of this <see cref="PixelMap{TPixel}"/>.
+    /// </summary>
+    public ReadOnlyMemory<TPixel> Palette { get; private protected set; }
+
+    /// <summary>
+    /// Returns the closest color in the palette and the index of that pixel.
+    /// </summary>
+    /// <param name="color">The color to match.</param>
+    /// <param name="match">The matched color.</param>
+    /// <returns>
+    /// The <see cref="int"/> index.
+    /// </returns>
+    public abstract int GetClosestColor(TPixel color, out TPixel match);
+
+    /// <summary>
+    /// Clears the map, resetting it to use the given palette.
+    /// </summary>
+    /// <param name="palette">The color palette to map from.</param>
+    public abstract void Clear(ReadOnlyMemory<TPixel> palette);
+
+    /// <summary>
+    /// Allows setting the transparent index after construction.
+    /// </summary>
+    /// <param name="index">An explicit index at which to match transparent pixels.</param>
+    public abstract void SetTransparentIndex(int index);
+
+    /// <inheritdoc/>
+    public abstract void Dispose();
+}
+
+/// <summary>
+/// A factory for creating <see cref="PixelMap{TPixel}"/> instances.
+/// </summary>
+internal static class PixelMapFactory
+{
+    /// <summary>
+    /// Creates a new <see cref="PixelMap{TPixel}"/> instance.
+    /// </summary>
+    /// <typeparam name="TPixel">The pixel format.</typeparam>
+    /// <param name="configuration">The configuration.</param>
+    /// <param name="palette">The color palette to map from.</param>
+    /// <param name="colorMatchingMode">The color matching mode.</param>
+    /// <param name="transparentIndex">An explicit index at which to match transparent pixels.</param>
+    /// <returns>
+    /// The <see cref="PixelMap{TPixel}"/>.
+    /// </returns>
+    public static PixelMap<TPixel> Create<TPixel>(
+        Configuration configuration,
+        ReadOnlyMemory<TPixel> palette,
+        ColorMatchingMode colorMatchingMode,
+        int transparentIndex = -1)
+        where TPixel : unmanaged, IPixel<TPixel> => colorMatchingMode switch
+        {
+            ColorMatchingMode.Hybrid => new EuclideanPixelMap<TPixel, HybridCache>(configuration, palette, transparentIndex),
+            ColorMatchingMode.Exact => new EuclideanPixelMap<TPixel, NullCache>(configuration, palette, transparentIndex),
+            _ => new EuclideanPixelMap<TPixel, CoarseCache>(configuration, palette, transparentIndex),
+        };
+}