|
| 1 | +<!DOCTYPE html> |
| 2 | +<html> |
| 3 | + <head> |
| 4 | + <meta charset="utf-8"> |
| 5 | + <title>Blur Hash | SkiaSharp.Extended </title> |
| 6 | + <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| 7 | + <meta name="title" content="Blur Hash | SkiaSharp.Extended "> |
| 8 | + |
| 9 | + <link rel="icon" href="../images/logo.ico"> |
| 10 | + <link rel="stylesheet" href="../public/docfx.min.css"> |
| 11 | + <link rel="stylesheet" href="../public/main.css"> |
| 12 | + <meta name="docfx:navrel" content="../toc.html"> |
| 13 | + <meta name="docfx:tocrel" content="toc.html"> |
| 14 | + |
| 15 | + <meta name="docfx:rel" content="../"> |
| 16 | + |
| 17 | + |
| 18 | + <meta name="docfx:docurl" content="https://github.com/mono/SkiaSharp.Extended/blob/362/merge/docs/docs/blurhash.md/#L1"> |
| 19 | + <meta name="loc:inThisArticle" content="In this article"> |
| 20 | + <meta name="loc:searchResultsCount" content="{count} results for "{query}""> |
| 21 | + <meta name="loc:searchNoResults" content="No results for "{query}""> |
| 22 | + <meta name="loc:tocFilter" content="Filter by title"> |
| 23 | + <meta name="loc:nextArticle" content="Next"> |
| 24 | + <meta name="loc:prevArticle" content="Previous"> |
| 25 | + <meta name="loc:themeLight" content="Light"> |
| 26 | + <meta name="loc:themeDark" content="Dark"> |
| 27 | + <meta name="loc:themeAuto" content="Auto"> |
| 28 | + <meta name="loc:changeTheme" content="Change theme"> |
| 29 | + <meta name="loc:copy" content="Copy"> |
| 30 | + <meta name="loc:downloadPdf" content="Download PDF"> |
| 31 | + </head> |
| 32 | + |
| 33 | + <script type="module" src="./../public/docfx.min.js"></script> |
| 34 | + |
| 35 | + <script> |
| 36 | + const theme = localStorage.getItem('theme') || 'auto' |
| 37 | + document.documentElement.setAttribute('data-bs-theme', theme === 'auto' ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') : theme) |
| 38 | + </script> |
| 39 | + |
| 40 | + |
| 41 | + <body class="tex2jax_ignore" data-layout="" data-yaml-mime=""> |
| 42 | + <header class="bg-body border-bottom"> |
| 43 | + <nav id="autocollapse" class="navbar navbar-expand-md" role="navigation"> |
| 44 | + <div class="container-xxl flex-nowrap"> |
| 45 | + <a class="navbar-brand" href="../index.html"> |
| 46 | + <img id="logo" class="svg" src="../images/logo.png" alt=""> |
| 47 | + |
| 48 | + </a> |
| 49 | + <button class="btn btn-lg d-md-none border-0" type="button" data-bs-toggle="collapse" data-bs-target="#navpanel" aria-controls="navpanel" aria-expanded="false" aria-label="Toggle navigation"> |
| 50 | + <i class="bi bi-three-dots"></i> |
| 51 | + </button> |
| 52 | + <div class="collapse navbar-collapse" id="navpanel"> |
| 53 | + <div id="navbar"> |
| 54 | + <form class="search" role="search" id="search"> |
| 55 | + <i class="bi bi-search"></i> |
| 56 | + <input class="form-control" id="search-query" type="search" disabled="" placeholder="Search" autocomplete="off" aria-label="Search"> |
| 57 | + </form> |
| 58 | + </div> |
| 59 | + </div> |
| 60 | + </div> |
| 61 | + </nav> |
| 62 | + </header> |
| 63 | + |
| 64 | + <main class="container-xxl"> |
| 65 | + <div class="toc-offcanvas"> |
| 66 | + <div class="offcanvas-md offcanvas-start" tabindex="-1" id="tocOffcanvas" aria-labelledby="tocOffcanvasLabel"> |
| 67 | + <div class="offcanvas-header"> |
| 68 | + <h5 class="offcanvas-title" id="tocOffcanvasLabel">Table of Contents</h5> |
| 69 | + <button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#tocOffcanvas" aria-label="Close"></button> |
| 70 | + </div> |
| 71 | + <div class="offcanvas-body"> |
| 72 | + <nav class="toc" id="toc"></nav> |
| 73 | + </div> |
| 74 | + </div> |
| 75 | + </div> |
| 76 | + |
| 77 | + <div class="content"> |
| 78 | + <div class="actionbar"> |
| 79 | + <button class="btn btn-lg border-0 d-md-none" style="margin-top: -.65em; margin-left: -.8em" type="button" data-bs-toggle="offcanvas" data-bs-target="#tocOffcanvas" aria-controls="tocOffcanvas" aria-expanded="false" aria-label="Show table of contents"> |
| 80 | + <i class="bi bi-list"></i> |
| 81 | + </button> |
| 82 | + |
| 83 | + <nav id="breadcrumb"></nav> |
| 84 | + </div> |
| 85 | + |
| 86 | + <article data-uid=""> |
| 87 | +<h1 id="blur-hash">Blur Hash</h1> |
| 88 | + |
| 89 | +<div class="TIP"> |
| 90 | +<h5>Tip</h5> |
| 91 | +<p><strong><a href="../sample/blurhash">Try it live →</a></strong> — Interactive BlurHash demo in the Blazor sample app.</p> |
| 92 | +</div> |
| 93 | +<p>Blur Hash is a compact representation of an image placeholder. Instead of loading a grey box while your image loads, you can show a colorful blur that hints at the final image—all from a tiny string that's only 20-30 characters.</p> |
| 94 | +<table> |
| 95 | +<thead> |
| 96 | +<tr> |
| 97 | +<th style="text-align: center;">Original</th> |
| 98 | +<th style="text-align: center;">Blur Hash Placeholder</th> |
| 99 | +</tr> |
| 100 | +</thead> |
| 101 | +<tbody> |
| 102 | +<tr> |
| 103 | +<td style="text-align: center;"><img src="../images/extended/skblurhash/logo.png" alt="Original"></td> |
| 104 | +<td style="text-align: center;"><img src="../images/extended/skblurhash/blur.png" alt="BlurHash"></td> |
| 105 | +</tr> |
| 106 | +</tbody> |
| 107 | +</table> |
| 108 | +<p>The hash for this image is just 28 characters: <code>LjPsbRxG%gx^aJxuM|W=?^X8Mxn$</code></p> |
| 109 | +<h2 id="quick-start">Quick Start</h2> |
| 110 | +<h3 id="encode-an-image">Encode an image</h3> |
| 111 | +<pre><code class="lang-csharp">using SkiaSharp; |
| 112 | +using SkiaSharp.Extended; |
| 113 | + |
| 114 | +using var bitmap = SKBitmap.Decode("photo.jpg"); |
| 115 | +string hash = SKBlurHash.Serialize(bitmap, 4, 3); |
| 116 | +// Returns something like: "LjPsbRxG%gx^aJxuM|W=?^X8Mxn$" |
| 117 | +</code></pre> |
| 118 | +<h3 id="decode-a-placeholder">Decode a placeholder</h3> |
| 119 | +<pre><code class="lang-csharp">var placeholder = SKBlurHash.DeserializeBitmap(hash, 32, 32); |
| 120 | +// Use this blurred bitmap while the real image loads |
| 121 | +</code></pre> |
| 122 | +<h2 id="how-it-works">How It Works</h2> |
| 123 | +<p>Blur Hash uses a technique similar to JPEG compression called the <a href="https://en.wikipedia.org/wiki/Discrete_cosine_transform">Discrete Cosine Transform</a> (DCT). It extracts the dominant color patterns from an image and encodes them into a short ASCII string.</p> |
| 124 | +<p>The <code>componentsX</code> and <code>componentsY</code> parameters control how much detail is captured:</p> |
| 125 | +<p><img src="../images/extended/skblurhash/components-comparison.png" alt="Components comparison"></p> |
| 126 | +<p>More components = more detail, but a longer string. For most use cases, <strong>4x3 is a good default</strong>.</p> |
| 127 | +<h2 id="customization">Customization</h2> |
| 128 | +<h3 id="components">Components</h3> |
| 129 | +<p>The component count (1-9 for each axis) determines the level of detail:</p> |
| 130 | +<table> |
| 131 | +<thead> |
| 132 | +<tr> |
| 133 | +<th style="text-align: center;">Components</th> |
| 134 | +<th style="text-align: center;">String Length</th> |
| 135 | +<th style="text-align: left;">Best For</th> |
| 136 | +</tr> |
| 137 | +</thead> |
| 138 | +<tbody> |
| 139 | +<tr> |
| 140 | +<td style="text-align: center;">2x2</td> |
| 141 | +<td style="text-align: center;">~12 chars</td> |
| 142 | +<td style="text-align: left;">Simple gradients</td> |
| 143 | +</tr> |
| 144 | +<tr> |
| 145 | +<td style="text-align: center;">4x3</td> |
| 146 | +<td style="text-align: center;">~28 chars</td> |
| 147 | +<td style="text-align: left;">Most images (recommended)</td> |
| 148 | +</tr> |
| 149 | +<tr> |
| 150 | +<td style="text-align: center;">6x6</td> |
| 151 | +<td style="text-align: center;">~76 chars</td> |
| 152 | +<td style="text-align: left;">Complex images with fine detail</td> |
| 153 | +</tr> |
| 154 | +</tbody> |
| 155 | +</table> |
| 156 | +<h3 id="punch">Punch</h3> |
| 157 | +<p>The <code>punch</code> parameter adjusts the contrast of the decoded image. Values greater than 1.0 make colors more vibrant:</p> |
| 158 | +<p><img src="../images/extended/skblurhash/punch-comparison.png" alt="Punch comparison"></p> |
| 159 | +<pre><code class="lang-csharp">// Default punch (1.0) |
| 160 | +var normal = SKBlurHash.DeserializeBitmap(hash, 32, 32); |
| 161 | + |
| 162 | +// More vibrant (1.5) |
| 163 | +var vibrant = SKBlurHash.DeserializeBitmap(hash, 32, 32, punch: 1.5f); |
| 164 | +</code></pre> |
| 165 | +<h3 id="placeholder-size">Placeholder Size</h3> |
| 166 | +<p>The decoded placeholder doesn't need to match your final image size. A small size like 32x32 is usually sufficient—it will be scaled up and displayed blurred anyway.</p> |
| 167 | +<h2 id="usage-patterns">Usage Patterns</h2> |
| 168 | +<h3 id="include-in-api-responses">Include in API responses</h3> |
| 169 | +<p>Pre-compute hashes on your server and include them with image URLs:</p> |
| 170 | +<pre><code class="lang-json">{ |
| 171 | + "imageUrl": "https://example.com/photo.jpg", |
| 172 | + "blurHash": "LjPsbRxG%gx^aJxuM|W=?^X8Mxn$", |
| 173 | + "width": 1920, |
| 174 | + "height": 1080 |
| 175 | +} |
| 176 | +</code></pre> |
| 177 | +<h3 id="maui-value-converter">MAUI value converter</h3> |
| 178 | +<p>Create a converter to decode blur hashes directly in XAML bindings:</p> |
| 179 | +<pre><code class="lang-csharp">using System.Globalization; |
| 180 | +using SkiaSharp; |
| 181 | +using SkiaSharp.Extended; |
| 182 | +using SkiaSharp.Views.Maui.Controls; |
| 183 | + |
| 184 | +public class BlurHashConverter : IValueConverter |
| 185 | +{ |
| 186 | + public int Width { get; set; } = 32; |
| 187 | + public int Height { get; set; } = 32; |
| 188 | + |
| 189 | + public object? Convert(object? value, Type targetType, object? parameter, CultureInfo culture) |
| 190 | + { |
| 191 | + if (value is string hash && !string.IsNullOrEmpty(hash)) |
| 192 | + { |
| 193 | + var bitmap = SKBlurHash.DeserializeBitmap(hash, Width, Height); |
| 194 | + return (SKBitmapImageSource)bitmap; |
| 195 | + } |
| 196 | + return null; |
| 197 | + } |
| 198 | + |
| 199 | + public object? ConvertBack(object? value, Type targetType, object? parameter, CultureInfo culture) |
| 200 | + => throw new NotImplementedException(); |
| 201 | +} |
| 202 | +</code></pre> |
| 203 | +<p>Then use it in XAML:</p> |
| 204 | +<pre><code class="lang-xml"><Image Source="{Binding BlurHash, Converter={StaticResource BlurHashConverter}}" /> |
| 205 | +</code></pre> |
| 206 | +<h2 id="learn-more">Learn More</h2> |
| 207 | +<ul> |
| 208 | +<li><a href="https://blurha.sh/">BlurHash.sh</a> — Official demo and explanation</li> |
| 209 | +<li><a href="https://github.com/woltapp/blurhash">BlurHash GitHub</a> — Original algorithm by Dag Ågren at Wolt</li> |
| 210 | +<li><a href="https://careers.wolt.com/en/blog/tech/how-we-came-to-create-a-new-image-placeholder-algorithm-blurhash">How Wolt created BlurHash</a> — The origin story</li> |
| 211 | +<li><a href="xref:SkiaSharp.Extended.SKBlurHash">API Reference</a> — Full method documentation</li> |
| 212 | +</ul> |
| 213 | + |
| 214 | +</article> |
| 215 | + |
| 216 | + <div class="contribution d-print-none"> |
| 217 | + <a href="https://github.com/mono/SkiaSharp.Extended/blob/362/merge/docs/docs/blurhash.md/#L1" class="edit-link">Edit this page</a> |
| 218 | + </div> |
| 219 | + |
| 220 | + <div class="next-article d-print-none border-top" id="nextArticle"></div> |
| 221 | + |
| 222 | + </div> |
| 223 | + |
| 224 | + <div class="affix"> |
| 225 | + <nav id="affix"></nav> |
| 226 | + </div> |
| 227 | + </main> |
| 228 | + |
| 229 | + <div class="container-xxl search-results" id="search-results"></div> |
| 230 | + |
| 231 | + <footer class="border-top text-secondary"> |
| 232 | + <div class="container-xxl"> |
| 233 | + <div class="flex-fill"> |
| 234 | + <span>Made with <a href="https://dotnet.github.io/docfx">docfx</a></span> |
| 235 | + </div> |
| 236 | + </div> |
| 237 | + </footer> |
| 238 | + </body> |
| 239 | +</html> |
0 commit comments