Blurhash

https://github.com/woltapp/blurhash
Admin
Blurhash is an algorithm and library that encodes an image into a short ASCII string, which can then...
Tokens:30,689
Snippets:374
Trust Score:8.6
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install BlurHash package

Source: https://github.com/woltapp/blurhash/blob/master/TypeScript/README.md

Install the library via npm.

```sh
npm install --save blurhash
```

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

### Start development server

Source: https://github.com/woltapp/blurhash/blob/master/Website/Readme.md

Executes the local development environment for the website.

```bash
npm start
```

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

### C Library Integration Example

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/modules.md

Standard pattern for including headers and managing memory when using the C library.

```c
// Copy these files into your project
#include "encode.h"
#include "decode.h"

const char *hash = blurHashForPixels(4, 3, width, height, rgb, bytesPerRow);
uint8_t *pixels = decode(hash, 32, 32, 1, 4);
// ...
freePixelArray(pixels);
```

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

### 32x32 RGBA Image Example

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/types.md

Illustrates byte indexing for a 32x32 RGBA image, showing the first few pixels and a row transition.

```text
- Total bytes: 32 × 32 × 4 = 4096
- First pixel (0, 0): indices [0, 1, 2, 3] = R, G, B, A
- Pixel (1, 0): indices [4, 5, 6, 7] = R, G, B, A
- Pixel (0, 1): indices [128, 129, 130, 131] = R, G, B, A (offset = 1 × 32 × 4)
```

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

### Initialize NumberTriplet

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/types.md

Example of assigning values to the NumberTriplet type.

```typescript
const rgb: NumberTriplet = [0.5, 0.3, 0.7];
```

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

### C decodeToArray Usage Example

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/api-reference/c-decoder.md

Demonstrates how to allocate a buffer, call the decoder, and handle the resulting status code.

```c
#include <stdlib.h>

uint8_t *buffer = malloc(256 * 256 * 4); // Custom allocation
if (buffer == NULL) {
  perror("malloc failed");
  return;
}

int result = decodeToArray("LEHV6nWB2yk8pyo0adR*.7kCMdnj", 256, 256, 1, 4, buffer);
if (result == 0) {
  // buffer now contains decoded pixel data
  // Use it...
  free(buffer); // Free with your custom allocator
} else {
  fprintf(stderr, "Decode failed\n");
  free(buffer);
}
```

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

### Encoding an image to BlurHash

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/api-reference/c-encoder.md

A complete example demonstrating image data preparation, calling the encoder, and safely storing the resulting hash string.

```c
#include "encode.h"
#include <stdio.h>
#include <string.h>

// Assuming you have loaded an image with pixel data in 'rgb' array
// Image dimensions: 256x256, 3 bytes per pixel, no padding
int width = 256;
int height = 256;
uint8_t *rgb = load_image_rgb("photo.jpg"); // Your image loading code
size_t bytesPerRow = width * 3;

// Encode with 4x3 components
const char *hash = blurHashForPixels(4, 3, width, height, rgb, bytesPerRow);

// Copy the hash for later use (important!)
char persistent_hash[64];
strcpy(persistent_hash, hash);

printf("BlurHash: %s\n", persistent_hash);

// Free your pixel data (not the hash)
free(rgb);
```

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

### Configure decode and decodeToArray functions

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/configuration.md

Examples for decoding BlurHash strings into pixel buffers, covering RGB/RGBA output and manual buffer management.

```c
// Standard RGB output
uint8_t *rgb = decode("LEHV6nWB2yk8pyo0adR*.7kCMdnj", 256, 256, 1, 3);

// With alpha channel
uint8_t *rgba = decode("LEHV6nWB2yk8pyo0adR*.7kCMdnj", 256, 256, 1, 4);

// High contrast
uint8_t *hc = decode("LEHV6nWB2yk8pyo0adR*.7kCMdnj", 256, 256, 2, 4);

// Using decodeToArray with custom allocator
uint8_t *buffer = my_allocator(256 * 256 * 4);
int status = decodeToArray("LEHV6nWB2yk8pyo0adR*.7kCMdnj", 256, 256, 1, 4, buffer);
if (status == 0) {
  // Use buffer
  my_deallocator(buffer);
}
```

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

### Usage Example

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/api-reference/typescript-encode.md

Demonstrates extracting pixel data from an image via a canvas and generating a BlurHash string.

```typescript
import { encode } from 'blurhash';

// Load an image and encode it
const img = new Image();
img.src = 'image.jpg';

img.onload = () => {
  // Draw image to canvas to extract pixel data
  const canvas = document.createElement('canvas');
  canvas.width = img.width;
  canvas.height = img.height;
  const ctx = canvas.getContext('2d');
  ctx.drawImage(img, 0, 0);
  
  const imageData = ctx.getImageData(0, 0, img.width, img.height);
  
  // Encode with 4 components in each direction
  const hash = encode(imageData.data, imageData.width, imageData.height, 4, 4);
  console.log('BlurHash:', hash); // e.g., "LEHV6nWB2yk8pyo0adR*.7kCMdnj"
};
```

```typescript
// Example with different component counts
const fine = encode(pixels, 256, 256, 5, 5);    // 54 characters, more detail
const compact = encode(pixels, 256, 256, 3, 3); // 24 characters, more compact
```

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

### BlurHash String Structure Example

Source: https://github.com/woltapp/blurhash/blob/master/Algorithm.md

