thumbhash

README

go-thumbhash

Introduction

The go-thumbhash library implements the Thumbhash image placeholder generation algorithm invented by Evan Wallace.

This algorithm is used to calculate a small binary hash representing an image using a Discrete Cosine Transform. The hash can then be used to generate a lossy representation of the original image.

The main use case is progressive loading of a web page containing lots of images, e.g. a photo gallery. Store the hash of each image in your database, and send it in the HTML document. On the client side, use Javascript (e.g. Evan Wallace's library) to generate a placeholder image from the hash. Then load the original image asynchronously.

Usage

Refer to the Go package documentation for information about the API.

See the thumbhash program for a practical use case.

Licensing

Go-thumbhash is open source software distributed under the ISC license.

Documentation

Index

• Variables
• func DecodeImage(hashData []byte) (image.Image, error)
• func DecodeImageWithCfg(hashData []byte, cfg DecodingCfg) (image.Image, error)
• func EncodeImage(img image.Image) []byte
• type DecodingCfg
• type Hash
  • func (h *Hash) Decode(data []byte, cfg *DecodingCfg) error
  • func (h *Hash) Encode() []byte
  • func (hash *Hash) Size(baseSize int) (w int, h int)

Variables

var (
	ErrInvalidHash = errors.New("invalid hash")
)

Functions

func DecodeImage

func DecodeImage(hashData []byte) (image.Image, error)

DecodeImage returns the image associated with a binary hash using the default decoding configuration.

func DecodeImageWithCfg

func DecodeImageWithCfg(hashData []byte, cfg DecodingCfg) (image.Image, error)

DecodeImageWithCfg returns the image associated with a binary hash.

func EncodeImage

func EncodeImage(img image.Image) []byte

EncodeImage returns the binary hash of an image.

Types

type DecodingCfg

type DecodingCfg struct {
	BaseSize        int     // the base image size (default: 32px)
	SaturationBoost float64 // the factor applied to increase image saturation (default: 1.25)
}

DecodingCfg contains the parameters used for image decoding. Decoding will use default values for uninitialized members.

type Hash

type Hash struct {
	LDC      float64
	PDC      float64
	QDC      float64
	LScale   float64
	HasAlpha bool

	Lx          int
	Ly          int
	LCount      int
	PScale      float64
	QScale      float64
	IsLandscape bool

	ADC    float64 // if HasAlpha
	AScale float64 // if HasAlpha

	LAC []float64
	PAC []float64
	QAC []float64
	AAC []float64 // if HasAlpha
}

Hash represents the set of data stored in an image hash.

func (*Hash) Decode

func (h *Hash) Decode(data []byte, cfg *DecodingCfg) error

Decode extract data from the binary representation of a hash.

func (*Hash) Encode

func (h *Hash) Encode() []byte

Encode returns the binary representation of a hash.

func (*Hash) Size

func (hash *Hash) Size(baseSize int) (w int, h int)

Size return the width and height of the image associated with a hash according to a specific base size.