goimagehash

README

goimagehash

Inspired by imagehash

A image hashing library written in Go. ImageHash supports:

• Average hashing
• Difference hashing
• Perception hashing
• Double Gradient hashing - An advanced version of gradient hashing that combines both horizontal and vertical gradient comparisons
• Wavelet hashing [TODO]

Installation

go get github.com/corona10/goimagehash

Special thanks to

• Haeun Kim

Usage

func main() {
        file1, _ := os.Open("sample1.jpg")
        file2, _ := os.Open("sample2.jpg")
        defer file1.Close()
        defer file2.Close()

        img1, _ := jpeg.Decode(file1)
        img2, _ := jpeg.Decode(file2)
        hash1, _ := goimagehash.AverageHash(img1)
        hash2, _ := goimagehash.AverageHash(img2)
        distance, _ := hash1.Distance(hash2)
        fmt.Printf("Distance between images: %v\n", distance)

        hash1, _ = goimagehash.DifferenceHash(img1)
        hash2, _ = goimagehash.DifferenceHash(img2)
        distance, _ = hash1.Distance(hash2)
        fmt.Printf("Distance between images: %v\n", distance)

        // Double Gradient Hash
        dgHash1, _ := goimagehash.DoubleGradientHash(img1, 8, 8)
        dgHash2, _ := goimagehash.DoubleGradientHash(img2, 8, 8)
        distance, _ = dgHash1.Distance(dgHash2)
        fmt.Printf("DoubleGradient distance between images: %v\n", distance)
        fmt.Printf("DoubleGradient hash (base64): %s\n", dgHash1.ToBase64())

        width, height := 8, 8
        hash3, _ := goimagehash.ExtAverageHash(img1, width, height)
        hash4, _ := goimagehash.ExtAverageHash(img2, width, height)
        distance, _ = hash3.Distance(hash4)
        fmt.Printf("Distance between images: %v\n", distance)
        fmt.Printf("hash3 bit size: %v\n", hash3.Bits())
        fmt.Printf("hash4 bit size: %v\n", hash4.Bits())

        var b bytes.Buffer
        foo := bufio.NewWriter(&b)
        _ = hash4.Dump(foo)
        foo.Flush()
        bar := bufio.NewReader(&b)
        hash5, _ := goimagehash.LoadExtImageHash(bar)
}

Release Note

v1.2.0

• Add Double Gradient hashing algorithm support
• Add CLI tool with support for all hashing algorithms
• Support for base64 output format (without padding)
• Enhanced batch processing with duplicate detection

v1.1.0

• The performance of Perceptionhash is enhanced.

v1.0.3

• Add workflow for GithubAction
• Fix typo on the GoDoc for LoadImageHash

v1.0.2

• go.mod is now used for install goimagehash

v1.0.1

• Perception/ExtPerception hash creation times are reduced

v1.0.0

IMPORTANT goimagehash v1.0.0 does not have compatible with the before version for future features

• More flexible extended hash APIs are provided (ExtAverageHash, ExtPerceptionHash, ExtDifferenceHash)
• New serialization APIs are provided(ImageHash.Dump, ExtImageHash.Dump)
• ExtImageHashFromString, ImageHashFromString is deprecated and will be removed
• New deserialization APIs are provided(LoadImageHash, LoadExtImageHash)
• Bits APIs are provided to measure actual bit size of hash

v0.3.0

• Support DifferenceHashExtend.
• Support AverageHashExtend.
• Support PerceptionHashExtend by @TokyoWolFrog.

v0.2.0

• Perception Hash is updated.
• Fix a critical bug of finding median value.

v0.1.0

• Support Average hashing
• Support Difference hashing
• Support Perception hashing
• Use bits.OnesCount64 for computing Hamming distance by @dominikh
• Support hex serialization methods to ImageHash by @brunoro

Documentation

Index

