README.md (4113B)
1 # go-blurhash [](https://travis-ci.org/buckket/go-blurhash) [](https://goreportcard.com/report/github.com/buckket/go-blurhash) [](https://codecov.io/gh/buckket/go-blurhash) [](https://pkg.go.dev/github.com/buckket/go-blurhash) 2 3 **go-blurhash** is a pure Go implementation of the [BlurHash](https://github.com/woltapp/blurhash) algorithm, which is used by 4 [Mastodon](https://github.com/tootsuite/mastodon) an other Fediverse software to implement a swift way of preloading placeholder images as well 5 as hiding sensitive media. Read more about it [here](https://blog.joinmastodon.org/2019/05/improving-support-for-adult-content-on-mastodon/). 6 7 **tl;dr:** BlurHash is a compact representation of a placeholder for an image. 8 9 This library allows generating the BlurHash of a given image, as well as 10 reconstructing a blurred version with specified dimensions from a given BlurHash. 11 12 This library is based on the following reference implementations: 13 - Encoder: [https://github.com/woltapp/blurhash/blob/master/C](https://github.com/woltapp/blurhash/blob/master/C) (C) 14 - Deocder: [https://github.com/woltapp/blurhash/blob/master/TypeScript](https://github.com/woltapp/blurhash/blob/master/TypeScript) (TypeScript) 15 16 BlurHash is written by [Dag Ågren](https://github.com/DagAgren) / [Wolt](https://github.com/woltapp). 17 18 | | Before | After | 19 | ---------- |:------------------------------:| :-----------------------------:| 20 | **Image** | ![alt text][test] | "LFE.@D9F01_2%L%MIVD*9Goe-;WB" | 21 | **Hash** | "LFE.@D9F01_2%L%MIVD*9Goe-;WB" | ![alt text][test_blur] 22 23 [test]: test.png "Blurhash example input." 24 [test_blur]: test_blur.png "Blurhash example output" 25 26 ## Installation 27 28 ### From source 29 30 go get -u github.com/buckket/go-blurhash 31 32 ## Usage 33 34 go-blurhash exports three functions: 35 ```go 36 func blurhash.Encode(xComponents, yComponents int, rgba image.Image) (string, error) 37 func blurhash.Decode(hash string, width, height, punch int) (image.Image, error) 38 func blurhash.Components(hash string) (xComponents, yComponents int, err error) 39 ``` 40 41 Here’s a simple demonstration. Check [pkg.go.dev](https://pkg.go.dev/github.com/buckket/go-blurhash) for the full documentation. 42 43 ```go 44 package main 45 46 import ( 47 "fmt" 48 "github.com/buckket/go-blurhash" 49 "image/png" 50 "os" 51 ) 52 53 func main() { 54 // Generate the BlurHash for a given image 55 imageFile, _ := os.Open("test.png") 56 loadedImage, err := png.Decode(imageFile) 57 str, _ := blurhash.Encode(4, 3, loadedImage) 58 if err != nil { 59 // Handle errors 60 } 61 fmt.Printf("Hash: %s\n", str) 62 63 // Generate an image for a given BlurHash 64 // Width will be 300px and Height will be 500px 65 // Punch specifies the contrasts and defaults to 1 66 img, err := blurhash.Decode(str, 300, 500, 1) 67 if err != nil { 68 // Handle errors 69 } 70 f, _ := os.Create("test_blur.png") 71 _ = png.Encode(f, img) 72 73 // Get the x and y components used for encoding a given BlurHash 74 x, y, err := blurhash.Components("LFE.@D9F01_2%L%MIVD*9Goe-;WB") 75 if err != nil { 76 // Handle errors 77 } 78 fmt.Printf("xComponents: %d, yComponents: %d", x, y) 79 } 80 ``` 81 82 ## Limitations 83 84 - Presumably a bit slower than the C implementation (TODO: Benchmarks) 85 86 ## Notes 87 88 - As mentioned [here](https://github.com/woltapp/blurhash#how-fast-is-encoding-decoding), it’s best to 89 generate very small images (~32x32px) via BlurHash and scale them up to the desired dimensions afterwards for optimal performance. 90 - Since [#2](https://github.com/buckket/go-blurhash/pull/2) we diverted from the reference implementation by memorizing sRGBtoLinear values, thus increasing encoding speed at the cost of higher memory usage. 91 - Starting with v1.1.0 the signature of blurhash.Encode() has changed slightly (see [#3](https://github.com/buckket/go-blurhash/issues/3)). 92 93 ## License 94 95 GNU GPLv3+ 96