DirectBitmap: UnsafeBitmap introduced & memory fixes

The `Bitmap` property has been replaced by `UnsafeBitmap` to make direct memory binding explicit.
All returns now provide a copy (`new Bitmap(UnsafeBitmap)`) to avoid memory leaks and side effects. Dispose logic and resource management have been improved.
Color conversion in `ColorHsv` is more robust (clamping instead of exceptions).
Methods return null if errors occur.
SIMD and pixel operations have been refactored. `Pixel32` is now immutable (`readonly`).
Tests and helper methods consistently use `UnsafeBitmap`. The changes increase security and efficiency in the imaging framework.

Author: Wayfarer

ImageCompare/AnalysisProcessing.cs

@@ -258,7 +258,7 @@ internal static Bitmap DifferenceImage(Bitmap first, Bitmap second, Color highli
                 }
             });
 
-            return dbmCanvas.Bitmap;
+            return new Bitmap(dbmCanvas.UnsafeBitmap);
         }
     }
 }

Imaging/Cif.cs

@@ -333,7 +333,7 @@ public Color GetColor(int id)
                 dbm.SetPixel(coordinate.X, coordinate.Y, key);
             }
 
-            return dbm.Bitmap;
+            return new Bitmap(dbm.UnsafeBitmap);
         }
 
         /// <summary>

Imaging/CifProcessing.cs

@@ -73,7 +73,7 @@ internal static Dictionary<Color, SortedSet<int>> ConvertToCifFromBitmap(Bitmap
                 dbm.SetArea(ids, color);
             }
 
-            return dbm.Bitmap;
+            return new Bitmap(dbm.UnsafeBitmap);
         }
 
         /// <summary>

Imaging/ColorHsv.cs

@@ -117,7 +117,7 @@ public ColorHsv(byte r, byte g, byte b, byte a)
         }
 
         /// <summary>
-        /// Froms the RGB.
+        /// Convert from RGB to HSV.
         /// </summary>
         /// <param name="r">The r.</param>
         /// <param name="g">The g.</param>
@@ -126,16 +126,20 @@ public ColorHsv(byte r, byte g, byte b, byte a)
         /// <returns>Color HSV object.</returns>
         public static ColorHsv FromRgb(int r, int g, int b, int a = 255)
         {
-            ValidateRgb(r, g, b, a);
+            // Robustness: Clamp instead of throwing
+            r = Math.Max(0, Math.Min(255, r));
+            g = Math.Max(0, Math.Min(255, g));
+            b = Math.Max(0, Math.Min(255, b));
+            a = Math.Max(0, Math.Min(255, a));
 
             var hsv = new ColorHsv { R = r, G = g, B = b, A = a };
-
             hsv.ToHsv();
             return hsv;
         }
 
         /// <summary>
-        /// Froms the HSV.
+        /// Creates a ColorHsv from HSV values.
+        /// Automatically wraps Hue and clamps S/V/A.
         /// </summary>
         /// <param name="h">The h.</param>
         /// <param name="s">The s.</param>
@@ -144,10 +148,22 @@ public static ColorHsv FromRgb(int r, int g, int b, int a = 255)
         /// <returns>Color HSV object.</returns>
         public static ColorHsv FromHsv(double h, double s, double v, int a = 255)
         {
-            ValidateHsv(h, s, v, a);
+            // Robustness: Handle "fuzzy" floating point math
 
-            var hsv = new ColorHsv { H = h, S = s, V = v, A = a };
+            // 1. Wrap Hue (e.g. 361 becomes 1, -10 becomes 350)
+            // This handles cases where the mouse rotation calc goes slightly over 360
+            h = h % 360.0;
+            if (h < 0) h += 360.0;
+
+            // 2. Clamp Saturation and Value to 0.0 - 1.0
+            // Barycentric triangle math often returns -0.00001 or 1.00001 at the edges
+            s = Math.Max(0.0, Math.Min(1.0, s));
+            v = Math.Max(0.0, Math.Min(1.0, v));
 
+            // 3. Clamp Alpha
+            a = Math.Max(0, Math.Min(255, a));
+
+            var hsv = new ColorHsv { H = h, S = s, V = v, A = a };
             hsv.ToRgb();
             return hsv;
         }
@@ -261,7 +277,7 @@ public int CompareTo(ColorHsv? other)
         /// <returns>
         /// The result of the operator.
         /// </returns>