• func DoubleGradientHashToBase64(img image.Image, width, height int) (string, error)
• type ExtImageHash
  • func DoubleGradientHash(img image.Image, width, height int) (*ExtImageHash, error)
  • func ExtAverageHash(img image.Image, width, height int) (*ExtImageHash, error)
  • func ExtDifferenceHash(img image.Image, width, height int) (*ExtImageHash, error)
  • func ExtImageHashFromString(s string) (*ExtImageHash, error)
  • func ExtPerceptionHash(img image.Image, width, height int) (*ExtImageHash, error)
  • func LoadExtImageHash(b io.Reader) (*ExtImageHash, error)
  • func NewExtImageHash(hash []uint64, kind Kind, bits int) *ExtImageHash
  • func (h *ExtImageHash) Bits() int
  • func (h *ExtImageHash) Distance(other *ExtImageHash) (int, error)
  • func (h *ExtImageHash) Dump(w io.Writer) error
  • func (h *ExtImageHash) GetHash() []uint64
  • func (h *ExtImageHash) GetKind() Kind
  • func (h *ExtImageHash) ToBase64() string
  • func (h *ExtImageHash) ToString() string
• type ImageHash
  • func AverageHash(img image.Image) (*ImageHash, error)
  • func DifferenceHash(img image.Image) (*ImageHash, error)
  • func ImageHashFromString(s string) (*ImageHash, error)
  • func LoadImageHash(b io.Reader) (*ImageHash, error)
  • func NewImageHash(hash uint64, kind Kind) *ImageHash
  • func PerceptionHash(img image.Image) (*ImageHash, error)
  • func (h *ImageHash) Bits() int
  • func (h *ImageHash) Distance(other *ImageHash) (int, error)
  • func (h *ImageHash) Dump(w io.Writer) error
  • func (h *ImageHash) GetHash() uint64
  • func (h *ImageHash) GetKind() Kind
  • func (h *ImageHash) ToString() string
• type Kind

Functions

func DoubleGradientHashToBase64

func DoubleGradientHashToBase64(img image.Image, width, height int) (string, error)

DoubleGradientHashToBase64 is a convenience function that computes DoubleGradient hash and returns base64 string without padding (compatible with Rust img_hash library)

Types

type ExtImageHash

type ExtImageHash struct {
	// contains filtered or unexported fields
}

ExtImageHash is a struct of big hash computation.

func DoubleGradientHash

func DoubleGradientHash(img image.Image, width, height int) (*ExtImageHash, error)

DoubleGradientHash implements the DoubleGradient algorithm similar to the Rust img_hash library DoubleGradient resizes the grayscaled image to (width/2 + 1) x (height/2 + 1) and compares columns in addition to rows, combining both horizontal and vertical gradient comparisons.

func ExtAverageHash

func ExtAverageHash(img image.Image, width, height int) (*ExtImageHash, error)

ExtAverageHash function returns ahash of which the size can be set larger than uint64 Support 64bits ahash (width=8, height=8) and 256bits ahash (width=16, height=16)

func ExtDifferenceHash

func ExtDifferenceHash(img image.Image, width, height int) (*ExtImageHash, error)

ExtDifferenceHash function returns dhash of which the size can be set larger than uint64 Support 64bits dhash (width=8, height=8) and 256bits dhash (width=16, height=16)

func ExtImageHashFromString

func ExtImageHashFromString(s string) (*ExtImageHash, error)

ExtImageHashFromString returns a big hash from a hex representation

Deprecated: Use goimagehash.LoadExtImageHash instead.

func ExtPerceptionHash

func ExtPerceptionHash(img image.Image, width, height int) (*ExtImageHash, error)

ExtPerceptionHash function returns phash of which the size can be set larger than uint64 Some variable name refer to https://github.com/JohannesBuchner/imagehash/blob/master/imagehash/__init__.py Support 64bits phash (width=8, height=8) and 256bits phash (width=16, height=16) Important: width * height should be the power of 2

