A Blurhash implementation in pure Go (Decode/Encode)

Last update: Dec 27, 2022

Overview

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+

You might also like...

A Go library for an efficient implementation of a skip list: https://godoc.org/github.com/MauriceGit/skiplist

Fast Skiplist Implementation This Go-library implements a very fast and efficient Skiplist that can be used as direct substitute for a balanced tree o

240 Dec 30, 2022

A slice-based implementation of a stack. In Go!

Stackgo Stackgo is a slice-based implementation of a simple stack in Go. It uses a pre-alloc pagination strategy which adds little memory overhead to

16 Nov 3, 2022

A Left-Leaning Red-Black (LLRB) implementation of balanced binary search trees for Google Go

GoLLRB GoLLRB is a Left-Leaning Red-Black (LLRB) implementation of 2-3 balanced binary search trees in Go Language. Overview As of this writing and to

747 Dec 23, 2022

Golang implementation of Radix trees

go-radix Provides the radix package that implements a radix tree. The package only provides a single Tree implementation, optimized for sparse nodes.

768 Dec 30, 2022

gtreap is an immutable treap implementation in the Go Language

gtreap gtreap is an immutable treap implementation in the Go Language Overview gtreap implements an immutable treap data structure in golang. By treap

85 Dec 11, 2022

An yet-another red-black tree implementation, with a C++ STL-like API.

A red-black tree with an API similar to C++ STL's. INSTALLATION go get github.com/yasushi-saito/rbtree EXAMPLE More examples can be fou

18 Apr 25, 2022

A simple Bloom Filter implementation in Go

This is a simple Bloom filter implementation written in Go. For the theory behind Bloom filters, read http://en.wikipedia.org/wiki/Bloom_filter This

16 Apr 26, 2018

HyperLogLog and HyperLogLog++ implementation in Go/Golang.

HyperLogLog and HyperLogLog++ Implements the HyperLogLog and HyperLogLog++ algorithms. HyperLogLog paper: http://algo.inria.fr/flajolet/Publications/F

424 Nov 24, 2022

A go implementation of Verkle trees

go-verkle A very experimental implementation of Verkle trees. When production-ready, the code is to be split between go-kzg and go-ethereum. Notes Nod

106 Jan 8, 2023

Comments

Pointer to image.Image interface
This library has the Encode API take in a pointer to image.Image (*image.Image) instead of either the interface itself (which has an underlying value of a pointer) or a concrete struct such as *image.NRGBA. This is usually a bad idea.

The lines that use this "pointer to interface" seem to only dereference the interface and not change it:

https://github.com/buckket/go-blurhash/blob/master/encode.go#L110-L111

height := (*rgba).Bounds().Max.Y width := (*rgba).Bounds().Max.X

https://github.com/buckket/go-blurhash/blob/master/encode.go#L131

rt, gt, bt, _ := (*rgba).At(x, y).RGBA()
enhancement
opened by diamondburned 1