Visual representation of a BlurHash string and its component parts.

```text
Example: LlMF%n00%#MwS|WCWEM{R*bbWBbH
Legend:  12333344....................
```

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

### Configure BlurHashDecoder decoding options

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/configuration.md

Examples of standard decoding, high contrast adjustments, and memory-conscious configurations for list items.

```kotlin
// Standard: with caching (recommended)
val bitmap = BlurHashDecoder.decode(hash, 256, 256) // Defaults: punch=1f, useCache=true

// High contrast
val crisp = BlurHashDecoder.decode(hash, 256, 256, punch = 1.5f)

// Subtle effect, no caching
val soft = BlurHashDecoder.decode(hash, 256, 256, punch = 0.7f, useCache = false)

// For list with many items (disable cache to save memory)
fun decodeForListItem(hash: String?, position: Int) {
  val size = 96 // Common thumbnail size
  return BlurHashDecoder.decode(hash, size, size, useCache = false)
}

// Or periodically clear cache in long lists
override fun onBindViewHolder(holder: ViewHolder, position: Int) {
  val bitmap = BlurHashDecoder.decode(hash, 96, 96)
  holder.imageView.setImageBitmap(bitmap)
  
  if (position % 50 == 0) {
    BlurHashDecoder.clearCache() // Periodic cleanup
  }
}
```

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

### Configure blurHashForPixels encoding

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/configuration.md

Examples demonstrating various configurations for encoding pixel data into a BlurHash string, including handling of row padding and quality settings.

```c
// Tightly packed RGB data
const char *hash = blurHashForPixels(4, 3, 256, 256, rgbData, 256 * 3);

// RGB data with row padding/alignment
const char *hash = blurHashForPixels(4, 3, 256, 256, rgbData, 768); // 256*3 padded to alignment

// Compact encoding
const char *compact = blurHashForPixels(3, 3, 256, 256, rgbData, 768);

// High quality
const char *hq = blurHashForPixels(5, 5, 256, 256, rgbData, 768);
```

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

### Return Examples for isBlurhashValid

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/api-reference/typescript-validation.md

Illustrates the possible return values for valid and invalid blurhash inputs.

```typescript
{ result: true }
// Valid blurhash, no error reason provided

{ result: false, errorReason: "The blurhash string must be at least 6 characters" }
// Input string is too short

{ result: false, errorReason: "blurhash length mismatch: length is 10 but it should be 24" }
// Length doesn't match the component count encoding
```

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

### Configure encode() quality levels

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/configuration.md

Examples of generating hashes with different component counts to balance quality and output length.

```typescript
// Compact hash (for bandwidth-sensitive)
const compact = encode(pixels, 256, 256, 3, 3); // 24 chars

// Standard quality
const standard = encode(pixels, 256, 256, 4, 3); // 28 chars

// High quality
const hq = encode(pixels, 256, 256, 5, 5); // 54 chars
```

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

### Configure decode() parameters

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/configuration.md

Examples of calling the decode function with varying punch values to adjust contrast.

```typescript
// Standard configuration
const pixels = decode(hash, 32, 32); // Width=32, Height=32, Punch=1

// High contrast
const crisp = decode(hash, 32, 32, 1.5);

// Subtle effect
const soft = decode(hash, 32, 32, 0.7);

// Full detail mode (zero punch becomes 1)
const normal = decode(hash, 32, 32, 0); // Internally becomes 1
```

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

### Usage Example for isBlurhashValid

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/api-reference/typescript-validation.md

Demonstrates how to import the function, validate user input, and implement a guard pattern before decoding.

```typescript
import { isBlurhashValid } from 'blurhash';

// Validate before decoding
const validResult = isBlurhashValid('LEHV6nWB2yk8pyo0adR*.7kCMdnj');
console.log(validResult); // { result: true }

// Check an invalid blurhash
const invalidResult = isBlurhashValid('???');
console.log(invalidResult); 
// { result: false, errorReason: "The blurhash string must be at least 6 characters" }

// Use in a guard pattern
if (isBlurhashValid(userInput).result) {
  const pixels = decode(userInput, 32, 32);
  // process pixels
} else {
  console.error('Invalid blurhash');
}
```

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

### Implement Caching Strategies

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/configuration.md

Demonstrates fixed-size caching, adaptive caching for common sizes, and periodic cache cleanup in Kotlin.

```kotlin
// Strategy 1: Fixed size (lists with uniform thumbnails)
val bitmap = BlurHashDecoder.decode(hash, 96, 96) // Uses cache

// Strategy 2: Adaptive (many different sizes)
fun decodeAdaptive(hash: String, size: Int) {
  val useCache = (size in listOf(96, 128, 256)) // Only cache common sizes
  return BlurHashDecoder.decode(hash, size, size, useCache = useCache)
}

// Strategy 3: Periodic cleanup (long-lived app)
fun decodeWithCleanup(hash: String, position: Int) {
  val bitmap = BlurHashDecoder.decode(hash, 96, 96)
  if (position % 100 == 0) {
    BlurHashDecoder.clearCache()
  }
  return bitmap
}
```

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

### Deploy website

Source: https://github.com/woltapp/blurhash/blob/master/Website/Readme.md

Builds the site and pushes the output to the gh-pages branch.

```bash
npm deploy
```

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

### init(blurHash:size:punch:)

Source: https://github.com/woltapp/blurhash/blob/master/Swift/Readme.md

