👁 Image
GlitchedPolygons.ThumbHash 1.4.1

GlitchedPolygons.ThumbHash:

👁 NuGet

GlitchedPolygons.ThumbHash.Img:

👁 NuGet

ThumbHash .NET Port

A very compact representation of an image placeholder for .NET 10+

This is a high-performance, memory-friendly C# port of the original ThumbHash implementation. ThumbHash allows you to store a tiny hash (usually around ~20 bytes) of an image and render a blurred version while the full image loads.

Why ThumbHash?

Compared to BlurHash, ThumbHash offers:

• Better Detail: Encodes more detail in the same amount of space.
• Aspect Ratio: The hash itself encodes the image's original aspect ratio.
• Alpha Channel: Full support for images with transparency.
• Improved Colors: More accurate color representation.

Quick Start

1. Encoding an Image

To create a hash, you need the raw RGBA pixel data of your image. Note: The input image must be ≤ 100x100 pixels for performance reasons.

Scale your image down before encoding.

// w: width, h: height, rgba: ReadOnlySpan<byte> of pixel data
Span<byte> hash = ThumbHashConvert.FromRgba(width, height, rgba);

// Store this small byte array in your database or alongside the 
// original image to render while the full resolution version is loading.
string base64Hash = Convert.ToBase64String(hash);

2. Decoding to a Data URL

The easiest way to show a placeholder in a web application is to generate a data:image/png;base64 string.

string dataUrl = ThumbHashConvert.ToDataUrl(hash);
// Result: "data:image/png;base64,iVBORw0KGgoAAAAN..."

3. Decoding to Raw Pixels

If you need to render the image yourself (e.g., in a desktop or mobile app):

(int w, int h, byte[] rgba) = ThumbHashConvert.ToRgba(hash);

Performance

This implementation is designed with performance in mind:

• It uses Span<T> to minimize memory allocations.
• Utilizes ArrayPool<T> for internal buffers to reduce GC pressure.
• Targets .NET 10 (LTS at the time of writing) or higher and allocates small buffers using stackalloc where possible for best performance.

Usage Tips

• Pre-scaling: Always scale your images down to roughly 100x100 or smaller before passing them to ThumbHashConvert.FromRgba.
• Browser usage: You can use the generated Data URL directly as the src attribute of an <img> tag or as a CSS background-image.

License

This project is licensed under the MIT License - same as the original implementation by Evan Wallace.