### Custom Image Type Adapter Implementation

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Example of implementing IImageConverter<TImage> for a hypothetical RawBitmap type. Converts between RawBitmap and Pixel[,] using linear-light double values.

```csharp
using Blurhash;
using Blurhash.Microsoft.Extensions.Core;

// Example: adapter for a hypothetical RawBitmap type
public class RawBitmapConverter : IImageConverter<RawBitmap>
{
    public Pixel[,] ImageToPixels(RawBitmap image)
    {
        var result = new Pixel[image.Width, image.Height];
        for (var x = 0; x < image.Width; x++)
        for (var y = 0; y < image.Height; y++)
        {
            var (r, g, b) = image.GetPixelRgb(x, y); // returns bytes 0–255
            result[x, y] = new Pixel(
                red:   MathUtils.SRgbToLinear(r),
                green: MathUtils.SRgbToLinear(g),
                blue:  MathUtils.SRgbToLinear(b)
            );
        }
        return result;
    }

    public RawBitmap PixelsToImage(Pixel[,] pixels)
    {
        var w = pixels.GetLength(0);
        var h = pixels.GetLength(1);
        var bmp = new RawBitmap(w, h);
        for (var x = 0; x < w; x++)
        for (var y = 0; y < h; y++)
        {
            var px = pixels[x, y];
            bmp.SetPixelRgb(x, y,
                (byte) MathUtils.LinearTosRgb(px.Red),
                (byte) MathUtils.LinearTosRgb(px.Green),
                (byte) MathUtils.LinearTosRgb(px.Blue)
            );
        }
        return bmp;
    }
}

// Registration
services.AddBlurhashCore();
services.AddSingleton<IImageConverter<RawBitmap>, RawBitmapConverter>();

```

--------------------------------

### Color Space Conversion Utilities

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Provides utilities for converting between sRGB and linear light color spaces, and a sign-preserving power function. Use SRgbToLinear for sRGB to linear conversion and LinearTosRgb for the inverse. SignPow is used internally for AC coefficient quantization.

```csharp
using Blurhash;

// sRGB (0–255) → linear light (0.0–1.0)
double linear0   = MathUtils.SRgbToLinear(0);   // 0.0
double linear128 = MathUtils.SRgbToLinear(128);  // ≈ 0.216
double linear255 = MathUtils.SRgbToLinear(255);  // 1.0

// Linear light (0.0–1.0) → sRGB (0–255)
int srgb0   = MathUtils.LinearTosRgb(0.0);  // 0
int srgb128 = MathUtils.LinearTosRgb(0.216); // ≈ 128
int srgb255 = MathUtils.LinearTosRgb(1.0);  // 255

// Sign-preserving power (used in AC coefficient quantisation)
double result = MathUtils.SignPow(-0.5, 2.0); // -(0.5^2.0) = -0.25
```

--------------------------------

### Generic Blurhasher Interface Usage

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Demonstrates using the generic IBlurhasher<TImage> interface for encoding and decoding images. Supports optional progress reporting.

```csharp
using Blurhash.Microsoft.Extensions.Core;
using System;

// Injected into a class via constructor injection
public class ThumbnailService
{
    private readonly IBlurhasher<MyImage> _blurhasher;

    public ThumbnailService(IBlurhasher<MyImage> blurhasher)
    {
        _blurhasher = blurhasher;
    }

    public string GenerateHash(MyImage image)
    {
        var progress = new Progress<int>(p =>
        {
            if (p % 10 == 0) Console.WriteLine($"Progress: {p}%");
        });

        // componentsX / componentsY: 1–9, higher = more detail, longer hash
        return _blurhasher.Encode(image, componentsX: 4, componentsY: 3, progressCallback: progress);
    }

    public MyImage GeneratePreview(string hash, int width, int height)
    {
        return _blurhasher.Decode(hash, width, height, punch: 1.0);
    }
}

```

--------------------------------

### AddBlurhash (System.Drawing)

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Registers the System.Drawing image stack for Blurhash. This includes core Blurhash functionality, an ImageConverter for System.Drawing.Image, and the IBlurhasher interface specific to System.Drawing.Image.