Initializes a UIImage from a BlurHash string.

```APIDOC
## init(blurHash: String, size: CGSize, punch: Float = 1)

### Description
Creates a UIImage containing the placeholder image decoded from the BlurHash string.

### Parameters
- **blurHash** (String) - Required - A string containing the BlurHash.
- **size** (CGSize) - Required - The requested output size.
- **punch** (Float) - Optional - Adjusts the contrast of the output image.
```

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

### Handle BlurHash C string

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/types.md

Demonstrates capturing a BlurHash string and copying it for persistence.

```c
const char *hash = blurHashForPixels(4, 3, width, height, rgb, bytesPerRow);
// String is valid until next blurHashForPixels() call
char persistent[64];
strcpy(persistent, hash); // Make a copy if needed
```

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

### Swift Module Structure

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/modules.md

Summary of available UIImage extension methods.

```text
UIImage extension methods:
├── init(blurHash:size:punch:)  [Decoder]
└── blurHash(numberOfComponents:)  [Encoder]
```

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

### Build and run BlurHash command-line tools

Source: https://github.com/woltapp/blurhash/blob/master/C/Readme.md

Commands to compile and execute the encoder and decoder utilities. Note that the command-line tools use stb_image and are not recommended for production use with untrusted data.

```bash
$ make blurhash_encoder
$ ./blurhash_encoder 4 3 ../Swift/BlurHashTest/pic1.png
LaJHjmVu8_~po#smR+a~xaoLWCRj
```

```bash
$ make blurhash_decoder
$ ./blurhash_decoder "LaJHjmVu8_~po#smR+a~xaoLWCRj" 32 32 decoded_output.png
```

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

### Generate and Load BlurHash (Android/Kotlin)

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/usage-patterns.md

Demonstrates backend hash generation and client-side placeholder decoding using the BlurHashDecoder utility.

```kotlin
// Backend: Generate hash
val blurhash = encode(pixelData, width, height, 4, 3)
val imageMetadata = ImageMetadata(url = imageUrl, blurhash = blurhash)
database.save(imageMetadata)

// Frontend: Load with placeholder
data class ImageData(val url: String, val blurhash: String?)

fun loadImageWithPlaceholder(data: ImageData, imageView: ImageView) {
  // Show placeholder immediately
  if (data.blurhash != null) {
    val bitmap = BlurHashDecoder.decode(data.blurhash, 128, 128)
    imageView.setImageBitmap(bitmap)
  }
  
  // Load actual image asynchronously
  loadImageAsync(data.url) { bitmap ->
    imageView.setImageBitmap(bitmap)
  }
}
```

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

### Import Patterns for BlurHash

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/modules.md

Demonstrates various ways to import the library, including named imports for full access or default imports for specific functionality.

```typescript
import { decode, encode, isBlurhashValid, ValidationError } from 'blurhash';

const pixels = decode(hash, 32, 32);
const hash = encode(pixels, 32, 32, 4, 3);
const valid = isBlurhashValid(hash);
```

```typescript
import encode from 'blurhash';

const hash = encode(pixels, 32, 32, 4, 3);
```

```typescript
import decode from 'blurhash';

const pixels = decode(hash, 32, 32);
```

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

### Project File Structure

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/MANIFEST.md

Visual representation of the documentation directory structure within the project.

```text
output/
├── INDEX.md (entry point: file index)
├── README.md (entry point: overview)
├── types.md
├── errors.md
├── configuration.md
├── modules.md
├── algorithm-internals.md
├── usage-patterns.md
├── api-reference/
│   ├── typescript-decode.md
│   ├── typescript-encode.md
│   ├── typescript-validation.md
│   ├── kotlin-decoder.md
│   ├── c-encoder.md
│   └── c-decoder.md
└── MANIFEST.md (this file)
```

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

### Test BlurHash in Kotlin

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/usage-patterns.md

Demonstrates decoding and cache management patterns for Android integration.

```kotlin
import org.junit.Test
import com.wolt.blurhashkt.BlurHashDecoder

class BlurHashDecoderTest {
  
  @Test
  fun testDecodeValid() {
    val bitmap = BlurHashDecoder.decode("LEHV6nWB2yk8pyo0adR*.7kCMdnj", 256, 256)
    assertNotNull(bitmap)
    assertEquals(256, bitmap?.width)
    assertEquals(256, bitmap?.height)
  }
  
  @Test
  fun testDecodeInvalid() {
    val result = BlurHashDecoder.decode(null, 256, 256)
    assertNull(result)
    
    val result2 = BlurHashDecoder.decode("", 256, 256)
    assertNull(result2)
  }
  
  @Test
  fun testCacheClearing() {
    BlurHashDecoder.decode("LEHV6nWB2yk8pyo0adR*.7kCMdnj", 256, 256, useCache = true)
    BlurHashDecoder.clearCache()
    // Cache is cleared; subsequent calls will recalculate
  }
}
```

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

### C Module Structure

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/modules.md

Available headers and functions for the C implementation.

```text
encode.h
├── blurHashForPixels()

decode.h
├── decode()
├── decodeToArray()
├── isValidBlurhash()
└── freePixelArray()
```

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

### Manage BlurHashDecoder cache performance

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/configuration.md

Demonstrates how caching affects decoding speed and how to manually clear the cache to manage memory.