func LoadExtImageHash

func LoadExtImageHash(b io.Reader) (*ExtImageHash, error)

LoadExtImageHash method loads a ExtImageHash from io.Reader.

func NewExtImageHash

func NewExtImageHash(hash []uint64, kind Kind, bits int) *ExtImageHash

NewExtImageHash function creates a new big hash

func (*ExtImageHash) Bits

func (h *ExtImageHash) Bits() int

Bits method returns an actual hash bit size

func (*ExtImageHash) Distance

func (h *ExtImageHash) Distance(other *ExtImageHash) (int, error)

Distance method returns a distance between two big hashes

func (*ExtImageHash) Dump

func (h *ExtImageHash) Dump(w io.Writer) error

Dump method writes a binary serialization into w io.Writer.

func (*ExtImageHash) GetHash

func (h *ExtImageHash) GetHash() []uint64

GetHash method returns a big hash value

func (*ExtImageHash) GetKind

func (h *ExtImageHash) GetKind() Kind

GetKind method returns a kind of big hash

func (*ExtImageHash) ToBase64

func (h *ExtImageHash) ToBase64() string

ToBase64 converts ExtImageHash to base64 string without padding (like Rust library)

func (*ExtImageHash) ToString

func (h *ExtImageHash) ToString() string

ToString returns a hex representation of big hash

type ImageHash

type ImageHash struct {
	// contains filtered or unexported fields
}

ImageHash is a struct of hash computation.

func AverageHash

func AverageHash(img image.Image) (*ImageHash, error)

AverageHash function returns a hash computation of average hash. Implementation follows http://www.hackerfactor.com/blog/index.php?/archives/432-Looks-Like-It.html

func DifferenceHash

func DifferenceHash(img image.Image) (*ImageHash, error)

DifferenceHash function returns a hash computation of difference hash. Implementation follows http://www.hackerfactor.com/blog/?/archives/529-Kind-of-Like-That.html

func ImageHashFromString

func ImageHashFromString(s string) (*ImageHash, error)

ImageHashFromString returns an image hash from a hex representation

Deprecated: Use goimagehash.LoadImageHash instead.

func LoadImageHash

func LoadImageHash(b io.Reader) (*ImageHash, error)

LoadImageHash method loads a ImageHash from io.Reader.

func NewImageHash

func NewImageHash(hash uint64, kind Kind) *ImageHash

NewImageHash function creates a new image hash.

func PerceptionHash

func PerceptionHash(img image.Image) (*ImageHash, error)

PerceptionHash function returns a hash computation of phash. Implementation follows http://www.hackerfactor.com/blog/index.php?/archives/432-Looks-Like-It.html

func (*ImageHash) Bits

func (h *ImageHash) Bits() int

Bits method returns an actual hash bit size

func (*ImageHash) Distance

func (h *ImageHash) Distance(other *ImageHash) (int, error)

Distance method returns a distance between two hashes.

func (*ImageHash) Dump

func (h *ImageHash) Dump(w io.Writer) error

Dump method writes a binary serialization into w io.Writer.

func (*ImageHash) GetHash

func (h *ImageHash) GetHash() uint64

GetHash method returns a 64bits hash value.

func (*ImageHash) GetKind

func (h *ImageHash) GetKind() Kind

GetKind method returns a kind of image hash.

func (*ImageHash) ToString

func (h *ImageHash) ToString() string

ToString returns a hex representation of the hash

type Kind

type Kind int

Kind describes the kinds of hash.

const (
	// Unknown is a enum value of the unknown hash.
	Unknown Kind = iota
	// AHash is a enum value of the average hash.
	AHash
	//PHash is a enum value of the perceptual hash.
	PHash
	// DHash is a enum value of the difference hash.
	DHash
	// WHash is a enum value of the wavelet hash.
	WHash
	// DGHash is a enum value of the double gradient hash.
	DGHash
)