```APIDOC
## AddBlurhash (System.Drawing)

### Description
Registers the full System.Drawing stack in one call: calls `AddBlurhashCore`, registers `IImageConverter<Image>` with the built-in `ImageConverter`, and additionally registers the strongly-typed `IBlurhasher` (the System.Drawing-specific interface extending `IBlurhasher<Image>`)

### NuGet Package
`Blurhash.Microsoft.Extensions.System.Drawing` (4.0.0)

### Usage Example
```csharp
using Microsoft.Extensions.DependencyInjection;
using System.Drawing;
using Blurhash.Microsoft.Extensions.System.Drawing;
using Blurhash.Microsoft.Extensions.Core;

var services = new ServiceCollection();
services.AddBlurhash();  // registers IBlurhasher<Image> + IBlurhasher + IImageConverter<Image>

var provider = services.BuildServiceProvider();

// Inject via the strongly-typed System.Drawing interface
var blurhasher = provider.GetRequiredService<IBlurhasher>();

using Image photo = Image.FromFile("photo.jpg");

string hash = blurhasher.Encode(
    photo,
    componentsX: 4,
    componentsY: 3,
    progressCallback: new Progress<int>(p => Console.Write($"\r{p}%"))
);
Console.WriteLine($"\nHash: {hash}");

Image preview = blurhasher.Decode(hash, outputWidth: 32, outputHeight: 32, punch: 1.0);
preview.Save("preview.png");
```
```

--------------------------------

### System.Drawing Bridge for Blurhash

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Provides static methods to encode and decode images using System.Drawing.Image and System.Drawing.Bitmap. This bridge is Windows-only due to System.Drawing.Common constraints. It also includes helpers for manual conversion between Image and Pixel[,].

```csharp
using System.Drawing;
using System.Drawing.Blurhash;

// --- Encode ---
using Image sourceImage = Image.FromFile("photo.jpg");

string hash = Blurhasher.Encode(sourceImage, componentsX: 4, componentsY: 3);
Console.WriteLine($"Hash: {hash}");

// --- Decode ---
// outputWidth / outputHeight are the preview image dimensions (independent of original)
using Image preview = Blurhasher.Decode(hash, outputWidth: 32, outputHeight: 32, punch: 1.0);
preview.Save("preview.png");

// --- Low-level conversion helpers ---
Pixel[,] pixelArray = Blurhasher.ConvertBitmap(sourceImage);          // Image → Pixel[,]
Bitmap reconstructed = Blurhasher.ConvertToBitmap(pixelArray);        // Pixel[,] → Bitmap (32bpp RGB)
```

--------------------------------

### Register System.Drawing Blurhash DI

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Registers the full System.Drawing stack for Blurhash. Use this for applications already using System.Drawing.Image.

```csharp
using Microsoft.Extensions.DependencyInjection;
using System.Drawing;
using Blurhash.Microsoft.Extensions.System.Drawing;
using Blurhash.Microsoft.Extensions.Core;

var services = new ServiceCollection();
services.AddBlurhash();  // registers IBlurhasher<Image> + IBlurhasher + IImageConverter<Image>

var provider = services.BuildServiceProvider();

// Inject via the strongly-typed System.Drawing interface
var blurhasher = provider.GetRequiredService<IBlurhasher>();

using Image photo = Image.FromFile("photo.jpg");

string hash = blurhasher.Encode(
    photo,
    componentsX: 4,
    componentsY: 3,
    progressCallback: new Progress<int>(p => Console.Write($"\r{p}%"))
);
Console.WriteLine($"\nHash: {hash}");

Image preview = blurhasher.Decode(hash, outputWidth: 32, outputHeight: 32, punch: 1.0);
preview.Save("preview.png");

```

--------------------------------

### MathUtils - Color Space Conversion

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Provides utilities for converting between sRGB and linear color spaces, and a sign-preserving power function.