```kotlin
// First decode: calculates and caches cosines
val bitmap1 = BlurHashDecoder.decode(hash, 256, 256, useCache = true) // ~50ms

// Second decode same size: reuses cache
val bitmap2 = BlurHashDecoder.decode(hash2, 256, 256, useCache = true) // ~30ms (40% faster)

// First decode different size: creates new cache entry
val bitmap3 = BlurHashDecoder.decode(hash3, 512, 512, useCache = true) // ~100ms

// Clear cache when memory is needed
BlurHashDecoder.clearCache()
```

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

### Responsive Placeholder Implementation

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/usage-patterns.md

Manages a placeholder that scales with the container and replaces itself once the actual image loads.

```typescript
import { decode } from 'blurhash';

class ResponsivePlaceholder {
  private hash: string;
  private container: HTMLElement;
  private image: HTMLImageElement;
  
  constructor(hash: string, imageUrl: string, container: HTMLElement) {
    this.hash = hash;
    this.container = container;
    this.image = document.createElement('img');
    this.image.src = imageUrl;
    
    // Create initial placeholder
    this.updatePlaceholder();
    
    // Replace on image load
    this.image.onload = () => this.showImage();
    this.container.appendChild(this.image);
  }
  
  private updatePlaceholder() {
    const dpr = window.devicePixelRatio || 1;
    const width = Math.round(this.container.clientWidth * dpr);
    const height = Math.round(this.container.clientHeight * dpr);
    
    const pixels = decode(this.hash, width, height);
    
    const canvas = document.createElement('canvas');
    canvas.width = width;
    canvas.height = height;
    canvas.style.width = this.container.clientWidth + 'px';
    canvas.style.height = this.container.clientHeight + 'px';
    
    const ctx = canvas.getContext('2d');
    const imageData = ctx.createImageData(width, height);
    imageData.data.set(pixels);
    ctx.putImageData(imageData, 0, 0);
    
    this.container.appendChild(canvas);
  }
  
  private showImage() {
    this.image.style.opacity = '1';
  }
}
```

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

### Manage pixel array lifecycle

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/api-reference/c-decoder.md

Shows the standard pattern for decoding and subsequently freeing the pixel array.

```c
uint8_t *pixels = decode(hash, width, height, 1, 4);
if (pixels != NULL) {
  // Use pixels...
  freePixelArray(pixels); // Must be called when done
}
```

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

### Import Blurhash Functions

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/INDEX.md

Essential imports for utilizing Blurhash functionality in TypeScript, Kotlin, and C projects.

```typescript
import { decode, encode, isBlurhashValid, ValidationError } from 'blurhash';
```

```kotlin
import com.wolt.blurhashkt.BlurHashDecoder
```

```c
#include "encode.h"
#include "decode.h"
```

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

### Project Directory Structure

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/README.md

Visual representation of the project's file organization.

```text
output/
├── README.md (this file)
├── api-reference/
│   ├── typescript-decode.md
│   ├── typescript-encode.md
│   ├── typescript-validation.md
│   ├── kotlin-decoder.md
│   ├── c-encoder.md
│   └── c-decoder.md
├── types.md
├── errors.md
├── configuration.md
├── modules.md
└── algorithm-internals.md
```

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

### Glide Integration for BlurHash

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/usage-patterns.md

Shows how to display a decoded BlurHash as a placeholder while loading the final image via Glide.

```kotlin
import android.graphics.Bitmap
import com.bumptech.glide.Glide
import com.bumptech.glide.load.Transformation
import com.bumptech.glide.request.RequestOptions
import com.wolt.blurhashkt.BlurHashDecoder

fun loadImageWithBlurHash(
  imageView: android.widget.ImageView,
  url: String,
  blurhash: String?,
  placeholderSize: Int = 128
) {
  // Load placeholder
  if (blurhash != null) {
    val placeholder = BlurHashDecoder.decode(blurhash, placeholderSize, placeholderSize)
    if (placeholder != null) {
      imageView.setImageBitmap(placeholder)
    }
  }
  
  // Load actual image over placeholder
  Glide.with(imageView.context)
    .load(url)
    .into(imageView)
}

// Usage
loadImageWithBlurHash(imageView, "https://example.com/image.jpg", "LEHV6nWB2yk8pyo0adR*.7kCMdnj")
```

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

### Select Placeholder Sizes

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/configuration.md

Adjusts decoding dimensions based on device pixel ratio for web or fixed thumbnail sizes for mobile.

```typescript
// Web: Match device pixel ratio
const dpr = window.devicePixelRatio || 1;
const placeholderSize = Math.round(32 * dpr);
const pixels = decode(hash, placeholderSize, placeholderSize);

// Mobile: Thumbnail sizes
// Kotlin
val thumbSize = 96 // DP, converted to pixels
val bitmap = BlurHashDecoder.decode(hash, thumbSize, thumbSize)
```

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

### C Decoder Required Includes

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/modules.md

Standard headers required for using the C decoder.

```c
#include "decode.h"
#include <stdint.h>
#include <stdlib.h>
#include <stdbool.h>
#include <string.h>
#include <math.h>
```

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

### Kotlin Module Structure

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/modules.md

Available exports for the Kotlin library.

```text
com.wolt.blurhashkt
└── BlurHashDecoder (object)
    ├── decode()
    └── clearCache()
```

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

### Basic BlurHash ImageView Extension

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/usage-patterns.md

Extends ImageView to decode and set a BlurHash string directly. Requires a valid BlurHash string and optional dimensions.

