4.0 KiB

Raw Blame History

go-blurhash

go-blurhash is a pure Go implementation of the BlurHash algorithm, which is used by Mastodon an other Fediverse software to implement a swift way of preloading placeholder images as well as hiding sensitive media. Read more about it here.

tl;dr: BlurHash is a compact representation of a placeholder for an image.

This library allows generating the BlurHash of a given image, as well as reconstructing a blurred version with specified dimensions from a given BlurHash.

This library is based on the following reference implementations:

Encoder: https://github.com/woltapp/blurhash/blob/master/C (C)
Deocder: https://github.com/woltapp/blurhash/blob/master/TypeScript (TypeScript)

BlurHash is written by Dag Ågren / Wolt.

	Before	After
Image		"LFE.@D9F01_2%L%MIVD*9Goe-;WB"
Hash	"LFE.@D9F01_2%L%MIVD*9Goe-;WB"

Installation

From source

go get -u github.com/buckket/go-blurhash

Usage

go-blurhash exports three functions:

func blurhash.Encode(xComponents, yComponents int, rgba image.Image) (string, error)
func blurhash.Decode(hash string, width, height, punch int) (image.Image, error)
func blurhash.Components(hash string) (xComponents, yComponents int, err error)

Here’s a simple demonstration. Check pkg.go.dev for the full documentation.

package main

import (
	"fmt"
	"github.com/buckket/go-blurhash"
	"image/png"
	"os"
)

func main() {
	// Generate the BlurHash for a given image
	imageFile, _ := os.Open("test.png")
	loadedImage, err := png.Decode(imageFile)
	str, _ := blurhash.Encode(4, 3, loadedImage)
	if err != nil {
		// Handle errors
	}
	fmt.Printf("Hash: %s\n", str)

	// Generate an image for a given BlurHash
	// Width will be 300px and Height will be 500px
	// Punch specifies the contrasts and defaults to 1
	img, err := blurhash.Decode(str, 300, 500, 1)
	if err != nil {
		// Handle errors
	}
	f, _ := os.Create("test_blur.png")
	_ = png.Encode(f, img)
	
	// Get the x and y components used for encoding a given BlurHash
	x, y, err := blurhash.Components("LFE.@D9F01_2%L%MIVD*9Goe-;WB")
	if err != nil {
		// Handle errors
	}
	fmt.Printf("xComponents: %d, yComponents: %d", x, y)
}

Limitations

Presumably a bit slower than the C implementation (TODO: Benchmarks)

Notes

As mentioned here, it’s best to generate very small images (~32x32px) via BlurHash and scale them up to the desired dimensions afterwards for optimal performance.
Since #2 we diverted from the reference implementation by memorizing sRGBtoLinear values, thus increasing encoding speed at the cost of higher memory usage.
Starting with v1.1.0 the signature of blurhash.Encode() has changed slightly (see #3).

License

GNU GPLv3+

4.0 KiB Raw Blame History Unescape Escape