FrameworkExtensions.System.Drawing 1.0.0.91

Extensions to System.Drawing

Extension methods for System.Drawing types (bitmaps, images, colors, graphics).

Extension Methods

Bitmap Extensions (Bitmap)

Bitmap Locking

• Lock(...) - Lock bitmap for direct pixel access (8 overloads for different combinations)
  • Lock() - Lock entire bitmap with ReadWrite mode
  • Lock(Rectangle) - Lock region
  • Lock(ImageLockMode) - Lock with specific mode
  • Lock(PixelFormat) - Lock with specific format
  • Lock(Rectangle, ImageLockMode)
  • Lock(Rectangle, PixelFormat)
  • Lock(ImageLockMode, PixelFormat)
  • Lock(Rectangle, ImageLockMode, PixelFormat) - Full control
  • Returns format-specific IBitmapLocker implementation

Transformations

• ConvertPixelFormat(PixelFormat) - Convert bitmap to different pixel format
• Crop(Rectangle, PixelFormat = DontCare) - Extract region from bitmap
• Resize(int width, int height, InterpolationMode = Bicubic) - Resize bitmap
• Rotated(float angle, Point? center = null) - Create rotated copy of bitmap
• RotateInplace(float angle, Point? center = null) - Rotate bitmap in-place
• RotateTo(Bitmap target, float angle, Point? center = null) - Rotate to target bitmap

Color Quantization & Dithering

• ReduceColors<TQuantizer, TDitherer>(quantizer, ditherer, colorCount, isHighQuality) - Reduce image to indexed palette
  • Returns indexed bitmap (1bpp for 2 colors, 4bpp for ≤16, 8bpp for ≤256)
  • isHighQuality: true uses OkLab perceptual color space (slower, better gradients)
  • isHighQuality: false uses linear RGB with Euclidean distance (faster)

using var original = new Bitmap("photo.png");

// High quality: OkLab color space, Floyd-Steinberg dithering
using var indexed = original.ReduceColors(
    new WuQuantizer(),
    ErrorDiffusion.FloydSteinberg,
    16,
    isHighQuality: true);

// Fast: Linear RGB, serpentine dithering
using var fast = original.ReduceColors(
    new OctreeQuantizer(),
    ErrorDiffusion.Atkinson.Serpentine,
    256,
    isHighQuality: false);

indexed.Save("indexed.gif");

Image Extensions (Image)

Multi-Page Support

• GetPageAt(int page) - Get specific page from multi-page image (e.g., TIFF)
• GetPageCount() - Get total number of pages in image

Save Operations

• SaveToPng(FileInfo/string) - Save image as PNG
• SaveToTiff(string) - Save image as TIFF
• SaveToJpeg(string/Stream, double quality = 1) - Save as JPEG with quality (0.0-1.0)

Conversions

• ToIcon(int targetRes = 0) - Convert image to Icon
• ToBase64DataUri() - Convert to Base64 data URI string
• FromBase64DataUri(string) (static-like extension on string) - Create image from Base64 data URI

Image Processing

• MakeGrayscale() - Convert image to grayscale
• Threshold(byte threshold = 127) - Apply threshold filter (black/white)
• ApplyPixelProcessor(Func<Color, Color> processor) - Apply custom pixel transformation function
• MirrorAlongX() - Mirror horizontally
• MirrorAlongY() - Mirror vertically
• Resize(int longSide) - Resize to fit within square, keep aspect
• Resize(int longSide, Color fillColor) - Resize with fill color
• Resize(int width, int height, bool keepAspect = true, Color? fillColor = null) - Resize with options
• Resize(int width = -1, int height = -1, InterpolationMode = Default) - Resize with interpolation
• Rotate(float angle) - Rotate image by angle
• GetRectangle(Rectangle) - Extract rectangular region
• ReplaceColorWithTransparency(Color) - Replace specific color with transparency

Color Extensions (Color)

Color Space Conversion

