goimagehash

Install the library using go get:

go get github.com/corona10/goimagehash

You can persist image hashes by dumping them to an io.Writer and reloading them from an io.Reader. This is useful for storing hashes in databases or files to avoid re-processing images.

• Use Dump(io.Writer) to serialize a hash.
• Use LoadImageHash(io.Reader) or LoadExtImageHash(io.Reader) to deserialize a hash.

Note: The older FromString methods are deprecated as of v1.0.0.

var b bytes.Buffer
foo := bufio.NewWriter(&b)

// Serialize
_ = hash4.Dump(foo)
foo.Flush()

// Deserialize
bar := bufio.NewReader(&b)
hash5, _ := goimagehash.LoadExtImageHash(bar)

Use the Bits() method on a hash object to retrieve the actual bit size of the generated hash. This is particularly useful when using extended hash functions where the dimensions are configurable.

fmt.Printf("hash bit size: %v\n", hash.Bits())

The ExtImageHash type is used for hashes that exceed 64 bits, represented as a slice of uint64. It includes the bits count and the Kind. Use NewExtImageHash to initialize it. You can compare two extended hashes using Distance(other *ExtImageHash), which requires both hashes to have the same Kind, the same total bit size, and the same number of uint64 elements.

import "github.com/corona10/goimagehash"

// Create an extended hash (e.g., 128 bits using two uint64s)
hash1 := goimagehash.NewExtImageHash([]uint64{1, 2}, goimagehash.DHash, 128)
hash2 := goimagehash.NewExtImageHash([]uint64{1, 3}, goimagehash.DHash, 128)

dist, err := hash1.Distance(hash2)
if err != nil {
	// handle error
}
fmt.Printf("Distance: %d\n", dist)

You can persist ImageHash or ExtImageHash objects using binary serialization via the gob package.

For ImageHash:

• Use Dump(w io.Writer) to write the hash to a stream.
• Use LoadImageHash(b io.Reader) to reconstruct a hash from a stream.

For ExtImageHash:

• Use Dump(w io.Writer) to write the hash to a stream.
• Use LoadExtImageHash(b io.Reader) to reconstruct a hash from a stream.

The ImageHash type represents a standard 64-bit image hash. It is used to store the hash value and its algorithm type (Kind). You can create a new hash using NewImageHash, retrieve its value via GetHash(), and calculate the Hamming distance between two hashes using Distance(other *ImageHash). Note that Distance requires both hashes to have the same Kind.

import "github.com/corona10/goimagehash"

// Create a new 64-bit hash
hash1 := goimagehash.NewImageHash(123456789, goimagehash.PHash)
hash2 := goimagehash.NewImageHash(123456790, goimagehash.PHash)

// Calculate distance
dist, err := hash1.Distance(hash2)
if err != nil {
	// handle error
}
fmt.Printf("Distance: %d\n", dist)

Use these functions to generate standard 64-bit image hashes. They all take an image.Image as input and return an *ImageHash and an error. If the input image is nil, they return an error: image object can not be nil.

• AverageHash(img image.Image): Computes an average hash (aHash).
• DifferenceHash(img image.Image): Computes a difference hash (dHash).
• PerceptionHash(img image.Image): Computes a perception hash (pHash) using DCT (Discrete Cosine Transform).

import (
	"image"
	"github.com/corona10/goimagehash"
)

// Example usage
hash, err := goimagehash.AverageHash(myImage)
if err != nil {
	// handle error
}

You can represent hashes as hex strings for easy storage or transmission.

ImageHash (64-bit):

• ToString(): Returns a string in the format k:hex (e.g., p:0000000000000001).
• ImageHashFromString(s string): Deprecated. Use LoadImageHash with a binary stream instead.

ExtImageHash (Large):

• ToString(): Returns a string in the format k:hex_sequence (e.g., d:010203...).
• ExtImageHashFromString(s string): Deprecated. Use LoadExtImageHash with a binary stream instead.

The Kind type defines the algorithm used to generate the hash. When comparing hashes via Distance, the Kind must match.

Supported values:

• Unknown: Default/unknown hash type.
• AHash: Average hash.
• PHash: Perceptual hash.
• DHash: Difference hash.
• WHash: Wavelet hash.

const (
	Unknown Kind = iota
	AHash
	PHash
	DHash
	WHash
)