```kotlin
import android.widget.ImageView
import com.wolt.blurhashkt.BlurHashDecoder

fun ImageView.setBlurHash(hash: String?, width: Int = 256, height: Int = 256) {
  val bitmap = BlurHashDecoder.decode(hash, width, height)
  if (bitmap != null) {
    setImageBitmap(bitmap)
  }
}

// Usage
imageView.setBlurHash("LEHV6nWB2yk8pyo0adR*.7kCMdnj")
```

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

### Validate and decode a Blurhash

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/api-reference/c-decoder.md

Demonstrates using isValidBlurhash to safely guard the decoding process.

```c
if (isValidBlurhash("LEHV6nWB2yk8pyo0adR*.7kCMdnj")) {
  uint8_t *pixels = decode("LEHV6nWB2yk8pyo0adR*.7kCMdnj", 32, 32, 1, 4);
  // process pixels...
} else {
  fprintf(stderr, "Invalid blurhash\n");
}
```

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

### C API

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/README.md

Public methods for encoding and decoding BlurHash strings in C.

```APIDOC
## C API

### blurHashForPixels(componentX, componentY, width, height, rgbPixels, bytesPerRow)
- **Description**: Encodes pixel data into a BlurHash string.

### decode(blurhash, width, height, punch, nChannels)
- **Description**: Decodes a BlurHash string into a pixel array.

### isValidBlurhash(blurhash)
- **Description**: Validates the format of a BlurHash string.

### freePixelArray(pixels)
- **Description**: Frees memory allocated for a pixel array.
```

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

### Pack AC Components

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/algorithm-internals.md

Combines three quantized values into a single integer representation for efficient storage.

```text
packedValue = quantR * 19² + quantG * 19 + quantB
// Range: 0 to 6859 (less than 83² = 6889)
```

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

### Implement decode() patterns

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/configuration.md

Common patterns for handling device pixel ratios and wrapping decode options in a custom interface.

```typescript
// Pattern: Adjust size based on device pixel ratio
const dpr = window.devicePixelRatio;
const pixels = decode(hash, 32 * dpr, 32 * dpr);

// Pattern: User-adjustable contrast
interface DecodeOptions {
  size: number;
  punch: number;
}
function decodeWithOptions(hash: string, opts: DecodeOptions) {
  return decode(hash, opts.size, opts.size, opts.punch);
}
```

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

### BlurHash Placeholder Manager

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/usage-patterns.md

Encapsulates decoding logic and cache management within a helper class. Useful for centralizing placeholder generation.

```kotlin
import android.content.Context
import android.graphics.Bitmap
import com.wolt.blurhashkt.BlurHashDecoder

class BlurHashPlaceholderManager(private val context: Context) {
  
  fun getPlaceholder(hash: String?, width: Int, height: Int): Bitmap? {
    return BlurHashDecoder.decode(hash, width, height)
  }
  
  fun getPlaceholder(hash: String?, size: Int): Bitmap? {
    return getPlaceholder(hash, size, size)
  }
  
  fun clearCache() {
    BlurHashDecoder.clearCache()
  }
}

// Usage
val manager = BlurHashPlaceholderManager(context)
val bitmap = manager.getPlaceholder("LEHV6nWB2yk8pyo0adR*.7kCMdnj", 256)
imageView.setImageBitmap(bitmap)
```

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

### C Encoder Required Includes

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/modules.md

Standard headers required for using the C encoder.

```c
#include "encode.h"
#include <stdint.h>
#include <stdlib.h>
```

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

### Display Placeholder and Load Image (Frontend)

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/usage-patterns.md

Decodes a BlurHash string into a canvas element for immediate display, then replaces it once the full image finishes loading.

```typescript
import { decode } from 'blurhash';

interface ImageData {
  url: string;
  blurhash: string;
}

async function loadImage(data: ImageData, container: HTMLElement) {
  // Immediately show placeholder
  const placeholder = decode(data.blurhash, 32, 32);
  const canvas = createCanvasFromPixels(placeholder, 32, 32);
  container.appendChild(canvas);
  
  // Load actual image
  const img = new Image();
  img.onload = () => {
    container.replaceChild(img, canvas);
  };
  img.src = data.url;
}
```

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

### BlurHash in RecyclerView

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/usage-patterns.md

Demonstrates efficient placeholder rendering and cache management within a RecyclerView adapter.

```kotlin
import android.view.LayoutInflater
import android.view.ViewGroup
import android.widget.ImageView
import androidx.recyclerview.widget.RecyclerView
import com.wolt.blurhashkt.BlurHashDecoder

class ImageAdapter(private val items: List<ImageItem>) : RecyclerView.Adapter<ImageAdapter.ViewHolder>() {
  
  data class ImageItem(val url: String, val blurhash: String?)
  
  inner class ViewHolder(val imageView: ImageView) : RecyclerView.ViewHolder(imageView) {
    fun bind(item: ImageItem) {
      // Set placeholder first
      if (item.blurhash != null) {
        val placeholder = BlurHashDecoder.decode(item.blurhash, 128, 128)
        if (placeholder != null) {
          imageView.setImageBitmap(placeholder)
        }
      }
      
      // Load actual image
      loadImage(item.url) { bitmap ->
        imageView.setImageBitmap(bitmap)
      }
    }
  }
  
  override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): ViewHolder {
    val imageView = ImageView(parent.context)
    return ViewHolder(imageView)
  }
  
  override fun onBindViewHolder(holder: ViewHolder, position: Int) {
    holder.bind(items[position])
    
    // Periodic cache cleanup for long lists
    if (position % 50 == 0) {
      BlurHashDecoder.clearCache()
    }
  }
  
  override fun getItemCount() = items.size
}
```

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