```APIDOC
## MathUtils

### Description
Provides the two color space helpers used throughout the library. `SRgbToLinear` applies the IEC 61966-2-1 sRGB → linear transfer function, and `LinearTosRgb` applies the inverse, clamping to [0, 255]. `SignPow` is a sign-preserving power function used internally by the AC coefficient quantisation step.

### Methods

#### `SRgbToLinear(int sRgbValue)`
Converts an sRGB color value (0-255) to linear light (0.0-1.0).

**Example:**
```csharp
double linear0   = MathUtils.SRgbToLinear(0);
double linear128 = MathUtils.SRgbToLinear(128);
double linear255 = MathUtils.SRgbToLinear(255);
```

#### `LinearTosRgb(double linearValue)`
Converts a linear light color value (0.0-1.0) to sRGB (0-255).

**Example:**
```csharp
int srgb0   = MathUtils.LinearTosRgb(0.0);
int srgb128 = MathUtils.LinearTosRgb(0.216);
int srgb255 = MathUtils.LinearTosRgb(1.0);
```

#### `SignPow(double baseValue, double exponent)`
Sign-preserving power function used internally by the AC coefficient quantisation step.

**Example:**
```csharp
double result = MathUtils.SignPow(-0.5, 2.0);
```
```

--------------------------------

### Dependency Injection Registration for Blurhash Core

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Registers IBlurhasher<TImage> as a singleton generic open-type in IServiceCollection. Requires a separate registration of an IImageConverter<TImage> implementation. Calling AddBlurhashCore multiple times is safe as it's idempotent.

```csharp
using Microsoft.Extensions.DependencyInjection;
using Blurhash.Microsoft.Extensions.Core;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;

// Custom converter for a hypothetical MyImage type
public class MyImageConverter : IImageConverter<MyImage>
{
    public Pixel[,] ImageToPixels(MyImage image)
    {
        var pixels = new Pixel[image.Width, image.Height];
        // ... populate pixels using MathUtils.SRgbToLinear(byteValue)
        return pixels;
    }

    public MyImage PixelsToImage(Pixel[,] pixels)
    {
        // ... convert back, using MathUtils.LinearTosRgb(pixel.Red) etc.
        return new MyImage(pixels);
    }
}

var services = new ServiceCollection();
services.AddBlurhashCore();                              // registers IBlurhasher<TImage>
services.AddSingleton<IImageConverter<MyImage>, MyImageConverter>();

var provider = services.BuildServiceProvider();
var blurhasher = provider.GetRequiredService<IBlurhasher<MyImage>>();

var myImage = LoadMyImage("photo.dat");
string hash = blurhasher.Encode(myImage, componentsX: 4, componentsY: 3);
MyImage preview = blurhasher.Decode(hash, outputWidth: 32, outputHeight: 32, punch: 1.0);
```

--------------------------------

### IImageConverter<TImage>

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Interface for custom image type adapters, allowing integration of unsupported image libraries.

```APIDOC
### `Blurhash.Microsoft.Extensions.Core.IImageConverter<TImage>` — Custom image type adapter

### Description
The interface to implement when integrating an unsupported image library. `ImageToPixels` must convert the image into a `Pixel[,]` using linear-light `double` values (apply `MathUtils.SRgbToLinear` on each sRGB byte). `PixelsToImage` performs the reverse, applying `MathUtils.LinearTosRgb` to get back sRGB bytes.

### Methods
- `ImageToPixels(TImage image)`: Converts an image of type `TImage` to a `Pixel[,]`.
- `PixelsToImage(Pixel[,] pixels)`: Converts a `Pixel[,]` back to an image of type `TImage`.

### Usage Example (Hypothetical RawBitmap)
```csharp
using Blurhash;
using Blurhash.Microsoft.Extensions.Core;

// Example: adapter for a hypothetical RawBitmap type
public class RawBitmapConverter : IImageConverter<RawBitmap>
{
    public Pixel[,] ImageToPixels(RawBitmap image)
    {
        var result = new Pixel[image.Width, image.Height];
        for (var x = 0; x < image.Width; x++)
        for (var y = 0; y < image.Height; y++)
        {
            var (r, g, b) = image.GetPixelRgb(x, y); // returns bytes 0–255
            result[x, y] = new Pixel(
                red:   MathUtils.SRgbToLinear(r),
                green: MathUtils.SRgbToLinear(g),
                blue:  MathUtils.SRgbToLinear(b)
            );
        }
        return result;
    }

    public RawBitmap PixelsToImage(Pixel[,] pixels)
    {
        var w = pixels.GetLength(0);
        var h = pixels.GetLength(1);
        var bmp = new RawBitmap(w, h);
        for (var x = 0; x < w; x++)
        for (var y = 0; y < h; y++)
        {
            var px = pixels[x, y];
            bmp.SetPixelRgb(x, y,
                (byte) MathUtils.LinearTosRgb(px.Red),
                (byte) MathUtils.LinearTosRgb(px.Green),
                (byte) MathUtils.LinearTosRgb(px.Blue)
            );
        }
        return bmp;
    }
}

