1st commit

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Vitali Fedulov (fedulov.vitali@gmail.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,63 @@
+# Find similar images with Go
+
+Near duplicates and resized images can be found with the package. No dependencies.
+
+**Demo**: [similar image clustering](https://vitali-fedulov.github.io/similar.pictures/) based on similar algorithm.
+
+**This is the latest major version (v4)** of [v1/2](https://github.com/vitali-fedulov/images) and [v3](https://github.com/vitali-fedulov/images3). The changes vs v3 are: simplified func `Icon` input, more than 2x smaller memory footprint of icons, additional IconNN function, fixed GIF support, removal of dependencies, removal of hashes (a separate package for hashes will be created and linked from here soon).
+
+Func `Similar` gives a verdict whether 2 images are similar with well-tested default thresholds.
+
+Func `EucMetric` can be used instead, when you need different precision or want to sort by similarity. Func `PropMetric` can be used for customization of image proportion threshold.
+
+Func `Open` supports JPEG, PNG and GIF. But other image types can be used through third-party decoders, because input for func `Icon` is Golang `image.Image`.
+
+[Go doc](https://pkg.go.dev/github.com/vitali-fedulov/images4) for code reference.
+
+## Example of comparing 2 images
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/vitali-fedulov/images4"
+)
+
+func main() {
+
+	// Photos to compare.
+	path1 := "1.jpg"
+	path2 := "2.jpg"
+
+	// Open files (discarding errors here).
+	img1, _ := images4.Open(path1)
+	img2, _ := images4.Open(path2)
+
+	// Icons are compact image representations (image "hashes").
+	// Name "hash" is not used intentionally.
+	icon1 := images4.Icon(img1)
+	icon2 := images4.Icon(img2)
+
+	// Comparison.
+	// Images are not used directly. Icons are used instead,
+	// because they have tiny memory footprint and fast to compare.
+	if images4.Similar(icon1, icon2) {
+		fmt.Println("Images are similar.")
+	} else {
+		fmt.Println("Images are distinct.")
+	}
+}
+```
+
+## Algorithm
+
+[Detailed explanation](https://vitali-fedulov.github.io/similar.pictures/algorithm-for-perceptual-image-comparison.html), also as a [PDF](https://github.com/vitali-fedulov/research/blob/main/Algorithm%20for%20perceptual%20image%20comparison.pdf).
+
+Summary: Images are resized in a special way to squares of fixed size called "icons". Euclidean distance between the icons is used to give the similarity verdict. Also image proportions are used to avoid matching images of distinct shape.
+
+## Customization suggestions
+
+To increase precision you can either use your own thresholds in func `EucMetric` (and `PropMetric`) OR generate icons for image sub-regions and compare those icons.
+
+To speedup file processing you may want to generate icons for available image thumbnails. Specifically, many JPEG images contain [EXIF thumbnails](https://vitali-fedulov.github.io/similar.pictures/jpeg-thumbnail-reader.html), you could considerably speedup the reads by using decoded thumbnails to feed into func `Icon`. External packages to read thumbnails: [1](https://github.com/dsoprea/go-exif) and [2](https://github.com/rwcarlsen/goexif). A note of caution: in rare cases there could be [issues](https://security.stackexchange.com/questions/116552/the-history-of-thumbnails-or-just-a-previous-thumbnail-is-embedded-in-an-image/201785#201785) with thumbnails not matching image content. EXIF standard specification: [1](https://www.media.mit.edu/pia/Research/deepview/exif.html) and [2](https://www.exif.org/Exif2-2.PDF).

const.go

@@ -0,0 +1,50 @@
+package images4
+
+const (
+
+	// Icon parameters.
+
+	// Image resolution of the icon
+	// is very small (11x11 pixels), therefore original
+	// image details are lost in downsampling, except
+	// when source images have very low resolution
+	// (e.g. favicons or simple logos). This is useful
+	// from the privacy perspective if you are to use
+	// generated icons in a large searchable database.
+	iconSize = 11
+	// Resampling rate defines how much information
+	// (how many pixels) from the source image are used
+	// to generate an icon. Too few will produce worse
+	// comparisons. Too many will consume too much compute.
+	samples = 12
+
+	// Similarity parameters.
+
+	// Cutoff value for color distance.
+	colorDiff = 50
+	// Cutoff coefficient for Euclidean distance (squared).
+	euclCoeff = 0.2
+	// Coefficient of sensitivity for Cb/Cr channels vs Y.
+	chanCoeff = 2
+
+	// Similarity thresholds.
+
+	// Euclidean distance threshold (squared) for Y-channel.
+	thY = float64(iconSize*iconSize) * float64(colorDiff*colorDiff) * euclCoeff
+	// Euclidean distance threshold (squared) for Cb and Cr channels.
+	thCbCr = thY * chanCoeff
+	// Proportion similarity threshold (5%).
+	thProp = 0.05
+
+	// Auxiliary constants.
+
+	numPix           = iconSize * iconSize
+	largeIconSize    = iconSize*2 + 1
+	resizedImgSize   = largeIconSize * samples
+	invSamplePixels2 = 1 / float64(samples*samples)
+	oneNinth         = 1 / float64(9)
+	one255th         = 1 / float64(255)
+	one255th2        = one255th * one255th
+	sq255            = 255 * 255
+	maxUint16        = 65535
+)

go.mod

@@ -0,0 +1,3 @@
+module github.com/vitali-fedulov/images4
+
+go 1.16

icon.go

@@ -0,0 +1,233 @@
+package images4
+
+import (
+	"image"
+	"image/color"
+)
+
+// Icon has square shape. Its pixels are uint16 values
+// in 3 channels. uint16 is intentional to preserve color
+// relationships from the full-size image. It is a 255-
+// premultiplied color value in [0, 255] range.
+type IconT struct {
+	Pixels  []uint16    // Visual signature.
+	ImgSize image.Point // Original image size.
+}
+
+// Icon generates a normalized image signature ("icon").
+// Generated icons can then be stored in a database and used
+// for comparison. Icon is the recommended function,
+// vs less robust func IconNN.
+func Icon(img image.Image) IconT {
+
+	icon := IconNN(img)
+
+	// Maximizing icon contrast. This to reflect on the human visual
+	// experience, when high contrast (normalized) images are easier
+	// to see. Normalization also compensates for considerable loss
+	// of visual information during scarse resampling during
+	// icon creation step.
+	icon.normalize()
+
+	return icon
+}
+
+// IconNN generates a NON-normalized image signature (icon).
+// Icons made with IconNN can be used instead of icons made with
+// func Icon, but mostly for experimental purposes, allowing
+// better understand how the algorithm works, or performing
+// less agressive customized normalization. Not for general use.
+func IconNN(img image.Image) IconT {
+
+	// Resizing to a large icon approximating average color
+	// values of the source image. YCbCr space is used instead
+	// of RGB for better results in image comparison.
+	resImg, imgSize := resizeByNearest(
+		img, image.Point{resizedImgSize, resizedImgSize})
+	largeIcon := sizedIcon(largeIconSize)
+	var r, g, b, sumR, sumG, sumB uint32
+	var yc, cb, cr float64
+	// For each pixel of the largeIcon.
+	for x := 0; x < largeIconSize; x++ {
+		for y := 0; y < largeIconSize; y++ {
+			sumR, sumG, sumB = 0, 0, 0
+			// Sum over pixels of resImg.
+			for m := 0; m < samples; m++ {
+				for n := 0; n < samples; n++ {
+					r, g, b, _ =
+						resImg.At(
+							x*samples+m, y*samples+n).RGBA()
+					sumR += r >> 8
+					sumG += g >> 8
+					sumB += b >> 8
+				}
+			}
+			set(largeIcon, largeIconSize, image.Point{x, y},
+				float64(sumR)*invSamplePixels2,
+				float64(sumG)*invSamplePixels2,
+				float64(sumB)*invSamplePixels2)
+		}
+	}
+
+	// Box blur filter with resizing to the final icon of smaller size.
+
+	icon := sizedIcon(iconSize)
+	// Pixel positions in the final icon.
+	var xd, yd int
+	var c1, c2, c3, s1, s2, s3 float64
+
+	// For pixels of source largeIcon with stride 2.
+	for x := 1; x < largeIconSize-1; x += 2 {
+		xd = x / 2
+		for y := 1; y < largeIconSize-1; y += 2 {
+			yd = y / 2
+			// For each pixel of a 3x3 box.
+			for n := -1; n <= 1; n++ {
+				for m := -1; m <= 1; m++ {
+					c1, c2, c3 =
+						get(largeIcon, largeIconSize,
+							image.Point{x + n, y + m})
+					s1, s2, s3 = s1+c1, s2+c2, s3+c3
+				}
+			}
+			yc, cb, cr = yCbCr(
+				s1*oneNinth, s2*oneNinth, s3*oneNinth)
+			set(icon, iconSize, image.Point{xd, yd},
+				yc, cb, cr)
+			s1, s2, s3 = 0, 0, 0
+		}
+	}
+
+	icon.ImgSize = imgSize
+	return icon
+}
+
+// EmptyIcon is an icon constructor in case you need an icon
+// with nil values, for example for convenient error handling.
+// Then you can use icon.Pixels == nil condition.
+func EmptyIcon() (icon IconT) {
+	icon = sizedIcon(iconSize)
+	icon.Pixels = nil
+	return icon
+}
+
+func sizedIcon(size int) (icon IconT) {
+	icon.Pixels = make([]uint16, size*size*3)
+	return icon
+}
+
+// ArrIndex gets a pixel position in 1D array from a point
+// of 2D array. ch is color channel index (0 to 2).
+func arrIndex(p image.Point, size, ch int) (index int) {
+	return size*(ch*size+p.Y) + p.X
+}
+
+// Set places pixel values in an icon at a point.
+// c1, c2, c3 are color values for each channel
+// (RGB for example). Size is icon size.
+func set(icon IconT, size int, p image.Point, c1, c2, c3 float64) {
+	// Multiplication by 255 is basically encoding float64 as uint16.
+	icon.Pixels[arrIndex(p, size, 0)] = uint16(c1 * 255)
+	icon.Pixels[arrIndex(p, size, 1)] = uint16(c2 * 255)
+	icon.Pixels[arrIndex(p, size, 2)] = uint16(c3 * 255)
+}
+
+// Get reads pixel values in an icon at a point.
+// c1, c2, c3 are color values for each channel
+// (RGB for example).
+func get(icon IconT, size int, p image.Point) (c1, c2, c3 float64) {
+	// Division by 255 is basically decoding uint16 into float64.
+	c1 = float64(icon.Pixels[arrIndex(p, size, 0)]) * one255th
+	c2 = float64(icon.Pixels[arrIndex(p, size, 1)]) * one255th
+	c3 = float64(icon.Pixels[arrIndex(p, size, 2)]) * one255th
+	return c1, c2, c3
+}
+
+// yCbCr transforms RGB components to YCbCr. This is a high
+// precision version different from the Golang image library
+// operating on uint8.
+func yCbCr(r, g, b float64) (yc, cb, cr float64) {
+	yc = 0.299000*r + 0.587000*g + 0.114000*b
+	cb = 128 - 0.168736*r - 0.331264*g + 0.500000*b
+	cr = 128 + 0.500000*r - 0.418688*g - 0.081312*b
+	return yc, cb, cr
+}
+
+// Normalize stretches histograms for the 3 channels of an icon, so that
+// min/max values of each channel are 0/255 correspondingly.
+// Note: values of IconT are premultiplied by 255, thus having maximum
+// value of sq255 constant corresponding to display color value of 255.
+func (src IconT) normalize() {
+
+	var c1Min, c2Min, c3Min, c1Max, c2Max, c3Max uint16
+	c1Min, c2Min, c3Min = maxUint16, maxUint16, maxUint16
+	c1Max, c2Max, c3Max = 0, 0, 0
+	var scale float64
+	var n int
+
+	// Looking for extreme values.
+	for n = 0; n < numPix; n++ {
+		// Channel 1.
+		if src.Pixels[n] > c1Max {
+			c1Max = src.Pixels[n]
+		}
+		if src.Pixels[n] < c1Min {
+			c1Min = src.Pixels[n]
+		}
+		// Channel 2.
+		if src.Pixels[n+numPix] > c2Max {
+			c2Max = src.Pixels[n+numPix]
+		}
+		if src.Pixels[n+numPix] < c2Min {
+			c2Min = src.Pixels[n+numPix]
+		}
+		// Channel 3.
+		if src.Pixels[n+2*numPix] > c3Max {
+			c3Max = src.Pixels[n+2*numPix]
+		}
+		if src.Pixels[n+2*numPix] < c3Min {
+			c3Min = src.Pixels[n+2*numPix]
+		}
+	}
+
+	// Normalization.
+	if c1Max != c1Min { // Must not divide by zero.
+		scale = sq255 / (float64(c1Max) - float64(c1Min))
+		for n = 0; n < numPix; n++ {
+			src.Pixels[n] = uint16(
+				(float64(src.Pixels[n]) - float64(c1Min)) *
+					scale)
+		}
+	}
+	if c2Max != c2Min { // Must not divide by zero.
+		scale = sq255 / (float64(c2Max) - float64(c2Min))
+		for n = 0; n < numPix; n++ {
+			src.Pixels[n+numPix] = uint16(
+				(float64(src.Pixels[n+numPix]) - float64(c2Min)) *
+					scale)
+		}
+	}
+	if c3Max != c3Min { // Must not divide by zero.
+		scale = sq255 / (float64(c3Max) - float64(c3Min))
+		for n = 0; n < numPix; n++ {
+			src.Pixels[n+2*numPix] = uint16(
+				(float64(src.Pixels[n+2*numPix]) - float64(c3Min)) *
+					scale)
+		}
+	}
+
+}
+
+// ToRGBA transforms a sized icon to image.RGBA. This is
+// an auxiliary function to visually evaluate an icon.
+func (icon IconT) ToRGBA(size int) *image.RGBA {
+	img := image.NewRGBA(image.Rect(0, 0, size, size))
+	for x := 0; x < size; x++ {
+		for y := 0; y < size; y++ {
+			r, g, b := get(icon, size, image.Point{x, y})
+			img.Set(x, y,
+				color.RGBA{uint8(r), uint8(g), uint8(b), 255})
+		}
+	}
+	return img
+}

icon_test.go

@@ -0,0 +1,158 @@
+package images4
+
+import (
+	"image"
+	"math"
+	"path"
+	"reflect"
+	"testing"
+)
+
+func TestSizedIcon(t *testing.T) {
+	icon := sizedIcon(4)
+	expected := 4 * 4 * 3
+	got := len(icon.Pixels)
+	if got != expected {
+		t.Errorf(
+			"Expected length %d, got %d.", expected, got)
+	}
+}
+
+func TestEmptyIcon(t *testing.T) {
+	icon1 := EmptyIcon()
+	icon2 := IconT{nil, image.Point{0, 0}}
+
+	if !reflect.DeepEqual(icon1.Pixels, icon2.Pixels) {
+		t.Errorf("Icons' Pixels mismatch. They must be equal: %v %v",
+			icon1.Pixels, icon2.Pixels)
+	}
+	if !reflect.DeepEqual(icon1.ImgSize, icon2.ImgSize) {
+		t.Errorf("Icons' ImgSize mismatch. They must be equal: %v %v",
+			icon1.ImgSize, icon2.ImgSize)
+	}
+}
+
+func TestArrIndex(t *testing.T) {
+	x, y := 2, 3
+	size := 4
+	ch := 2
+	got := arrIndex(image.Point{x, y}, size, ch)
+	expected := 46
+	if got != expected {
+		t.Errorf("Expected %d, got %d.", expected, got)
+	}
+	x, y = 1, 1
+	ch = 1
+	got = arrIndex(image.Point{x, y}, size, ch)
+	expected = 21
+	if got != expected {
+		t.Errorf("Expected %d, got %d.", expected, got)
+	}
+	x, y = 3, 3
+	ch = 0
+	got = arrIndex(image.Point{x, y}, size, ch)
+	expected = 15
+	if got != expected {
+		t.Errorf("Expected %d, got %d.", expected, got)
+	}
+}
+
+func TestSet(t *testing.T) {
+	icon := sizedIcon(4)
+	set(icon, 4, image.Point{1, 1}, 13.5, 29.9, 95.9)
+	expected := sizedIcon(4)
+	expectedPixels := []float64{0, 0, 0, 0, 0, 13.5, 0, 0, 0, 0, 0,
+		0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 29.9, 0, 0, 0, 0,
+		0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 95.9, 0, 0, 0,
+		0, 0, 0, 0, 0, 0, 0}
+	for i := range expectedPixels {
+		expected.Pixels[i] = uint16(expectedPixels[i] * 255)
+	}
+	if !reflect.DeepEqual(expected, icon) {
+		t.Errorf("Expected %v, got %v.", expected, icon)
+	}
+}
+
+func TestGet(t *testing.T) {
+	icon := sizedIcon(4)
+	iconPix := []float64{0, 0, 0, 0, 0, 13.5, 0, 0, 0, 0, 0, 0,
+		0, 0, 0, 0, 0, 0, 0, 0, 0, 29.9, 0, 0, 0, 0, 0,
+		0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 95.9, 0, 0, 0, 0,
+		0, 0, 0, 0, 0, 0}
+	for i := range iconPix {
+		icon.Pixels[i] = uint16(iconPix[i] * 255)
+	}
+	c1, c2, c3 := get(icon, 4, image.Point{1, 1})
+	if math.Abs(float64(c1)-13.5) > 0.1 || math.Abs(float64(c2)-29.9) > 0.1 || math.Abs(float64(c3)-95.9) > 0.1 {
+		t.Errorf(
+			"Expected near 13.5, 29.9, 95.9, got %v, %v, %v.",
+			c1, c2, c3)
+	}
+}
+
+// Only checking that image size is correct.
+func TestIcon(t *testing.T) {
+	const (
+		testDir1  = "testdata"
+		testDir2  = "resample"
+		imageName = "nearest533x400.png"
+	)
+	filePath := path.Join(testDir1, testDir2, imageName)
+	img, err := Open(filePath)
+	if err != nil {
+		t.Error(
+			"Cannot decode", filePath)
+	}
+	icon := Icon(img)
+	if icon.ImgSize.X != 533 || icon.ImgSize.Y != 400 {
+		t.Errorf(
+			"Expected image size (533, 400), got (%d, %d).",
+			icon.ImgSize.X, icon.ImgSize.Y)
+	}
+}
+
+func TestYCbCr(t *testing.T) {
+	var r, g, b float64 = 255, 255, 255
+	var eY, eCb, eCr float64 = 255, 128, 128
+	y, cb, cr := yCbCr(r, g, b)
+	// Int values, so the test does not become brittle.
+	if math.Abs(y-eY) > 0.1 ||
+		math.Abs(cb-eCb) > 0.1 ||
+		math.Abs(cr-eCr) > 0.1 {
+		t.Errorf("Expected (%v,%v,%v) got (%v,%v,%v).",
+			eY, eCb, eCr, y, cb, cr)
+	}
+	r, g, b = 14, 22, 250
+	// From the original external formula.
+	eY, eCb, eCr = 45.6, 243.3, 105.5
+	y, cb, cr = yCbCr(r, g, b)
+	// Int values, so the test does not become brittle.
+	if int(y) != int(eY) || int(cb) !=
+		int(eCb) || int(cr) != int(eCr) {
+		t.Errorf("Expected (%v,%v,%v) got (%v,%v,%v).",
+			int(eY), int(eCb), int(eCr),
+			int(y), int(cb), int(cr))
+	}
+}
+
+func testNormalize(src, want IconT, t *testing.T) {
+	src.normalize()
+	for i := range src.Pixels {
+		if math.Abs(float64(src.Pixels[i])-float64(want.Pixels[i]))/
+			float64(want.Pixels[i]) > 1 {
+			t.Errorf("Want %v, got %v.", want, src)
+			break
+		}
+	}
+}
+
+func TestNormalize(t *testing.T) {
+
+	src := EmptyIcon()
+	src.Pixels = []uint16{8670, 45801, 29935, 11700, 53747, 33743, 44189, 48647, 8000, 49182, 20434, 15423, 46834, 32946, 37230, 63317, 28058, 6485, 29179, 29196, 59058, 49234, 50741, 19913, 64476, 31201, 30996, 28808, 720, 48844, 41325, 19517, 30908, 58705, 20865, 4306, 2909, 58380, 28762, 27511, 48562, 5041, 51122, 30882, 57739, 29392, 35254, 61898, 39625, 23720, 59995, 51153, 50919, 28488, 35064, 33029, 33237, 36843, 20078, 25135, 6877, 11867, 56143, 10160, 15597, 43740, 8877, 35459, 60119, 20334, 16937, 56416, 6827, 38948, 44732, 54001, 60061, 60972, 57112, 16523, 61155, 5701, 40190, 55897, 7134, 16251, 39892, 19855, 43222, 54575, 59722, 54342, 23580, 26257, 61420, 815, 39345, 10940, 31442, 63002, 52973, 40687, 12674, 32538, 33552, 30224, 40345, 10436, 24821, 50417, 47839, 62478, 37337, 18230, 33532, 45803, 23903, 38849, 35630, 3627, 38659, 31402, 19608, 62399, 48530, 3753, 36802, 25329, 53769, 5365, 12726, 63463, 904, 7375, 62226, 451, 22133, 221, 63653, 62807, 42256, 50027, 21033, 36161, 3588, 46813, 37872, 35987, 986, 36660, 1202, 44719, 58405, 36560, 26745, 13657, 23196, 28188, 26293, 56759, 17684, 18406, 54165, 3998, 45305, 53890, 41361, 6359, 7405, 3328, 32031, 56429, 47514, 22217, 16040, 16167, 6175, 48735, 36290, 54622, 41591, 13457, 50097, 41033, 21848, 4299, 49897, 41964, 35484, 52596, 29367, 56402, 10443, 27805, 16583, 25625, 30523, 62152, 23240, 64471, 64466, 59924, 7174, 43059, 46756, 55581, 1999, 24458, 7400, 21940, 57965, 40574, 23153, 51189, 51073, 27884, 61911, 52357, 14291, 5207, 34548, 43078, 19790, 34009, 44402, 27855, 57427, 1081, 62896, 64235, 24699, 22668, 42119, 18484, 56684, 4080, 11400, 6986, 58352, 57121, 48421, 2320, 58727, 32763, 50307, 20600, 2464, 31682, 57633, 36149, 44016, 747, 47489, 44600, 29839, 61025, 48568, 8425, 31064, 53872, 11855, 49332, 10546, 21119, 11459, 54084, 42448, 324, 11798, 53552, 42757, 25887, 22761, 36103, 2156, 49624, 9194, 47341, 60071, 14493, 26676, 34587, 57408, 64326, 55415, 59744, 34885, 42007, 33864, 49781, 21178, 48073, 58192, 62091, 49217, 30950, 64026, 6972, 59068, 31061, 10621, 18316, 12150, 5498, 29100, 52325, 42576, 55699, 6835, 14422, 27324, 15251, 53763, 53195, 63126, 14229, 29628, 8018, 55615, 16097, 64658, 3592, 876, 8917, 20167, 13926, 57807, 17979, 55333, 14765, 20319, 29759, 42546, 41141, 22034, 49653, 44053, 40404, 7205, 13305, 46645, 14602, 15398, 3116, 15038, 6957, 56078, 31672, 19903, 4166, 4415, 38343, 10208, 34337, 40584, 17486, 42009, 27122, 31383, 6076, 50009, 8451, 12074}
+
+	want := EmptyIcon()
+	want.Pixels = []uint16{8108, 45978, 29796, 11198, 54082, 33680, 44334, 48880, 7424, 49426, 20106, 14995, 47031, 32867, 37236, 63842, 27882, 5879, 29025, 29042, 59499, 49479, 51016, 19575, 65025, 31087, 30878, 28647, 0, 49081, 41413, 19171, 30788, 59139, 20545, 3657, 2232, 58807, 28600, 27324, 48794, 4407, 51405, 30762, 58153, 29242, 35221, 62395, 39679, 23457, 60454, 51436, 51198, 28320, 35027, 32952, 33164, 36841, 19743, 24900, 6279, 11368, 56526, 9627, 15173, 43876, 8319, 35430, 60581, 20004, 16539, 56804, 6228, 38988, 44888, 54341, 60522, 61451, 57514, 16117, 61637, 5080, 40255, 56275, 6541, 15840, 39951, 19515, 43347, 54926, 60176, 54689, 23315, 26045, 61908, 96, 39393, 10423, 31333, 63521, 53293, 40762, 12191, 32451, 33485, 30091, 40413, 9909, 24580, 50686, 48056, 62987, 37345, 17858, 33465, 45980, 23644, 38887, 35604, 2964, 38694, 31557, 19620, 62928, 48891, 3574, 37022, 25410, 54193, 5206, 12655, 64004, 691, 7240, 62752, 232, 22176, 0, 64197, 63340, 42542, 50406, 21063, 36373, 3407, 47154, 38105, 36197, 774, 36878, 992, 45034, 58885, 36777, 26843, 13598, 23252, 28304, 26386, 57219, 17673, 18404, 54594, 3822, 45627, 54316, 41636, 6212, 7270, 3144, 32193, 56885, 47863, 22261, 16009, 16138, 6025, 49099, 36504, 55057, 41869, 13395, 50477, 41304, 21887, 4127, 50275, 42246, 35688, 53006, 29497, 56858, 10345, 27916, 16559, 25710, 30667, 62678, 23296, 65025, 65019, 60423, 7036, 43354, 47096, 56027, 1799, 24529, 7265, 21980, 58440, 40839, 23208, 51582, 51465, 27996, 62434, 52764, 14239, 5046, 34741, 43373, 19805, 34195, 44713, 27967, 57896, 870, 63431, 64786, 24773, 22717, 42403, 18483, 57144, 3905, 11313, 6846, 58832, 57586, 48781, 2124, 59030, 32787, 50519, 20493, 2162, 31694, 57924, 36209, 44161, 427, 47671, 44751, 29832, 61352, 48762, 8188, 31070, 54123, 11654, 49534, 10331, 21018, 11254, 54337, 42576, 0, 11597, 53799, 42888, 25837, 22677, 36163, 1851, 49829, 8965, 47522, 60388, 14321, 26635, 34631, 57697, 64689, 55682, 60058, 34932, 42130, 33900, 49988, 21077, 48261, 58489, 62430, 49418, 30954, 64386, 6719, 59374, 31067, 10407, 18185, 11953, 5229, 29085, 52559, 42705, 55969, 6580, 14249, 27290, 15087, 54012, 53438, 63476, 14054, 29618, 7776, 55884, 15942, 65025, 3303, 557, 8685, 20056, 13748, 58100, 17844, 55599, 14596, 20209, 29751, 42675, 41255, 21943, 49858, 44198, 40510, 6954, 13120, 46818, 14431, 15235, 2821, 14872, 6704, 56352, 31684, 19789, 3883, 4134, 38427, 9990, 34378, 40692, 17346, 42132, 27085, 31392, 5813, 50218, 8214, 11876}
+
+	testNormalize(src, want, t)
+}

image.go

@@ -0,0 +1,82 @@
+package images4
+
+import (
+	"image"
+	"image/color"
+	_ "image/gif"
+	"image/jpeg"
+	"image/png"
+	"log"
+	"os"
+)
+
+// Open opens and decodes an image file for a given path.
+func Open(path string) (img image.Image, err error) {
+	file, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer file.Close()
+	img, _, err = image.Decode(file)
+	if err != nil {
+		return nil, err
+	}
+	return img, err
+}
+
+// resizeByNearest resizes an image to the destination size
+// with the nearest neighbour method. It also returns the source
+// image size.
+func resizeByNearest(
+	src image.Image, dstSize image.Point) (
+	dst image.RGBA, srcSize image.Point) {
+	// Original image size.
+	xMax, xMin := src.Bounds().Max.X, src.Bounds().Min.X
+	yMax, yMin := src.Bounds().Max.Y, src.Bounds().Min.Y
+	srcX := xMax - xMin
+	srcY := yMax - yMin
+	xScale := float64(srcX) / float64(dstSize.X)
+	yScale := float64(srcY) / float64(dstSize.Y)
+
+	// Destination rectangle.
+	outRect := image.Rectangle{
+		image.Point{0, 0}, image.Point{dstSize.X, dstSize.Y}}
+	// Color model of uint8 per color.
+	dst = *image.NewRGBA(outRect)
+	var (
+		r, g, b, a uint32
+	)
+	for y := 0; y < dstSize.Y; y++ {
+		for x := 0; x < dstSize.X; x++ {
+			r, g, b, a = src.At(
+				int(float64(x)*xScale+float64(xMin)),
+				int(float64(y)*yScale+float64(yMin))).RGBA()
+			dst.Set(x, y, color.RGBA{
+				uint8(r >> 8),
+				uint8(g >> 8),
+				uint8(b >> 8),
+				uint8(a >> 8)})
+		}
+	}
+	return dst, image.Point{srcX, srcY}
+}
+
+// SaveToPNG encodes and saves image.RGBA to a file.
+func SaveToPNG(img *image.RGBA, path string) {
+	if destFile, err := os.Create(path); err != nil {
+		log.Println("Cannot create file: ", path, err)
+	} else {
+		defer destFile.Close()
+		png.Encode(destFile, img)
+	}
+}
+
+// SaveToJPG encodes and saves image.RGBA to a file.
+func SaveToJPG(img *image.RGBA, path string, quality int) {
+	if destFile, err := os.Create(path); err != nil {
+		log.Println("Cannot create file: ", path, err)
+	} else {
+		defer destFile.Close()
+		jpeg.Encode(destFile, img, &jpeg.Options{Quality: quality})
+	}
+}

image_test.go

@@ -0,0 +1,49 @@
+package images4
+
+import (
+	"image"
+	"path"
+	"reflect"
+	"testing"
+)
+
+const (
+	testDir1 = "testdata"
+	testDir2 = "resample"
+)
+
+func TestResizeByNearest(t *testing.T) {
+	testDir := path.Join(testDir1, testDir2)
+	tables := []struct {
+		inFile     string
+		srcX, srcY int
+		outFile    string
+		dstX, dstY int
+	}{
+		{"original.png", 533, 400,
+			"nearest100x100.png", 100, 100},
+		{"nearest100x100.png", 100, 100,
+			"nearest533x400.png", 533, 400},
+	}
+
+	for _, table := range tables {
+		inImg, err := Open(path.Join(testDir, table.inFile))
+		if err != nil {
+			t.Error("Cannot decode", path.Join(testDir, table.inFile))
+		}
+		outImg, err := Open(path.Join(testDir, table.outFile))
+		if err != nil {
+			t.Error("Cannot decode", path.Join(testDir, table.outFile))
+		}
+		resampled, srcSize := resizeByNearest(inImg,
+			image.Point{table.dstX, table.dstY})
+		if !reflect.DeepEqual(
+			outImg.(*image.RGBA), &resampled) ||
+			table.srcX != srcSize.X ||
+			table.srcY != srcSize.Y {
+			t.Errorf(
+				"Resample data do not match for %s and %s.",
+				table.inFile, table.outFile)
+		}
+	}
+}

similarity.go

@@ -0,0 +1,91 @@
+package images4
+
+// Similar returns similarity verdict based on Euclidean
+// and proportion similarity.
+func Similar(iconA, iconB IconT) bool {
+
+	if !propSimilar(iconA, iconB) {
+		return false
+	}
+	if !eucSimilar(iconA, iconB) {
+		return false
+	}
+	return true
+}
+
+// propSimilar gives a similarity verdict for image A and B based on
+// their height and width. When proportions are similar, it returns
+// true.
+func propSimilar(iconA, iconB IconT) bool {
+	return PropMetric(iconA, iconB) < thProp
+}
+
+// PropMetric gives image proportion similarity metric for image A
+// and B. The smaller the metric the more similar are images by their
+// x-y size.
+func PropMetric(iconA, iconB IconT) (m float64) {
+
+	// Filtering is based on rescaling a narrower side of images to 1,
+	// then cutting off at threshold of a longer image vs shorter image.
+	xA, yA := float64(iconA.ImgSize.X), float64(iconA.ImgSize.Y)
+	xB, yB := float64(iconB.ImgSize.X), float64(iconB.ImgSize.Y)
+
+	if xA <= yA { // x to 1.
+		yA = yA / xA
+		yB = yB / xB
+		if yA > yB {
+			m = (yA - yB) / yA
+		} else {
+			m = (yB - yA) / yB
+		}
+	} else { // y to 1.
+		xA = xA / yA
+		xB = xB / yB
+		if xA > xB {
+			m = (xA - xB) / xA
+		} else {
+			m = (xB - xA) / xB
+		}
+	}
+	return m
+}
+
+// eucSimilar gives a similarity verdict for image A and B based
+// on Euclidean distance between pixel values of their icons.
+// When the distance is small, the function returns true.
+// iconA and iconB are generated with the Icon function.
+// eucSimilar wraps EucMetric with well-tested thresholds.
+func eucSimilar(iconA, iconB IconT) bool {
+
+	m1, m2, m3 := EucMetric(iconA, iconB)
+
+	return m1 < thY && // Luma as most sensitive.
+		m2 < thCbCr &&
+		m3 < thCbCr
+}
+
+// EucMetric returns Euclidean distances between 2 icons.
+// These are 3 metrics corresponding to each color channel.
+// Distances are squared, not to waste CPU on square root calculations.
+// Note: color channels of icons are YCbCr (not RGB).
+func EucMetric(iconA, iconB IconT) (m1, m2, m3 float64) {
+
+	var cA, cB uint16
+	for i := 0; i < numPix; i++ {
+		// Channel 1.
+		cA = iconA.Pixels[i]
+		cB = iconB.Pixels[i]
+		m1 += ((float64(cA) - float64(cB)) * one255th2 * (float64(cA) - float64(cB)))
+		// Channel 2.
+		cA = iconA.Pixels[i+numPix]
+		cB = iconB.Pixels[i+numPix]
+		m2 += ((float64(cA) - float64(cB)) * one255th2 * (float64(cA) - float64(cB)))
+		// Channel 3.
+		cA = iconA.Pixels[i+2*numPix]
+		cB = iconB.Pixels[i+2*numPix]
+		m3 += ((float64(cA) - float64(cB)) * one255th2 * (float64(cA) - float64(cB)))
+
+	}
+
+	return m1, m2, m3
+}

similarity_test.go

@@ -0,0 +1,83 @@
+package images4
+
+import (
+	"path"
+	"testing"
+)
+
+func testPropSimilar(fA, fB string, isSimilar bool,
+	t *testing.T) {
+	p := path.Join("testdata", "proportions")
+	imgA, err := Open(path.Join(p, fA))
+	if err != nil {
+		t.Error("Error opening image:", err)
+	}
+	imgB, err := Open(path.Join(p, fB))
+	if err != nil {
+		t.Error("Error opening image:", err)
+	}
+	iconA := Icon(imgA)
+	iconB := Icon(imgB)
+
+	if isSimilar == true {
+		if !propSimilar(iconA, iconB) {
+			t.Errorf("Expecting similarity of %v to %v.", fA, fB)
+		}
+	}
+	if isSimilar == false {
+		if propSimilar(iconA, iconB) {
+			t.Errorf("Expecting non-similarity of %v to %v.", fA, fB)
+		}
+	}
+}
+
+func TestPropSimilar(t *testing.T) {
+	testPropSimilar("100x130.png", "100x124.png", true, t)
+	testPropSimilar("100x130.png", "100x122.png", false, t)
+	testPropSimilar("130x100.png", "260x200.png", true, t)
+	testPropSimilar("200x200.png", "260x200.png", false, t)
+	testPropSimilar("130x100.png", "124x100.png", true, t)
+	testPropSimilar("130x100.png", "122x100.png", false, t)
+	testPropSimilar("130x100.png", "130x100.png", true, t)
+	testPropSimilar("100x130.png", "130x100.png", false, t)
+	testPropSimilar("124x100.png", "260x200.png", true, t)
+	testPropSimilar("122x100.png", "260x200.png", false, t)
+	testPropSimilar("100x124.png", "100x130.png", true, t)
+}
+
+func testEucSimilar(fA, fB string, isSimilar bool,
+	t *testing.T) {
+	p := path.Join("testdata", "euclidean")
+	imgA, err := Open(path.Join(p, fA))
+	if err != nil {
+		t.Error("Error opening image:", err)
+	}
+	iconA := Icon(imgA)
+	imgB, err := Open(path.Join(p, fB))
+	if err != nil {
+		t.Error("Error opening image:", err)
+	}
+	iconB := Icon(imgB)
+	if isSimilar == true {
+		if !eucSimilar(iconA, iconB) {
+			t.Errorf("Expecting similarity of %v to %v.", fA, fB)
+		}
+	}
+	if isSimilar == false {
+		if eucSimilar(iconA, iconB) {
+			t.Errorf("Expecting non-similarity of %v to %v.", fA, fB)
+		}
+	}
+}
+
+func TestEucSimilar(t *testing.T) {
+	testEucSimilar("large.jpg", "distorted.jpg", true, t)
+	testEucSimilar("large.jpg", "flipped.jpg", false, t)
+	testEucSimilar("large.jpg", "small.jpg", true, t)
+	testEucSimilar("small.gif", "small.jpg", true, t) // GIF test.
+	testEucSimilar("uniform-black.png", "uniform-black.png", true, t)
+	testEucSimilar("uniform-black.png", "uniform-white.png", false, t)
+	testEucSimilar("uniform-green.png", "uniform-green.png", true, t)
+	testEucSimilar("uniform-green.png", "uniform-white.png", false, t)
+	testEucSimilar("uniform-white.png", "uniform-white.png", true, t)
+}