images

README

Comparing images in Go ➔ LATEST version

Near duplicates and resized images can be found with the module.

Demo: similar image search and clustering (deployed from).

Semantic versions:

• v1/v2 (/images) - this repository,
• v3 (/images3),
• v4 (/images4) - latest recommended.

All versions will be kept available indefinitely.

About this repo

There are no dependencies: only the Golang standard library is used. Supported image types: GIF, JPEG and PNG (golang.org/pkg/image/ as in October 2018).

Similar function gives a verdict whether 2 images are similar or not. The library also contains wrapper functions to open/save images and basic image resampling/resizing.

SimilarCustom function allows your own similarity metric thresholds.

Documentation: godoc.

Example of comparing 2 photos

To test this example go-file, you need to initialize modules from command line, because the latest version (v2) uses them:

go mod init foo

Here foo can be anything for testing purposes. Then get the required import:

go get github.com/vitali-fedulov/images/v2

Now you are ready to run or build the example.

package main

import (
	"fmt"

	// Notice v2, which is module-based most recent version.
	// Explanation: https://go.dev/blog/v2-go-modules
	"github.com/vitali-fedulov/images/v2"
)

func main() {
	
	// Open photos.
	imgA, err := images.Open("photoA.jpg")
	if err != nil {
		panic(err)
	}
	imgB, err := images.Open("photoB.jpg")
	if err != nil {
		panic(err)
	}
	
	// Calculate hashes and image sizes.
	hashA, imgSizeA := images.Hash(imgA)
	hashB, imgSizeB := images.Hash(imgB)
	
	// Image comparison.
	if images.Similar(hashA, hashB, imgSizeA, imgSizeB) {
		fmt.Println("Images are similar.")
	} else {
		fmt.Println("Images are distinct.")
	}
}

Algorithm for image comparison

Detailed explanation, also as a PDF.

Summary: In the algorithm images are resized to small squares of fixed size. A number of masks representing several sample pixels are run against the resized images to calculate average color values. Then the values are compared to give the similarity verdict. Also image proportions are used to avoid matching images of distinct shape.

Documentation

Overview

Package images allows image comparison by perceptual similarity. Supported image types are those default to the Go image package https://golang.org/pkg/image/ (which are GIF, JPEG and PNG in October 2018).

Index

• func Gif(img *image.RGBA, path string)
• func Hash(img image.Image) (h []float32, imgSize image.Point)
• func Jpg(img *image.RGBA, path string, quality int)
• func Open(path string) (img image.Image, err error)
• func Png(img *image.RGBA, path string)
• func ResampleByNearest(inImg image.Image, outImgSize image.Point) (outImg image.RGBA, inImgSize image.Point)
• func Similar(hA, hB []float32, imgSizeA, imgSizeB image.Point) bool
• func SimilarCustom(hA, hB []float32, imgSizeA, imgSizeB image.Point) (delta, euc, eucNorm, corr float32)

Functions

func Gif

func Gif(img *image.RGBA, path string)

Gif saves image.RGBA to a file.

func Hash

func Hash(img image.Image) (h []float32,
	imgSize image.Point)

Hash calculates a slice of average color values of an image at the position of white pixels of a mask. One average value corresponds to one mask. The function also returns the original image width and height.

func Jpg

func Jpg(img *image.RGBA, path string, quality int)

Jpg saves image.RGBA to a file.

func Open

func Open(path string) (img image.Image, err error)

Open opens and decodes an image file for a given path.

func Png

func Png(img *image.RGBA, path string)

Png saves image.RGBA to a file.

func ResampleByNearest

func ResampleByNearest(inImg image.Image, outImgSize image.Point) (
	outImg image.RGBA, inImgSize image.Point)

ResampleByNearest resizes an image by the nearest neighbour method to the output size outX, outY. It also returns the size inX, inY of the input image.

func Similar

func Similar(hA, hB []float32, imgSizeA, imgSizeB image.Point) bool

Similar function gives a verdict for image A and B based on their hashes and sizes. The input parameters are generated with the Hash function.

func SimilarCustom

func SimilarCustom(hA, hB []float32, imgSizeA, imgSizeB image.Point) (
	delta, euc, eucNorm, corr float32)

SimilarCustom function returns similarity metrics instead of returning a verdict as the function Similar does. Then you can decide on your own which thresholds to use for each filter, or filter/rank by combining the values. delta is image proportions metric (sizeThreshold in func Similar). The larger the delta the more distinct are images by their proportions. euc is Euclidean metric. The larger euc is the more distinct are images visually. eucNorm is Euclidean metric for normalized hash values (visially similar to autolevels in graphic editors). The larger eucNorm is the more distinct are images visually after autolevelling (normalization). corr is sign correlation of color values. The larger the value the more similar are images (correlate more to each other). Demo returned values are used in TestSimilarCustom function.