• Rgb / RgbNormalized - Convert to RGB color space
• Hsl / HslNormalized - Convert to HSL (Hue, Saturation, Lightness)
• Hsv / HsvNormalized - Convert to HSV (Hue, Saturation, Value)
• Hwb / HwbNormalized - Convert to HWB (Hue, Whiteness, Blackness)
• Cmyk / CmykNormalized - Convert to CMYK (Cyan, Magenta, Yellow, Key)
• Xyz / XyzNormalized - Convert to CIE XYZ tristimulus values
• Lab / LabNormalized - Convert to CIE Lab* perceptual color space
• Yuv / YuvNormalized - Convert to YUV (Luma + chrominance)
• YCbCr / YCbCrNormalized - Convert to YCbCr digital video encoding
• Din99 / Din99Normalized - Convert to DIN99 (DIN 6176) perceptual space

Color Comparison

• IsLike(Color other, byte luminanceDelta = 24, byte chromaUDelta = 7, byte chromaVDelta = 6) - Compare colors in YUV space with tolerance
• IsLikeNaive(Color other, int tolerance = 2) - Simple RGB comparison with tolerance

Color Blending

• BlendWith(Color other, float current, float max) - Interpolate between two colors

Graphics Extensions (Graphics)

• DrawString(float x, float y, string text, Font font, Brush brush, ContentAlignment anchor) - Draw text with anchor positioning
• DrawCross(float/int x, float/int y, float/int size, Pen pen) - Draw cross marker (4 overloads including Point/PointF)
• DrawCircle(Pen pen, float centerX, float centerY, float radius) - Draw circle outline
• FillCircle(Brush brush, float centerX, float centerY, float radius) - Draw filled circle

Rectangle Extensions (Rectangle)

• MultiplyBy(int factor) - Scale rectangle uniformly
• MultiplyBy(int xfactor, int yfactor) - Scale rectangle with different X/Y factors
• CollidesWith(Rectangle/RectangleF) - Check rectangle collision
• CollidesWith(Point/PointF) - Check if point is inside
• CollidesWith(int x, int y) / CollidesWith(float x, float y) - Check if coordinates are inside
• Center() - Get center point
• SetLeft/SetRight/SetTop/SetBottom(int) - Create new rectangle with modified edge

RectangleF Extensions (RectangleF)

(Similar methods to Rectangle, for floating-point rectangles)

Size Extensions (Size)

• Center() - Get center point

Point Extensions (Point)

(Generated from T4 template - numeric operations on points)

FileInfo Extensions (FileInfo)

• GetIcon(bool smallIcon = false, bool linkOverlay = false) - Get Windows shell icon for file
  • Uses native SHGetFileInfo API

Custom Types

IBitmapLocker Interface

Format-specific bitmap pixel access implementations:

• ARGB32BitmapLocker - 32-bit ARGB (Format32bppArgb)
• RGB32BitmapLocker - 32-bit RGB (Format32bppRgb)
• RGB24BitmapLocker - 24-bit RGB (Format24bppRgb)
• RGB565BitmapLocker - 16-bit RGB 565 (Format16bppRgb565)
• ARGB1555BitmapLocker - 16-bit ARGB 1555 (Format16bppArgb1555)
• Gray16BitmapLocker - 16-bit grayscale (Format16bppGrayScale)
• RGB555BitmapLocker - 16-bit RGB 555 (Format16bppRgb555)
• Indexed8BitmapLocker - 8-bit indexed (Format8bppIndexed)
• IndexedBitmapLocker - 1-bit and 4-bit indexed (Format1bppIndexed, Format4bppIndexed)
• UnsupportedDrawingBitmapLocker - Fallback for unsupported formats

Each locker provides optimized pixel access for its specific format.

Color Spaces (System.Drawing.ColorSpaces)

A comprehensive color space conversion and comparison library with zero-cost generic abstractions.

Color Space Types

Distance Calculators (System.Drawing.ColorSpaces.Distances)

All calculators also have *Squared variants for faster comparisons.

Palette Lookup

using Hawkynt.ColorProcessing;
using Hawkynt.ColorProcessing.Metrics;
using Hawkynt.ColorProcessing.Working;

