phamilie 0.1.0

data/README.md

@@ -0,0 +1,56 @@
+[![Gem Version](https://img.shields.io/gem/v/phamilie.svg?style=flat)](https://rubygems.org/gems/phamilie)
+[![Build Status](https://img.shields.io/travis/toy/phamilie/master.svg?style=flat)](https://travis-ci.org/toy/phamilie)
+
+# Phamilie
+
+Originally forked from [deepfryed/similie](https://github.com/deepfryed/similie).
+
+Phamilie is a simple DCT based image hashing interface that,
+
+* computes a fingerprint based on low frequencies of an image.
+* computes hamming distance between 2 fingerprints.
+
+## Example
+
+```ruby
+require 'phamilie'
+
+phamilie = Phamilie.new
+
+lena1 = 'spec/lena1.png'
+lena2 = 'spec/lena2.png' # lena1.png cropped and scaled
+lena5 = 'spec/lena5.png' # a different image
+lena6 = 'spec/lena6.png' # lena2.png rotated and scaled
+
+phamilie.fingerprint(lena1) #=> 36170087496991428
+
+phamilie.distance(lena1, lena2) #=> 2
+phamilie.distance(lena1, lena5) #=> 12
+
+phamilie.distance(lena1, lena6) #=> 19
+phamilie.distance(lena2, lena6) #=> 19
+phamilie.distance(lena5, lena6) #=> 23
+phamilie.distance_with_rotations(lena1, lena6) #=> 2
+phamilie.distance_with_rotations(lena2, lena6) #=> 0
+phamilie.distance_with_rotations(lena5, lena6) #=> 12
+```
+
+## Caching
+
+By default a Hash is used to cache fingerprints by path. Be carefull if images or current directory can change in process.
+
+As cache you can use an instance of class responding to `[]` and `[]=`.
+
+If using persistant cache take into account file size and mtime or even cryptographic hash of contents.
+
+## Dependencies
+
+* ruby 1.9.1+
+* CImg
+* libpng if you need to read png images
+* libjpeg if you need to read jpeg images
+* ImageMagick if you need to read other images
+
+# License
+
+GPL — using code from pHash library

data/ext/phamilie/.gitignore

@@ -0,0 +1 @@
+/extconf.h

data/ext/phamilie/extconf.rb

@@ -0,0 +1,12 @@
+require 'mkmf'
+
+if have_header 'png.h'
+  $LDFLAGS << ' -lpng'
+end
+
+if have_header 'jpeglib.h'
+  $LDFLAGS << ' -ljpeg'
+end
+
+create_header
+create_makefile 'phamilie/fingerprint'

data/ext/phamilie/fingerprint.cpp

@@ -0,0 +1,239 @@
+/*
+  Original similie gem
+  (c) Bharanee Rathna 2011
+
+  CC BY-SA 3.0
+  http://creativecommons.org/licenses/by-sa/3.0/
+
+  Free for every type of use. The author cannot be legally held responsible for
+  any damages resulting from the use of this work. All modifications or derivatives
+  need to be attributed.
+*/
+/*
+  Original pHash library (ph_dct_matrix and ph_dct_imagehash functions)
+
+  pHash, the open source perceptual hash library
+  Copyright (C) 2009 Aetilius, Inc.
+  All rights reserved.
+
+  This program is free software: you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation, either version 3 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+  Evan Klinger - eklinger@phash.org
+  D Grant Starkweather - dstarkweather@phash.org
+*/
+/*
+  Reworking, adaptation, fixes
+  (c) Ivan Kuchin 2013
+*/
+
+#include <ruby.h>
+#include <ruby/encoding.h>
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+#include <unistd.h>
+
+#include "extconf.h"
+#define cimg_display 0
+#define cimg_verbosity 0
+
+#ifdef HAVE_PNG_H
+#define cimg_use_png
+#endif
+
+#ifdef HAVE_JPEGLIB_H
+#define cimg_use_jpeg
+#endif
+
+#include "CImg.h"
+using namespace cimg_library;
+
+#define TO_S(v)    rb_funcall(v, rb_intern("to_s"), 0)
+#define CSTRING(v) RSTRING_PTR(TO_S(v))
+
+#undef SIZET2NUM
+#undef NUM2SIZET
+
+#ifdef HAVE_LONG_LONG
+  #define SIZET2NUM(x) ULL2NUM(x)
+  #define NUM2SIZET(x) NUM2ULL(x)
+#else
+  #define SIZET2NUM(x) ULONG2NUM(x)
+  #define NUM2SIZET(x) NUM2ULONG(x)
+#endif
+
+#define DCT_SIZE 32
+
+#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
+#define popcount __builtin_popcountll
+#else
+// http://en.wikipedia.org/wiki/Hamming_weight
+
+const uint64_t m1  = 0x5555555555555555; //binary: 0101...
+const uint64_t m2  = 0x3333333333333333; //binary: 00110011..
+const uint64_t m4  = 0x0f0f0f0f0f0f0f0f; //binary:  4 zeros,  4 ones ...
+const uint64_t h01 = 0x0101010101010101; //the sum of 256 to the power of 0,1,2,3...
+
+int popcount(uint64_t x) {
+  x -= (x >> 1) & m1;             //put count of each 2 bits into those 2 bits
+  x = (x & m2) + ((x >> 2) & m2); //put count of each 4 bits into those 4 bits
+  x = (x + (x >> 4)) & m4;        //put count of each 8 bits into those 8 bits
+  return (x * h01)>>56;           //returns left 8 bits of x + (x<<8) + (x<<16) + (x<<24) + ...
+}
+#endif
+
+CImg<float>* ph_dct_matrix(const int N) {
+  CImg<float> *ptr_matrix = new CImg<float>(N, N, 1, 1, 1 / sqrt((float) N));
+  const float c1 = sqrt(2.0 / N);
+  for (int x = 0; x < N; x++){
+    for (int y = 1; y < N; y++){
+      *ptr_matrix->data(x, y) = c1 * cos((cimg::PI / 2 / N) * y * (2 * x + 1));
+    }
+  }
+  return ptr_matrix;
+}
+
+void small_mono_image(CImg<uint8_t> &img, CImg<float> &small) {
+  CImg<float> meanfilter(7, 7, 1, 1, 1);
+  if (img.spectrum() == 3){
+    small = img.RGBtoYCbCr().channel(0).get_convolve(meanfilter);
+  } else if (img.spectrum() == 4){
+    int width = img.width();
+    int height = img.height();
+    small = img.crop(0, 0, 0, 0, width - 1, height - 1, 0, 2).RGBtoYCbCr().channel(0).get_convolve(meanfilter);
+  } else {
+    small = img.channel(0).get_convolve(meanfilter);
+  }
+  small.resize(DCT_SIZE, DCT_SIZE, -100, -100, 2);
+}
+
+uint64_t small_mono_image_fingerprint(CImg<float> &small) {
+  uint64_t hash;
+
+  CImg<float> *C  = ph_dct_matrix(DCT_SIZE);
+  CImg<float> Ctransp = C->get_transpose();
+  CImg<float> dctImage = (*C) * small * Ctransp;
+  CImg<float> subsec = dctImage.crop(1, 1, 8, 8).unroll('x');
+
+  float median = subsec.median();
+  uint64_t one = 0x0000000000000001;
+  hash = 0x0000000000000000;
+  for (int i = 0; i < 64; i++){
+    float current = subsec(i);
+    if (current > median)
+      hash |= one;
+    one = one << 1;
+  }
+
+  delete C;
+
+  return hash;
+}
+
+uint64_t image_fingerprint(CImg<uint8_t> &image) {
+  CImg<float> small;
+
+  small_mono_image(image, small);
+
+  return small_mono_image_fingerprint(small);
+}
+
+void image_rotation_fingerprints(CImg<uint8_t> &image, uint64_t* phashs) {
+  static int a = 0;
+
+  CImg<float> small;
+
+  small_mono_image(image, small);
+
+  phashs[0] = small_mono_image_fingerprint(small);
+
+  small.mirror('x');
+  phashs[1] = small_mono_image_fingerprint(small);
+
+  small.mirror('y');
+  phashs[2] = small_mono_image_fingerprint(small);
+
+  small.mirror('x');
+  phashs[3] = small_mono_image_fingerprint(small);
+
+  small.transpose();
+  phashs[4] = small_mono_image_fingerprint(small);
+
+  small.mirror('x');
+  phashs[5] = small_mono_image_fingerprint(small);
+
+  small.mirror('y');
+  phashs[6] = small_mono_image_fingerprint(small);
+
+  small.mirror('x');
+  phashs[7] = small_mono_image_fingerprint(small);
+}
+
+VALUE rb_image_fingerprint_func(VALUE self, VALUE file) {
+  CImg<uint8_t> img;
+  try {
+    img.load(CSTRING(file));
+  } catch (CImgIOException ex){
+    rb_raise(rb_eArgError, "Invalid image or unsupported format: %s", CSTRING(file));
+  }
+
+  uint64_t phash = image_fingerprint(img);
+
+  return SIZET2NUM(phash);
+}
+
+VALUE rb_image_rotation_fingerprints_func(VALUE self, VALUE file) {
+  CImg<uint8_t> img;
+  try {
+    img.load(CSTRING(file));
+  } catch (CImgIOException ex){
+    rb_raise(rb_eArgError, "Invalid image or unsupported format: %s", CSTRING(file));
+  }
+
+  uint64_t phashs[8] = {};
+  image_rotation_fingerprints(img, phashs);
+
+  VALUE rotations = rb_ary_new();
+
+  for (int i = 0; i < 8; i++) {
+    rb_ary_push(rotations, SIZET2NUM(phashs[i]));
+  }
+
+  return rotations;
+}
+
+VALUE rb_fingerprint_distance_func(VALUE self, VALUE fingerprint1, VALUE fingerprint2) {
+  if (TYPE(fingerprint1) != T_BIGNUM && TYPE(fingerprint1) != T_FIXNUM)
+    rb_raise(rb_eArgError, "fingerprint1 needs to be a number");
+
+  if (TYPE(fingerprint2) != T_BIGNUM && TYPE(fingerprint2) != T_FIXNUM)
+    rb_raise(rb_eArgError, "fingerprint2 needs to be a number");
+
+  int dist = popcount(NUM2SIZET(fingerprint1) ^ NUM2SIZET(fingerprint2));
+
+  return INT2NUM(dist);
+}
+
+extern "C" {
+  void Init_fingerprint() {
+    VALUE cPhamilie = rb_define_class("Phamilie", rb_cObject);
+    VALUE mFingerprint = rb_define_module_under(cPhamilie, "Fingerprint");
+
+    rb_define_singleton_method(mFingerprint, "fingerprint", RUBY_METHOD_FUNC(rb_image_fingerprint_func),            1);
+    rb_define_singleton_method(mFingerprint, "rotations",   RUBY_METHOD_FUNC(rb_image_rotation_fingerprints_func),  1);
+    rb_define_singleton_method(mFingerprint, "distance",    RUBY_METHOD_FUNC(rb_fingerprint_distance_func),         2);
+  }
+}

data/lib/phamilie.rb

@@ -0,0 +1,62 @@
+class Phamilie
+  def initialize(cache = {})
+    {:[] => 1, :[]= => 2}.each do |method, desired_arity|
+      unless cache.respond_to?(method)
+        raise ArgumentError.new("#{cache} does not respond to #{method}")
+      end
+
+      arity = cache.method(method).arity
+      unless arity == desired_arity
+        raise ArgumentError.new("#{cache} method #{method} arity should be #{desired_arity} instead of #{arity}")
+      end
+    end
+
+    @cache = cache
+  end
+
+  def fingerprint(path)
+    case cached = @cache[path]
+    when Array
+      cached[0]
+    when Integer
+      cached
+    when nil
+      @cache[path] = Fingerprint.fingerprint(path)
+    else
+      raise "Cache for #{path} contains non fingerprint #{cached}"
+    end
+  end
+
+  def rotations(path)
+    case cached = @cache[path]
+    when Array
+      cached
+    when Integer, nil
+      @cache[path] = Fingerprint.rotations(path)
+    else
+      raise "Cache for #{path} contains non fingerprint #{cached}"
+    end
+  end
+
+  def distance(path_a, path_b)
+    Fingerprint.distance(fingerprint(path_a), fingerprint(path_b))
+  end
+
+  def distance_with_rotations(path_a, path_b)
+    if @cache[path_a].is_a?(Array) || @cache[path_b].is_a?(Integer)
+      path_a, path_b = path_b, path_a
+    end
+
+    fingerprint_a = if @cache[path_a].is_a?(Integer)
+      fingerprint(path_a)
+    else
+      rotations(path_a)[0]
+    end
+
+    rotations(path_b).map do |rotation_b|
+      Fingerprint.distance(fingerprint_a, rotation_b)
+    end.min
+  end
+end
+
+require 'phamilie/fingerprint.so'

data/phamilie.gemspec

@@ -0,0 +1,16 @@
+Gem::Specification.new do |s|
+  s.name              = 'phamilie'
+  s.version           = '0.1.0'
+  s.authors           = ['Bharanee Rathna', 'Ivan Kuchin']
+  s.summary           = 'compute image fingerprints and similarity'
+  s.description       = 'phamilie is an image fingerprinting & comparison utility'
+  s.homepage          = 'http://github.com/toy/phamilie'
+  s.license           = 'GPL'
+  s.files             = `git ls-files`.split("\n")
+  s.test_files        = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables       = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.extensions        = `git ls-files -- ext/**/extconf.rb`.split("\n")
+  s.require_paths     = %w[lib]
+
+  s.add_development_dependency 'rspec'
+end

data/spec/build_rotations

@@ -0,0 +1,9 @@
+#!/bin/sh
+
+convert rotation0.png -flop       rotation1.png
+convert rotation0.png -rotate 180 rotation2.png
+convert rotation0.png -flip       rotation3.png
+convert rotation0.png -transpose  rotation4.png
+convert rotation0.png -rotate 270 rotation5.png
+convert rotation0.png -transverse rotation6.png
+convert rotation0.png -rotate 90  rotation7.png

data/spec/phamilie_spec.rb

@@ -0,0 +1,134 @@
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+$:.unshift File.join(File.dirname(__FILE__), '..', 'ext')
+require 'rspec'
+require 'phamilie'
+require 'pathname'
+
+describe 'Phamilie fingerprinting' do
+  DIR = Pathname(__FILE__).dirname
+
+  it 'should fingerprint image' do
+    expect(Phamilie.new.fingerprint(DIR + 'lena1.png')).not_to be(nil)
+  end
+
+  it 'should barf on invalid path' do
+    expect{ Phamilie.new.fingerprint(DIR + 'foo') }.to raise_error(ArgumentError)
+  end
+
+  it 'should barf on non image' do
+    expect{ Phamilie.new.fingerprint(__FILE__) }.to raise_error(ArgumentError)
+  end
+
+  LENA1_FINGERPRINT = 11112265815244395537
+
+  it 'should fingerprint image' do
+    fingerprint = Phamilie.new.fingerprint(DIR + 'lena1.png')
+    expect(fingerprint).to eq(LENA1_FINGERPRINT)
+  end
+
+  it 'should fingerprint image rotations' do
+    rotations = Phamilie.new.rotations(DIR + 'lena1.png')
+    expect(rotations[0]).to eq(LENA1_FINGERPRINT)
+  end
+end
+
+describe 'Phamilie image distance' do
+  it 'should work for similar images' do
+    phamilie = Phamilie.new
+    images = (1..5).map{ |n| DIR + 'lena%d.png' % n }
+    images.unshift nil
+
+    expect(phamilie.distance(images[1], images[2])).to eq(0)
+    expect(phamilie.distance(images[2], images[3])).to eq(26)
+    expect(phamilie.distance(images[3], images[4])).to eq(26)
+    expect(phamilie.distance(images[1], images[4])).to eq(2)
+    expect(phamilie.distance(images[1], images[5])).to eq(32)
+  end
+end
+
+describe 'Phamilie caching' do
+  it 'should use cache' do
+    phamilie = Phamilie.new
+
+    images = (1..5).map{ |n| DIR + 'lena%d.png' % n }
+
+    images.each do |image|
+      expect(Phamilie::Fingerprint).to receive(:fingerprint).once.with(image).and_return(image.__id__)
+    end
+
+    images.permutation(2) do |a, b|
+      phamilie.distance(a, b)
+    end
+  end
+end
+
+describe 'Phamilie image reoriented distance' do
+  it 'should work for identical but rotated images' do
+    phamilie = Phamilie.new
+
+    images = (0..7).map{ |n| DIR + 'rotation%d.png' % n }
+
+    images.permutation(2) do |a, b|
+      expect(phamilie.distance(a, b)).not_to eq(0)
+      expect(phamilie.distance_with_rotations(a, b)).to eq(0)
+    end
+  end
+end
+
+describe 'Phamilie caching with rotations' do
+  it 'should use cache' do
+    phamilie = Phamilie.new
+
+    images = (1..5).map{ |n| DIR + 'lena%d.png' % n }
+
+    expect(Phamilie::Fingerprint).to receive(:fingerprint).exactly(images.length).times.and_return(0)
+    expect(Phamilie::Fingerprint).to receive(:rotations).exactly(images.length - 1).times.and_return(8.times.to_a)
+
+    images.permutation(2) do |a, b|
+      phamilie.distance(a, b)
+    end
+
+    images.permutation(2) do |a, b|
+      phamilie.distance_with_rotations(a, b)
+    end
+
+    images.permutation(2) do |a, b|
+      phamilie.distance(a, b)
+    end
+  end
+
+  it 'should calculate rotation fingerprints only when required' do
+    phamilie = Phamilie.new
+
+    images = (1..2).map{ |n| DIR + 'lena%d.png' % n }
+
+    expect(Phamilie::Fingerprint).to receive(:fingerprint).once.with(images[0]).and_return(0)
+    expect(Phamilie::Fingerprint).to receive(:rotations).once.with(images[0]).and_return(8.times.to_a)
+
+    expect(Phamilie::Fingerprint).to receive(:fingerprint).once.with(images[1]).and_return(0)
+    expect(Phamilie::Fingerprint).not_to receive(:rotations).with(images[1])
+
+    phamilie.distance(images[0], images[1])
+    phamilie.distance(images[1], images[0])
+    phamilie.distance_with_rotations(images[0], images[1])
+    phamilie.distance_with_rotations(images[1], images[0])
+  end
+
+  it 'should calculate rotation fingerprints when it should be more effective' do
+    phamilie = Phamilie.new
+
+    images = (1..2).map{ |n| DIR + 'lena%d.png' % n }
+
+    expect(Phamilie::Fingerprint).not_to receive(:fingerprint).with(images[0])
+    expect(Phamilie::Fingerprint).to receive(:rotations).once.with(images[0]).and_return(8.times.to_a)
+
+    expect(Phamilie::Fingerprint).not_to receive(:fingerprint).with(images[0])
+    expect(Phamilie::Fingerprint).to receive(:rotations).with(images[1]).and_return(8.times.to_a)
+
+    phamilie.distance_with_rotations(images[0], images[1])
+    phamilie.distance_with_rotations(images[1], images[0])
+    phamilie.distance(images[0], images[1])
+    phamilie.distance(images[1], images[0])
+  end
+
+end