### Calculate AC Components

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/algorithm-internals.md

Computes detail components using DCT basis functions and quantizes them.

```text
// Basis function with normalization = 2.0
basis(x, y) = 2.0 * cos(π*i*x/width) * cos(π*j*y/height)

// Multiply with all pixels
acRed = sum(pixel_r * basis) / (width * height)
acGreen = sum(pixel_g * basis) / (width * height)
acBlue = sum(pixel_b * basis) / (width * height)

// Normalize by maximum value
acRed_norm = acRed / maximumValue
acGreen_norm = acGreen / maximumValue
acBlue_norm = acBlue / maximumValue

// Apply sign-preserving power and quantize to 0–18
quantR = floor(max(0, min(18, floor(signPow(acRed_norm, 0.5) * 9 + 9.5))))
quantG = floor(max(0, min(18, floor(signPow(acGreen_norm, 0.5) * 9 + 9.5))))
quantB = floor(max(0, min(18, floor(signPow(acBlue_norm, 0.5) * 9 + 9.5))))

// Pack into single value
acValue = quantR * 19*19 + quantG * 19 + quantB

// Encode as 2 base-83 digits
acChars = encode83(acValue, 2)
```

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

### Kotlin: BlurHashDecoder

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/modules.md

Public object methods for BlurHash operations in Kotlin.

```APIDOC
## Kotlin: com.wolt.blurhashkt

### BlurHashDecoder
- `decode()`: Decodes a BlurHash string.
- `clearCache()`: Clears internal decoder cache.
```

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

### TypeScript/JavaScript Module Structure

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/modules.md

Available exports for the npm package.

```text
blurhash (npm package)
├── decode()
├── encode()
├── isBlurhashValid()
└── ValidationError
```

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

### Implement custom memory allocation for decoding

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/usage-patterns.md

Allows integration with custom memory management systems by providing a function pointer structure for allocation and deallocation.

```c
#include "decode.h"
#include <stdio.h>
#include <stdlib.h>

// Custom allocator (example)
typedef struct {
  void *(*malloc)(size_t);
  void (*free)(void *);
} Allocator;

int decode_with_allocator(const char *hash, int width, int height, Allocator *alloc) {
  // Validate
  if (!isValidBlurhash(hash)) {
    return -1;
  }
  
  // Allocate with custom allocator
  size_t size = width * height * 4;
  uint8_t *buffer = (uint8_t *)alloc->malloc(size);
  
  if (buffer == NULL) {
    fprintf(stderr, "Custom allocation failed\n");
    return -1;
  }
  
  // Decode into buffer
  int status = decodeToArray(hash, width, height, 1, 4, buffer);
  
  if (status != 0) {
    fprintf(stderr, "Decode failed\n");
    alloc->free(buffer);
    return -1;
  }
  
  // Use buffer...
  
  alloc->free(buffer);
  return 0;
}
```

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

### TypeScript/JavaScript: blurhash package

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/modules.md

Public functions available in the blurhash npm package.

```APIDOC
## TypeScript/JavaScript API

- `decode()`: Decodes a BlurHash string.
- `encode()`: Encodes pixel data into a BlurHash string.
- `isBlurhashValid()`: Validates a BlurHash string format.
```

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

### blurHashForPixels()

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/api-reference/c-encoder.md

Encodes an RGB image into a BlurHash string. The function returns a pointer to a static buffer containing the null-terminated hash string.

```APIDOC
## blurHashForPixels(int xComponents, int yComponents, int width, int height, uint8_t *rgb, size_t bytesPerRow)

### Description
Generates a BlurHash string from raw RGB pixel data. The function returns a pointer to a static string that is overwritten on subsequent calls.

### Parameters
- **xComponents** (int) - Required - Number of horizontal blur hash components (1-9).
- **yComponents** (int) - Required - Number of vertical blur hash components (1-9).
- **width** (int) - Required - Width of the input image in pixels.
- **height** (int) - Required - Height of the input image in pixels.
- **rgb** (uint8_t *) - Required - Pointer to RGB pixel data (3 bytes per pixel).
- **bytesPerRow** (size_t) - Required - Number of bytes per row of pixel data.

### Return Value
- **Type**: const char *
- **Description**: A null-terminated C string containing the BlurHash. The memory is managed by the function and should not be freed by the caller.
```

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

### Swift Decoder Extension

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/modules.md

Standalone extension for UIImage to decode BlurHash strings.

```swift
// BlurHashDecode.swift
import UIKit

extension UIImage {
  public convenience init?(blurHash: String, size: CGSize, punch: Float = 1)
}
```

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

### Kotlin API

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/README.md

Public methods for decoding BlurHash strings on Android using Kotlin.

```APIDOC
## Kotlin API

### BlurHashDecoder.decode(blurhash, width, height)
- **Description**: Decodes a BlurHash string into an Android Bitmap.
- **Parameters**:
  - blurhash (string) - The BlurHash string.
  - width (int) - Target width.
  - height (int) - Target height.

### BlurHashDecoder.clearCache()
- **Description**: Clears the internal cosine calculation cache.
```

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

### Apply Punch Parameter

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/algorithm-internals.md