// Convert palette to working color space
LinearRgbaF[] workPalette = palette.Select(c => /* decode to LinearRgbaF */).ToArray();

// Create lookup with metric (auto-caches results)
var lookup = new PaletteLookup<LinearRgbaF, EuclideanSquared4F<LinearRgbaF>>(
    workPalette,
    default);

// Find nearest palette color
int index = lookup.FindNearest(targetColor);
LinearRgbaF nearest = lookup.FindNearestColor(targetColor);

// Repeated lookups are O(1) due to built-in caching
foreach (var pixel in imagePixels) {
  var paletteIndex = lookup.FindNearest(pixel);  // Cached after first lookup
}

Color Interpolation (System.Drawing.ColorSpaces.Interpolation)

using System.Drawing.ColorSpaces.Interpolation;

// Interpolate in perceptual Lab space
var lerp = new ColorLerp<Lab>();
var midpoint = lerp.Lerp(color1, color2, 0.5f);

// Create smooth gradients
var gradient = new ColorGradient<Hsl>(Color.Red, Color.Blue);
var colors = gradient.GetColors(10);  // 10 evenly-spaced colors

Color Quantization

Quantizers reduce the number of colors in an image to generate optimized palettes.

Available Quantizers

// Generate palette from colors
var quantizer = new WuQuantizer();
Bgra8888[] palette = quantizer.GeneratePalette(colors, 16);

// Generate from histogram (weighted by frequency)
var histogram = new List<(Bgra8888 color, uint count)> { ... };
Bgra8888[] palette = quantizer.GeneratePalette(histogram, 256);

K-Means Color Metrics

The KMeansQuantizer supports any IColorMetric<Bgra8888> for clustering. See Color Metrics for all available metrics.

// Default K-Means (squared Euclidean - fastest)
var kmeans = new KMeansQuantizer();

// With perceptual Lab-based distance
var perceptual = new KMeansQuantizer<CIEDE2000>();

// With weighted RGB perception
var weighted = new KMeansQuantizer<PngQuantDistance>(default);

// With custom iterations
var custom = new KMeansQuantizer { MaxIterations = 200, ConvergenceThreshold = 0.0001f };

Dithering

Error diffusion dithering distributes quantization error to neighboring pixels for smoother gradients.

Available Ditherers

Ordered Dithering

Ordered dithering uses threshold matrices to determine pixel output. Unlike error diffusion, pixels can be processed independently (parallelizable).

// Ordered dithering with Bayer matrix
var ditherer = OrderedDitherer.Bayer8x8;

// Adjust strength (0.0 - 1.0)
var reduced = OrderedDitherer.Bayer4x4.WithStrength(0.5f);

Noise Dithering

Noise dithering adds random or pseudo-random thresholds before quantization. Can be processed in parallel.

// Noise dithering
var ditherer = NoiseDitherer.BlueNoise;

// Other noise types
var pink = NoiseDitherer.PinkNoise;     // More natural than white
var brown = NoiseDitherer.BrownNoise;   // Smooth, organic appearance
var violet = NoiseDitherer.VioletNoise; // Sharp, textured
var grey = NoiseDitherer.GreyNoise;     // Perceptually uniform

// Adjust strength and seed
var custom = NoiseDitherer.WhiteNoise.WithStrength(0.8f).WithSeed(12345);

Ditherer Configuration

// Basic usage
var ditherer = ErrorDiffusion.FloydSteinberg;

// Enable serpentine scanning (reduces artifacts)
var serpentine = ErrorDiffusion.FloydSteinberg.Serpentine;

// Adjust strength (0.0 - 1.0)
var reduced = ErrorDiffusion.Atkinson.WithStrength(0.75f);

// Combine options
var custom = ErrorDiffusion.JarvisJudiceNinke.Serpentine.WithStrength(0.9f);

Installation

dotnet add package FrameworkExtensions.System.Drawing

License

LGPL 3.0 or later - See LICENSE for details