// Registration
// Assuming services is an instance of Microsoft.Extensions.DependencyInjection.IServiceCollection
// services.AddBlurhashCore(); // If not already registered
// services.AddSingleton<IImageConverter<RawBitmap>, RawBitmapConverter>();
```
```

--------------------------------

### System.Drawing.Blurhash.Blurhasher - System.Drawing Bridge

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Provides static methods to encode and decode images using System.Drawing.Image and System.Drawing.Bitmap. This bridge is Windows-only.

```APIDOC
## Blurhasher (System.Drawing Bridge)

### Description
Provides `Encode` and `Decode` static methods that accept and return `System.Drawing.Image` / `System.Drawing.Bitmap` directly. `ConvertBitmap` and `ConvertToBitmap` are public helpers for manually converting between `System.Drawing.Image` and `Pixel[,]` when integrating with custom pipelines. **Windows-only** (System.Drawing.Common constraint).

### Methods

#### `Encode(Image sourceImage, int componentsX, int componentsY)`
Encodes a `System.Drawing.Image` into a Blurhash string.

**Parameters:**
- `sourceImage` (Image) - The source image to encode.
- `componentsX` (int) - The number of components in the X direction.
- `componentsY` (int) - The number of components in the Y direction.

**Returns:**
- `string` - The generated Blurhash string.

**Example:**
```csharp
using System.Drawing;
using System.Drawing.Blurhash;

using Image sourceImage = Image.FromFile("photo.jpg");
string hash = Blurhasher.Encode(sourceImage, componentsX: 4, componentsY: 3);
```

#### `Decode(string hash, int outputWidth, int outputHeight, double punch)`
Decodes a Blurhash string into a `System.Drawing.Image`.

**Parameters:**
- `hash` (string) - The Blurhash string to decode.
- `outputWidth` (int) - The desired width of the output image.
- `outputHeight` (int) - The desired height of the output image.
- `punch` (double) - The punch value to adjust the brightness and contrast.

**Returns:**
- `Image` - The decoded image.

**Example:**
```csharp
using System.Drawing;
using System.Drawing.Blurhash;

using Image preview = Blurhasher.Decode(hash, outputWidth: 32, outputHeight: 32, punch: 1.0);
preview.Save("preview.png");
```

#### `ConvertBitmap(Image sourceImage)`
Converts a `System.Drawing.Image` to a `Pixel[,]` array.

**Parameters:**
- `sourceImage` (Image) - The source image.

**Returns:**
- `Pixel[,]` - The pixel data as a 2D array.

**Example:**
```csharp
Pixel[,] pixelArray = Blurhasher.ConvertBitmap(sourceImage);
```

#### `ConvertToBitmap(Pixel[,] pixelArray)`
Converts a `Pixel[,]` array to a `System.Drawing.Bitmap` (32bpp RGB).

**Parameters:**
- `pixelArray` (Pixel[,]) - The pixel data as a 2D array.

**Returns:**
- `Bitmap` - The reconstructed Bitmap.

**Example:**
```csharp
Bitmap reconstructed = Blurhasher.ConvertToBitmap(pixelArray);
```
```

--------------------------------

### ImageSharp Bridge for Blurhash

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Enables encoding and decoding of images using ImageSharp's Image<Rgb24> and Image<Rgba32> types. The decoded image is always returned as Image<Rgb24>. Supports both Rgb24 and Rgba32 pixel formats for encoding. An ArgumentOutOfRangeException is thrown for unsupported pixel formats.

```csharp
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;
using Blurhash.ImageSharp;

// --- Encode from Rgb24 ---
using var imageRgb = await Image.LoadAsync<Rgb24>("photo.png");
string hash = Blurhasher.Encode(imageRgb, componentsX: 9, componentsY: 9);
Console.WriteLine(hash);
// e.g. "|20Ktja2e-eSe8g2e9gNene,dCg$gOf8gieTf+..."

// --- Encode from Rgba32 ---
using var imageRgba = await Image.LoadAsync<Rgba32>("photo.png");
string hashRgba = Blurhasher.Encode(imageRgba, componentsX: 4, componentsY: 3);

// --- Decode ---
Image<Rgb24> preview = Blurhasher.Decode(hash, outputWidth: 200, outputHeight: 200, punch: 1.0);
await preview.SaveAsPngAsync("preview.png");

// ArgumentOutOfRangeException if pixel format is not Rgb24 or Rgba32
```