-        public static bool operator ==(ColorHsv a, ColorHsv b) => Equals(a, b);
+        public static bool operator ==(ColorHsv? a, ColorHsv b) => Equals(a, b);
 
         /// <summary>
         /// Implements the operator !=.
@@ -391,29 +407,5 @@ private static void ValidateRgb(int r, int g, int b, int a)
             if (r is < 0 or > 255 || g is < 0 or > 255 || b is < 0 or > 255 || a is < 0 or > 255)
                 throw new ArgumentOutOfRangeException("RGB values must be 0–255");
         }
-
-        /// <summary>
-        /// Validates the HSV.
-        /// </summary>
-        /// <param name="h">The h.</param>
-        /// <param name="s">The s.</param>
-        /// <param name="v">The v.</param>
-        /// <param name="a">a.</param>
-        /// <exception cref="System.ArgumentOutOfRangeException">
-        /// Hue must be 0–360
-        /// or
-        /// Saturation must be 0–1
-        /// or
-        /// Value must be 0–1
-        /// or
-        /// Alpha must be 0–255
-        /// </exception>
-        private static void ValidateHsv(double h, double s, double v, int a)
-        {
-            if (h is < 0 or > 360) throw new ArgumentOutOfRangeException("Hue must be 0–360");
-            if (s is < 0 or > 1) throw new ArgumentOutOfRangeException("Saturation must be 0–1");
-            if (v is < 0 or > 1) throw new ArgumentOutOfRangeException("Value must be 0–1");
-            if (a is < 0 or > 255) throw new ArgumentOutOfRangeException("Alpha must be 0–255");
-        }
     }
 }

Imaging/DirectBitmap.cs

@@ -84,7 +84,7 @@ public DirectBitmap(Image image)
                 }
             }
 