Adjusts AC component contrast using the punch factor.

```text
acComponent *= punch
```

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

### Handle BlurHash String Length Errors

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/errors.md

Demonstrates how to handle errors when a provided BlurHash string is too short, either by catching the exception or using the safe validation function.

```typescript
import { decode, isBlurhashValid } from 'blurhash';

// Method 1: Direct call (throws)
try {
  decode('abc', 32, 32);
} catch (error) {
  console.error(error.message); // "The blurhash string must be at least 6 characters"
}

// Method 2: Validation first (safe)
const validation = isBlurhashValid('abc');
if (!validation.result) {
  console.error(validation.errorReason); // Same message
}
```

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

### decode(blurhash, width, height, punch, nChannels)

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/errors.md

C function to decode a BlurHash string into a pixel array.

```APIDOC
## decode(blurhash, width, height, punch, nChannels)

### Description
Decodes a BlurHash string into a pixel array.

### Returns
- **uint8_t* / NULL** - Returns a pointer to the pixel array on success, or NULL if the input is invalid, memory allocation fails, or component count decoding fails.
```

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

### Copying the BlurHash result

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/api-reference/c-encoder.md

The returned pointer is managed internally and overwritten on subsequent calls. Copy the result to a local buffer if persistence is required.

```c
const char *result = blurHashForPixels(4, 3, width, height, pixels, bytesPerRow);
char hash[MAX_HASH_LENGTH];
strcpy(hash, result); // Now you have a persistent copy
```

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

### Expose C functions for FFI

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/usage-patterns.md

Provides a clean interface for foreign function interfaces, such as Python's ctypes, by wrapping core library functions.

```c
// C implementation for FFI exposure
#include "encode.h"
#include "decode.h"

// Export function for Python ctypes
const char *encode_image(int xComp, int yComp, int width, int height, uint8_t *rgb, size_t row) {
  return blurHashForPixels(xComp, yComp, width, height, rgb, row);
}

// Export function for Python ctypes
uint8_t *decode_image(const char *hash, int width, int height, int punch, int channels) {
  return decode(hash, width, height, punch, channels);
}

// Export function for Python ctypes
int validate_hash(const char *hash) {
  return isValidBlurhash(hash) ? 1 : 0;
}

// Export function for Python ctypes
void free_image(uint8_t *pixels) {
  freePixelArray(pixels);
}
```

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

### Decode BlurHash to UIImage

Source: https://github.com/woltapp/blurhash/blob/master/Swift/Readme.md

Initializes a UIImage from a BlurHash string. Keep the requested size small, such as 32 pixels wide, for optimal performance.

```swift
public convenience init?(blurHash: String, size: CGSize, punch: Float = 1)
```

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

### encode(pixels: Uint8ClampedArray, width: number, height: number, componentX: number, componentY: number) => string

Source: https://github.com/woltapp/blurhash/blob/master/TypeScript/README.md

Encodes pixel data into a blurhash string.

```APIDOC
## encode(pixels, width, height, componentX, componentY)

### Description
Encodes pixels to a blurhash string.

### Parameters
- **pixels** (Uint8ClampedArray) - Required - The pixel data to encode.
- **width** (number) - Required - The width of the image.
- **height** (number) - Required - The height of the image.
- **componentX** (number) - Required - The number of components in the X direction.
- **componentY** (number) - Required - The number of components in the Y direction.

### Returns
- **string** - The resulting blurhash string.
```

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

### Parse BlurHash Size Information

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/algorithm-internals.md

Extracts the component counts (numX and numY) from the first character of the hash string.

```pseudocode
sizeFlag = decode83(hash[0])
numY = floor(sizeFlag / 9) + 1
numX = (sizeFlag % 9) + 1
```

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

### Handle BlurHash decoding errors in C

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/README.md

Validate the input string before decoding and check for NULL pointers after decoding. Ensure allocated pixel arrays are freed after use.

```c
if (!isValidBlurhash(userInput)) {
  fprintf(stderr, "Invalid blurhash\n");
  return;
}

uint8_t *pixels = decode(userInput, 256, 256, 1, 4);
if (pixels == NULL) {
  fprintf(stderr, "Decode failed\n");
  return;
}

// Use pixels
freePixelArray(pixels);
```

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

### blurHash(numberOfComponents:)

Source: https://github.com/woltapp/blurhash/blob/master/Swift/Readme.md

Encodes a UIImage into a BlurHash string.

```APIDOC
## blurHash(numberOfComponents: (Int, Int)) -> String?

### Description
Returns a string containing the BlurHash for the image, or nil if the image format is not supported.

### Parameters
- **numberOfComponents** ((Int, Int)) - Required - A tuple of integers specifying the number of components in the X and Y directions (must be between 1 and 9 inclusive).
```

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

### TypeScript Package Exports

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/modules.md

Configuration for package.json exports to support various environments.

```json
{
  "exports": {
    ".": {
      "browser": {
        "import": "./dist/esm/index.js",
        "require": "./dist/index.js"
      },
      "import": "./dist/index.mjs",
      "node": "./dist/index.js",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  }
}
```

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

### Create and manage Uint8ClampedArray

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/types.md

Methods for obtaining or creating pixel data arrays.

```typescript
// From decode() output
const pixels = decode(hash, 32, 32);

// Manual creation
const manual = new Uint8ClampedArray(32 * 32 * 4);

// From Canvas
const canvas = document.createElement('canvas');
const ctx = canvas.getContext('2d');
const imageData = ctx.getImageData(0, 0, 32, 32);
const pixels = imageData.data; // Already Uint8ClampedArray
```

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