--------------------------------

### Encode Image to BlurHash String

Source: https://github.com/markuspalcer/blurhash.net/blob/master/Readme.MD

This method encodes an image into a BlurHash string. Ensure you have a method to convert your image to a 2D array of Blurhash.Pixel.

```csharp
public static string Encode(Bitmap image)
{
    var pixels = new Pixel[image.Width, image.Height];
    for (var y = 0; y < image.Height; y++)
    {
        for (var x = 0; x < image.Width; x++)
        {
            var color = image.GetPixel(x, y);
            pixels[x, y] = new Pixel((byte)color.R, (byte)color.G, (byte)color.B, (byte)color.A);
        }
    }
    return Blurhash.Core.Encode(pixels, image.Width, image.Height, 4, 4);
}
```

--------------------------------

### Encode Pixel Array to BlurHash String

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Encodes a library-independent Pixel[,] array into a BlurHash string. Adjust componentsX and componentsY (1-9) to balance hash length and spatial fidelity. An optional progress callback can track encoding progress.

```csharp
using Blurhash;

// Build a synthetic 4×4 pixel array (linear light values 0.0–1.0)
var pixels = new Pixel[4, 4];
for (var x = 0; x < 4; x++)
for (var y = 0; y < 4; y++)
    pixels[x, y] = new Pixel(red: 0.5, green: 0.3, blue: 0.8);

// Encode with 4 x-components and 3 y-components
var progress = new Progress<int>(p => Console.WriteLine($"Encoding: {p}%"));
string hash = Core.Encode(pixels, componentsX: 4, componentsY: 3, progress);

Console.WriteLine(hash); // e.g. "UBF~Jmt7~qofofj[j[fQ..."

// Constraints enforced:
// componentsX must be 1–9 → ArgumentException otherwise
// componentsY must be 1–9 → ArgumentException otherwise
```

--------------------------------

### Decode BlurHash String to Image

Source: https://github.com/markuspalcer/blurhash.net/blob/master/Readme.MD

This method decodes a BlurHash string into a Pixel array, which can then be used to create an image. You will need a converter to transform the Pixel array into your desired image format.

```csharp
public static Bitmap Decode(string blurhash, int width, int height)
{
    var pixels = new Pixel[width, height];
    Blurhash.Core.Decode(blurhash, pixels, width, height, 4, 4);
    var image = new Bitmap(width, height);
    for (var y = 0; y < height; y++)
    {
        for (var x = 0; x < width; x++)
        {
            var pixel = pixels[x, y];
            image.SetPixel(x, y, Color.FromArgb(pixel.R, pixel.G, pixel.B));
        }
    }
    return image;
}
```

--------------------------------

### AddBlurhashCore - DI Registration

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Registers IBlurhasher<TImage> as a singleton generic open-type in the IServiceCollection for Dependency Injection.

```APIDOC
## AddBlurhashCore (Dependency Injection)

### Description
Registers `IBlurhasher<TImage>` as a singleton generic open-type in the `IServiceCollection`. Requires the caller to separately register an `IImageConverter<TImage>` implementation. Calling `AddBlurhashCore` a second time is idempotent — it checks for an existing registration.

### Methods

#### `AddBlurhashCore(this IServiceCollection services)`
Adds Blurhash core services to the specified `IServiceCollection`.

**Parameters:**
- `services` (IServiceCollection) - The service collection to add services to.

**Example:**
```csharp
using Microsoft.Extensions.DependencyInjection;
using Blurhash.Microsoft.Extensions.Core;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;

// Custom converter for a hypothetical MyImage type
public class MyImageConverter : IImageConverter<MyImage>
{
    public Pixel[,] ImageToPixels(MyImage image)
    {
        var pixels = new Pixel[image.Width, image.Height];
        // ... populate pixels using MathUtils.SRgbToLinear(byteValue)
        return pixels;
    }

    public MyImage PixelsToImage(Pixel[,] pixels)
    {
        // ... convert back, using MathUtils.LinearTosRgb(pixel.Red) etc.
        return new MyImage(pixels);
    }
}