-            Bitmap = new Bitmap(
+            UnsafeBitmap = new Bitmap(
                 Width,
                 Height,
                 Width * Marshal.SizeOf<Pixel32>(),
@@ -120,7 +120,7 @@ public DirectBitmap(string filePath)
                 Height = image.Height;
                 Initiate();
 
-                using var graphics = Graphics.FromImage(Bitmap);
+                using var graphics = Graphics.FromImage(UnsafeBitmap);
                 graphics.DrawImage(image, new Rectangle(0, 0, Width, Height), 0, 0, Width, Height, GraphicsUnit.Pixel);
             }
             catch (Exception ex)
@@ -134,11 +134,14 @@ public DirectBitmap(string filePath)
 
         /// <summary>
         ///     Gets the bitmap.
+        ///     Be careful, we pass a reference that never gets copied, so any changes to this Bitmap will affect the DirectBitmap and vice versa.
+        ///     GcHandle is pinned, so the memory address of the pixel data will not change, allowing for direct manipulation of the bitmap's pixels.
+        ///     This memory is not managed by the .NET runtime, so it is crucial to ensure that it is properly released to avoid memory leaks. Always call Dispose() when done with the DirectBitmap to free the pinned handle and associated resources.
         /// </summary>
         /// <value>
         ///     The bitmap.
         /// </value>
-        public Bitmap Bitmap { get; private set; }
+        public Bitmap UnsafeBitmap { get; private set; }
 
         /// <summary>
         ///     Gets a value indicating whether this <see cref="DirectBitmap" /> is disposed.
@@ -154,7 +157,12 @@ public DirectBitmap(string filePath)
         /// <inheritdoc />
         public int Width { get; }
 
-        /// <inheritdoc />
+        /// <summary>
+        /// Gets or sets the bits handle.
+        /// </summary>
+        /// <value>
+        /// The bits handle.
+        /// </value>
         private GCHandle BitsHandle { get; set; }
 
         /// <inheritdoc />
@@ -206,7 +214,7 @@ private void Initiate(Color color = default)
             BitsHandle = GCHandle.Alloc(Bits, GCHandleType.Pinned);
 
             // Create Bitmap from pinned Pixel32 array
-            Bitmap = new Bitmap(
+            UnsafeBitmap = new Bitmap(
                 Width,
                 Height,
                 Width * Marshal.SizeOf<Pixel32>(), // stride in bytes
@@ -230,7 +238,8 @@ public static DirectBitmap GetInstance(Bitmap btm)
 
             // Lock source bits
             var rect = new Rectangle(0, 0, btm.Width, btm.Height);
-            var srcData = btm.LockBits(rect, System.Drawing.Imaging.ImageLockMode.ReadOnly, PixelFormat.Format32bppArgb);
+            var srcData = btm.LockBits(rect, System.Drawing.Imaging.ImageLockMode.ReadOnly,
+                PixelFormat.Format32bppArgb);
 
             // We can copy directly into our Bits array since it's pinned
             unsafe
@@ -318,7 +327,7 @@ public void DrawRectangle(int x1, int y2, int width, int height, Color color)
 
                     for (var x = x1; x < x1 + width && x < Width; x++)
                     {
-                        Bits[rowStart + x] = colorPixel; 
+                        Bits[rowStart + x] = colorPixel;
                     }
                 }
             }
@@ -505,7 +514,7 @@ public Span<Color> GetColors()
         /// <returns>BitmapImage image data</returns>
         public BitmapImage ToBitmapImage()
         {
-            return Bitmap.ToBitmapImage();
+            return UnsafeBitmap.ToBitmapImage();
         }
 
         /// <summary>
@@ -583,21 +592,18 @@ private static IEnumerable<PixelData> Convert(IEnumerable<(int x, int y, Color c
         /// </param>
         private void Dispose(bool disposing)
         {
-            if (Disposed)
-            {
-                return;
-            }
+            if (Disposed) return;
 
             if (disposing)
             {
-                // free managed resources
-                Bitmap?.Dispose();
+                // Managed resources (objects that implement IDisposable)
+                UnsafeBitmap?.Dispose();
+            }
 
-                // Free the GCHandle if it is allocated
-                if (BitsHandle.IsAllocated)
-                {
-                    BitsHandle.Free();
-                }
+            // Unmanaged resources/Handles (Free these always)
+            if (BitsHandle.IsAllocated)
+            {
+                BitsHandle.Free();
             }
 
             Disposed = true;

Imaging/DirectBitmapCore.cs

@@ -115,7 +115,8 @@ internal static unsafe void SetPixelsAdaptive(
         /// <param name="width">The width of the image.</param>
         /// <param name="height">The height of the image.</param>
         /// <param name="pixels">Enumerable of (x, y, Pixel32) tuples to set.</param>
-        internal static void SetPixelsSimd(Pixel32[] bits, int width, int height, IEnumerable<(int x, int y, Pixel32 color)> pixels)
+        internal static void SetPixelsSimd(Pixel32[] bits, int width, int height,
+            IEnumerable<(int x, int y, Pixel32 color)> pixels)
         {
             if (bits == null || pixels == null) return;
 
@@ -262,8 +263,20 @@ internal static unsafe void BlendInt(Pixel32[] dstBits, uint[] src)
                     uint s = *sPtr;
 
                     uint sa = s >> 24;
-                    if (sa == 0) { dPtr++; sPtr++; continue; }
-                    if (sa == 255) { *dPtr = s; dPtr++; sPtr++; continue; }
+                    if (sa == 0)
+                    {
+                        dPtr++;
+                        sPtr++;
+                        continue;
+                    }
+
+                    if (sa == 255)
+                    {
+                        *dPtr = s;
+                        dPtr++;
+                        sPtr++;
+                        continue;
+                    }
 
                     uint d = *dPtr;
 
@@ -293,4 +306,3 @@ internal static unsafe void BlendInt(Pixel32[] dstBits, uint[] src)
         }
     }
 }
-

Imaging/DirectBitmapImage.cs

@@ -165,7 +165,7 @@ public void SetPixel(int x, int y, Color color)
         ///     Fills the bitmap with a uniform color using SIMD.
         /// </summary>
         /// <param name="color">The color to fill with.</param>
-        public unsafe void FillSimd(Color color)
+        public void FillSimd(Color color)
         {
             var packed = (uint)(color.A << 24 | color.R << 16 | color.G << 8 | color.B);
 
@@ -268,11 +268,11 @@ public void UpdateBitmapFromBits()
             unsafe
             {
                 var dst = (Pixel32*)_bitmap.BackBuffer; // treat back buffer as Pixel32[]
-                var span = Bits.AsSpan();               // Pixel32[]
+                var span = Bits.AsSpan(); // Pixel32[]
 
                 for (int i = 0; i < span.Length; i++)
                 {
-                    dst[i] = span[i];                   // direct struct copy
+                    dst[i] = span[i]; // direct struct copy
                 }
             }