### Optimize encode() components by aspect ratio

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/configuration.md

A helper function to dynamically select DCT component counts based on the source image aspect ratio.

```typescript
function encodeOptimal(pixels: Uint8ClampedArray, width: number, height: number) {
  const aspectRatio = width / height;
  
  let componentX = 4;
  let componentY = 3;
  
  if (aspectRatio > 1.5) {
    // Wide image: more X components
    componentX = 5;
    componentY = 3;
  } else if (aspectRatio < 0.67) {
    // Tall image: more Y components
    componentX = 3;
    componentY = 5;
  }
  
  return encode(pixels, width, height, componentX, componentY);
}
```

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

### Generate BlurHash on Backend (TypeScript)

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/usage-patterns.md

Encodes image pixel data into a BlurHash string. Requires an image processing library like sharp to extract raw pixel data.

```typescript
import { encode } from 'blurhash';
import fs from 'fs';

interface ImageMetadata {
  url: string;
  blurhash: string;
}

async function generateImageMetadata(imagePath: string): Promise<ImageMetadata> {
  // Read image file
  const imageBuffer = fs.readFileSync(imagePath);
  
  // Decode image to pixels (using sharp or similar)
  const image = await sharp(imagePath).raw().toBuffer({ resolveWithObject: true });
  const pixels = new Uint8ClampedArray(image.data);
  
  // Generate blurhash
  const blurhash = encode(pixels, image.info.width, image.info.height, 4, 3);
  
  return {
    url: `/images/${imagePath}`,
    blurhash: blurhash
  };
}
```

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

### C Decoder Exported Functions

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/modules.md

Functions for decoding BlurHash strings and managing memory for pixel arrays.

```c
uint8_t *decode(
  const char *blurhash,
  int width, int height,
  int punch, int nChannels
);

int decodeToArray(
  const char *blurhash,
  int width, int height,
  int punch, int nChannels,
  uint8_t *pixelArray
);

bool isValidBlurhash(const char *blurhash);

void freePixelArray(uint8_t *pixelArray);
```

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

### Kotlin BlurHashDecoder Usage

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/modules.md

Demonstrates decoding a hash into a bitmap and clearing the internal cache.

```kotlin
import com.wolt.blurhashkt.BlurHashDecoder

// Usage
val bitmap = BlurHashDecoder.decode(hash, width, height)
BlurHashDecoder.clearCache()
```

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

### Implement defensive Blurhash decoding in C

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/usage-patterns.md

Uses a custom struct to return error codes alongside results, ensuring memory safety and explicit error reporting.

```c
#include "decode.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

typedef struct {
  uint8_t *pixels;
  int width;
  int height;
  int error_code;
} DecodeResult;

DecodeResult decode_image_safe(const char *hash, int width, int height) {
  DecodeResult result = {NULL, width, height, 0};
  
  // Null check
  if (hash == NULL) {
    result.error_code = -1;
    return result;
  }
  
  // Length check
  if (strlen(hash) < 6) {
    result.error_code = -2;
    return result;
  }
  
  // Format validation
  if (!isValidBlurhash(hash)) {
    result.error_code = -3;
    return result;
  }
  
  // Decode
  result.pixels = decode(hash, width, height, 1, 4);
  if (result.pixels == NULL) {
    result.error_code = -4;
  }
  
  return result;
}

int main() {
  DecodeResult result = decode_image_safe("LEHV6nWB2yk8pyo0adR*.7kCMdnj", 256, 256);
  
  if (result.error_code == 0 && result.pixels != NULL) {
    // Success
    use_pixels(result.pixels);
    freePixelArray(result.pixels);
  } else {
    fprintf(stderr, "Decode error code: %d\n", result.error_code);
  }
  
  return 0;
}
```

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

### Select Component Counts

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/configuration.md

Determines the number of components to use during decoding based on the image aspect ratio.

```typescript
// Based on image aspect ratio
function selectComponents(width: number, height: number) {
  const aspectRatio = width / height;
  
  if (aspectRatio > 2.0) return [5, 3]; // Very wide
  if (aspectRatio > 1.5) return [4, 3]; // Wide
  if (aspectRatio > 0.67) return [4, 4]; // Roughly square
  if (aspectRatio > 0.5) return [3, 4]; // Tall
  return [3, 5]; // Very tall
}
```

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

### Handle C API Errors and Validation

Source: https://github.com/woltapp/blurhash/blob/master/_autodocs/api-reference/c-decoder.md

Common patterns for error handling, including NULL pointer checks, return code validation, and pre-decoding hash validation.

```c
// Pattern 1: Check for NULL
uint8_t *pixels = decode(hash, 32, 32, 1, 4);
if (pixels == NULL) {
  perror("decode failed");
} else {
  // use pixels
  freePixelArray(pixels);
}

// Pattern 2: Check return code with decodeToArray
int status = decodeToArray(hash, 32, 32, 1, 4, buffer);
if (status != 0) {
  fprintf(stderr, "decode failed\n");
}

// Pattern 3: Validate before decoding
if (!isValidBlurhash(hash)) {
  fprintf(stderr, "invalid blurhash\n");
} else {
  uint8_t *pixels = decode(hash, 32, 32, 1, 4);
  // ...
}
```
Tokens:
Raw