var services = new ServiceCollection();
services.AddBlurhashCore(); // registers IBlurhasher<TImage>
services.AddSingleton<IImageConverter<MyImage>, MyImageConverter>();

var provider = services.BuildServiceProvider();
var blurhasher = provider.GetRequiredService<IBlurhasher<MyImage>>();

var myImage = LoadMyImage("photo.dat");
string hash = blurhasher.Encode(myImage, componentsX: 4, componentsY: 3);
MyImage preview = blurhasher.Decode(hash, outputWidth: 32, outputHeight: 32, punch: 1.0);
```
```

--------------------------------

### Decode BlurHash String to Pixel Array

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Decodes a BlurHash string into a pre-allocated Pixel[,] array. The punch parameter (default 1.0) adjusts contrast. Output dimensions are determined by the provided pixel array, independent of the original image size. Handles errors for short or malformed hash strings.

```csharp
using Blurhash;

string hash = "LGF5]+Yk^6#M@-5c,1J5@[or[Q6.";

// Allocate output at desired render resolution
var pixels = new Pixel[32, 32];

var progress = new Progress<int>(p => Console.WriteLine($"Decoding: {p}%"));
Core.Decode(hash, pixels, punch: 1.2, progressCallback: progress);

// Read back linear-light pixel values
var topLeft = pixels[0, 0];
Console.WriteLine($"R={topLeft.Red:F3} G={topLeft.Green:F3} B={topLeft.Blue:F3}");

// Convert to 8-bit sRGB manually if needed
int r8 = MathUtils.LinearTosRgb(topLeft.Red);
int g8 = MathUtils.LinearTosRgb(topLeft.Green);
int b8 = MathUtils.LinearTosRgb(topLeft.Blue);
Console.WriteLine($"sRGB: ({r8}, {g8}, {b8})");

// Error cases:
// hash.Length < 6   → ArgumentException("Blurhash value needs to be at least 6 characters")
// hash length mismatch to component count → ArgumentException("Blurhash value is missing data")
```

--------------------------------

### Blurhash Pixel Representation and Conversion

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Represents a pixel with linear-light RGB values as doubles in the range [0.0, 1.0]. Includes utility methods for converting between sRGB byte values and linear double values, essential for custom image format handling.

```csharp
using Blurhash;

// Construct from linear-light values
var pixel = new Pixel(red: 1.0, green: 0.0, blue: 0.0); // pure red in linear space

// Or mutate fields directly
pixel.Green = 0.5;

// Convert sRGB byte (0–255) → linear double
double linearValue = MathUtils.SRgbToLinear(128);  // ≈ 0.216

// Convert linear double → sRGB byte (0–255)
int srgbByte = MathUtils.LinearTosRgb(linearValue); // ≈ 128

Console.WriteLine($"Linear: {linearValue:F3}, sRGB: {srgbByte}");
```

--------------------------------

### Blurhash.Core.Decode

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Decodes a BlurHash string into a pixel array. The output dimensions are determined by the provided pixel array. A 'punch' parameter can adjust contrast, and progress can be monitored.

```APIDOC
## Blurhash.Core.Decode

### Description
Fills a pre-allocated `Pixel[,]` array by performing the inverse DCT from the Blurhash string. The `punch` parameter (default 1.0) amplifies or reduces contrast: values > 1 exaggerate colour, values < 1 tone it down. The output dimensions are determined entirely by the dimensions of the `pixels` array passed in — they are independent of the original image size.

### Method
`Core.Decode(string hash, Pixel[,] pixels, double punch = 1.0, IProgress<int> progressCallback = null)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```csharp
using Blurhash;

string hash = "LGF5]+Yk^6#M@-5c,1J5@[or[Q6.";

// Allocate output at desired render resolution
var pixels = new Pixel[32, 32];

var progress = new Progress<int>(p => Console.WriteLine($"Decoding: {p}%"));
Core.Decode(hash, pixels, punch: 1.2, progressCallback: progress);

// Read back linear-light pixel values
var topLeft = pixels[0, 0];
Console.WriteLine($"R={topLeft.Red:F3} G={topLeft.Green:F3} B={topLeft.Blue:F3}");

// Convert to 8-bit sRGB manually if needed
int r8 = MathUtils.LinearTosRgb(topLeft.Red);
int g8 = MathUtils.LinearTosRgb(topLeft.Green);
int b8 = MathUtils.LinearTosRgb(topLeft.Blue);
Console.WriteLine($"sRGB: ({r8}, {g8}, {b8})");

// Error cases:
// hash.Length < 6   → ArgumentException("Blurhash value needs to be at least 6 characters")
// hash length mismatch to component count → ArgumentException("Blurhash value is missing data")
```

### Response
#### Success Response (200)
This method modifies the `pixels` array in place. No direct return value is specified, but the `pixels` array will be populated.

#### Response Example
None provided, as the output is the modified `pixels` array.
```

--------------------------------

### IBlurhasher<TImage>

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

The central DI-injectable interface for encoding and decoding images. It is generic with respect to the image type.

```APIDOC
### `Blurhash.Microsoft.Extensions.Core.IBlurhasher<TImage>` — Generic Blurhasher interface

### Description
The central DI-injectable interface for encoding and decoding. The generic parameter `TImage` is the concrete image type. Both `Encode` and `Decode` accept an optional `IProgress<int>` for progress reporting. The `Blurhash.Microsoft.Extensions.System.Drawing.IBlurhasher` inherits from `IBlurhasher<Image>` to provide a non-generic convenience type for System.Drawing consumers.

### Methods
- `Encode(TImage image, int componentsX, int componentsY, IProgress<int>? progressCallback = null)`: Encodes an image into a Blurhash string.
- `Decode(string hash, int outputWidth, int outputHeight, double punch = 1.0)`: Decodes a Blurhash string into an image.

### Usage Example
```csharp
using Blurhash.Microsoft.Extensions.Core;
using System;

// Injected into a class via constructor injection
public class ThumbnailService
{
    private readonly IBlurhasher<MyImage> _blurhasher;

    public ThumbnailService(IBlurhasher<MyImage> blurhasher)
    {
        _blurhasher = blurhasher;
    }

    public string GenerateHash(MyImage image)
    {
        var progress = new Progress<int>(p =>
        {
            if (p % 10 == 0) Console.WriteLine($"Progress: {p}%");
        });

        // componentsX / componentsY: 1–9, higher = more detail, longer hash
        return _blurhasher.Encode(image, componentsX: 4, componentsY: 3, progressCallback: progress);
    }

    public MyImage GeneratePreview(string hash, int width, int height)
    {
        return _blurhasher.Decode(hash, width, height, punch: 1.0);
    }
}
```
```

--------------------------------

### Blurhash.ImageSharp.Blurhasher - ImageSharp Bridge

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Provides methods for encoding and decoding images using the ImageSharp library.

```APIDOC
## Blurhasher (ImageSharp Bridge)

### Description
Provides `Encode` and `Decode` methods for `SixLabors.ImageSharp.Image<Rgb24>` and `Image<Rgba32>`. The decoded image is returned as `Image<Rgb24>`. Supports both pixel formats for encoding.

### Methods

#### `Encode(Image<TPixel> image, int componentsX, int componentsY)`
Encodes an ImageSharp image into a Blurhash string. Supports `Image<Rgb24>` and `Image<Rgba32>`.

**Parameters:**
- `image` (Image<TPixel>) - The ImageSharp image to encode.
- `componentsX` (int) - The number of components in the X direction.
- `componentsY` (int) - The number of components in the Y direction.

**Returns:**
- `string` - The generated Blurhash string.

**Example (Rgb24):**
```csharp
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;
using Blurhash.ImageSharp;

using var imageRgb = await Image.LoadAsync<Rgb24>("photo.png");
string hash = Blurhasher.Encode(imageRgb, componentsX: 9, componentsY: 9);
```

**Example (Rgba32):**
```csharp
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;
using Blurhash.ImageSharp;

using var imageRgba = await Image.LoadAsync<Rgba32>("photo.png");
string hashRgba = Blurhasher.Encode(imageRgba, componentsX: 4, componentsY: 3);
```

#### `Decode(string hash, int outputWidth, int outputHeight, double punch)`
Decodes a Blurhash string into an `Image<Rgb24>`.

**Parameters:**
- `hash` (string) - The Blurhash string to decode.
- `outputWidth` (int) - The desired width of the output image.
- `outputHeight` (int) - The desired height of the output image.
- `punch` (double) - The punch value to adjust the brightness and contrast.

**Returns:**
- `Image<Rgb24>` - The decoded image.

**Throws:**
- `ArgumentOutOfRangeException` - If the pixel format is not Rgb24 or Rgba32 during encoding.

**Example:**
```csharp
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;
using Blurhash.ImageSharp;

Image<Rgb24> preview = Blurhasher.Decode(hash, outputWidth: 200, outputHeight: 200, punch: 1.0);
await preview.SaveAsPngAsync("preview.png");
```
```

--------------------------------

### Blurhash.Core.Encode

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Encodes a pixel array into a BlurHash string. Allows control over the trade-off between hash length and spatial fidelity using component counts. Progress can be tracked via an optional callback.

```APIDOC
## Blurhash.Core.Encode

### Description
Performs the DCT-based BlurHash encoding on a library-independent `Pixel[,]` array. `componentsX` and `componentsY` (1–9 each) control the trade-off between hash length and the spatial fidelity of the resulting blur. Higher values produce a longer string but richer gradients. An optional `IProgress<int>` reports percentage completion during the nested loop.

### Method
`Core.Encode(Pixel[,] pixels, int componentsX, int componentsY, IProgress<int> progress = null)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```csharp
using Blurhash;

// Build a synthetic 4×4 pixel array (linear light values 0.0–1.0)
var pixels = new Pixel[4, 4];
for (var x = 0; x < 4; x++)
for (var y = 0; y < 4; y++)
    pixels[x, y] = new Pixel(red: 0.5, green: 0.3, blue: 0.8);

// Encode with 4 x-components and 3 y-components
var progress = new Progress<int>(p => Console.WriteLine($"Encoding: {p}%"));
string hash = Core.Encode(pixels, componentsX: 4, componentsY: 3, progress);

Console.WriteLine(hash); // e.g. "UBF~Jmt7~qofofj[j[fQ..."

// Constraints enforced:
// componentsX must be 1–9 → ArgumentException otherwise
// componentsY must be 1–9 → ArgumentException otherwise
```

### Response
#### Success Response (200)
- **hash** (string) - The generated BlurHash string.

#### Response Example
```json
{
  "hash": "UBF~Jmt7~qofofj[j[fQ..."
}
```
```

--------------------------------

### Blurhash.Pixel

Source: https://context7.com/markuspalcer/blurhash.net/llms.txt

Represents a pixel with linear-light RGB color values. Provides utility methods for converting between linear light and sRGB color spaces.

```APIDOC
## Blurhash.Pixel

### Description
A lightweight `struct` carrying linear-light (not gamma-encoded) red, green, and blue channel values as `double` fields. Values are expected in the range `[0.0, 1.0]`. All bridge converters populate and read this struct; callers implementing custom converters must populate it using `MathUtils.SRgbToLinear`.

### Fields
- **Red** (double) - The red channel value in linear light space (0.0 to 1.0).
- **Green** (double) - The green channel value in linear light space (0.0 to 1.0).
- **Blue** (double) - The blue channel value in linear light space (0.0 to 1.0).

### Methods
- `Pixel(double red, double green, double blue)`: Constructor to create a new Pixel.
- `MathUtils.SRgbToLinear(int sRgbValue)`: Converts an 8-bit sRGB value (0-255) to a linear light double.
- `MathUtils.LinearTosRgb(double linearValue)`: Converts a linear light double to an 8-bit sRGB value (0-255).

### Request Example
```csharp
using Blurhash;

// Construct from linear-light values
var pixel = new Pixel(red: 1.0, green: 0.0, blue: 0.0); // pure red in linear space

// Or mutate fields directly
pixel.Green = 0.5;

// Convert sRGB byte (0–255) → linear double
double linearValue = MathUtils.SRgbToLinear(128);  // ≈ 0.216

// Convert linear double → sRGB byte (0–255)
int srgbByte = MathUtils.LinearTosRgb(linearValue); // ≈ 128

Console.WriteLine($"Linear: {linearValue:F3}, sRGB: {srgbByte}");
```

### Response
#### Success Response (200)
Represents a pixel with `Red`, `Green`, and `Blue` double fields.

#### Response Example
```json
{
  "Red": 0.5,
  "Green": 0.3,
  "Blue": 0.8
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.