dhash-vips 0.1.0.1 → 0.1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 465577547953c3039cdea1665f7010ed0af57656
-  data.tar.gz: 9bb9a40feba3b039d0c0ee12f94907dd9b23fa68
+  metadata.gz: 2b90b4abcd617f0e285dd3399338b4114d921624
+  data.tar.gz: d47a8e51a8e7a2bf28b60d0259dc350f8b5e4fa0
 SHA512:
-  metadata.gz: 5936ffe730fb274a719d812dde7dab4113c5002d3c7acaad3c58bb12ed8d1da5744f7afa9d73e728ad7b54ee14f5f1f300bf021d98eab64ed08fefbeeb5034e2
-  data.tar.gz: 19d272fa20c2f954f111561537328f677fbb32a84836e4d03d605f1086c3694b27647390b9420b36ce4fe56c7ddd8537f247729464202a0ba8a968813670237e
+  metadata.gz: 3b8b2ce65f3bdfd90d03e3a069e30c61be4a9bf1fc40f9d4beace8216165383d7f54572e996e101ab9fd6f056b260676a9ed465b8860bd1a6e17a4228b859909
+  data.tar.gz: 2ea40198fa4c6ed05183d610b2ca558a6ad67a386e69c127dbc0afac5723686025bd4644cc7297c300d9173b212788cc1ab4f242ad849ed7ee50dbc462dd5f08

data/README.md

@@ -1,4 +1,4 @@
-[![Gem Version](https://badge.fury.io/rb/dhash-vips.svg)](http://badge.fury.io/rb/dhash-vips)
+[![Gem Version](https://badge.fury.io/rb/dhash-vips.svg)](http://badge.fury.io/rb/dhash-vips) [![Docker Image](https://github.com/nakilon/dhash-vips/workflows/Docker%20Image/badge.svg)](https://hub.docker.com/repository/docker/nakilonishe/dhash-vips/general)
 
 # dHash and IDHash gem powered by ruby-vips
 
@@ -7,28 +7,16 @@ The **IDHash** is the new algorithm that has some improvements over dHash -- I'l
 
 You can read about the dHash and perceptual hashing in the article ["Kind of Like That" at "The Hacker Factor Blog"](http://www.hackerfactor.com/blog/index.php?/archives/529-Kind-of-Like-That.html) (21 January 2013). The idea is that you resize the otiginal image to 8x9 and then convert it to 8x8 array of bits -- each tells if the corresponding segment of the image is brighter or darker than the one on the right (or left). Then you apply the [Hamming distance](https://en.wikipedia.org/wiki/Hamming_distance) to such arrays to measure how much they are different.
 
-There were several Ruby implementations on Github already but they all depended on ImageMagick. My implementation takes an advantage of speed of the libvips (the `ruby-vips` gem) -- it fingerprints images much faster:
-
-    load the image and calculate the fingerprint:
-                              user     system      total        real
-    Dhash                 6.191731   0.230885   6.422616 (  6.428763)
-    DHashVips::DHash      0.858045   0.144820   1.002865 (  0.924308)
-
-`Dhash` here is [another gem](https://github.com/maccman/dhash) that I used earlier in my projects before I decided to make this one.  
-Unfortunately both gems made slightly different fingerprints for two image files that are supposed to have the same fingerprint because from the human point of view they are the same (photo by Jordan Voth):  
-![](https://storage.googleapis.com/dhash-vips.nakilon.pro/dhash_issue_example.png)  
-The distance here appeared to be equal to 5. This is why I've decided to improve the algorithm and this is how the "IDHash" appeared.
+There were several Ruby implementations on Github already but they all depended on ImageMagick. My implementation takes an advantage of speed of the libvips (the `ruby-vips` gem) -- it fingerprints images much faster. For even more speed the fingerprint comparison function is made as native C extension.
 
 ## IDHash (the Important Difference Hash)
 
-The main improvement over the dHash is what makes it insensitive to the resizing algorithm, color scheme and effectively made the pair of images above to have a distance of 0.
+The main improvement over the dHash is what makes it insensitive to the resizing algorithm and possible errors due to color scheme conversion.
 
 * The "Importance" is an array of extra 64 bits that tells the comparing function which half of 64 bits is important (when the difference between neighbors was enough significant) and which is not. So not every bit in a fingerprint is being compared but only half of them.  
 * It subtracts not only horizontally but also vertically -- that adds 128 more bits.  
 * Instead of resizing to 8x9 it resizes to 8x8 and puts the image on a torus so it subtracts the very left column from the very right one and the top from the bottom.
 
-You could see in fingerprint calculation benchmark earlier that these improvements didn't make it slower than dHash because most of the time is spent on image resizing. Distance measurement is what became slower.
-
 ### Example
 
 Here are two photos (by Brian Lauer):  
@@ -49,6 +37,8 @@ Here in each of 64 cells, there are two circles that color the difference betwee
   * [Finding the closest pair between two sets of points on the hypercube](https://cstheory.stackexchange.com/q/16322/27420)  
   * [Would PCA work for boolean data types?](https://stats.stackexchange.com/q/159705/1125)  
   * [Using pHash to search agaist a huge image database, what is the best approach?](https://stackoverflow.com/q/18257641/322020)  
+  * [How do I speed up this BIT_COUNT query for hamming distance?](https://stackoverflow.com/q/35065675/322020)  
+  * [Hamming distance on binary strings in SQL](https://stackoverflow.com/q/4777070/322020)
 
 ## Installation
 
@@ -101,19 +91,23 @@ end
 
 ### Notes and benchmarks
 
-* The above `15` and `25` constants are found empirically and just work enough well for 8-byte hashes. To find these tresholds we can run a rake task with hardcoded test cases (pairs of photos from the same photosession are not the same but are considered to be enough 'similar' for the purpose of this benchmark):
+* The above `15` and `25` constants are found empirically and just work enough well for 8-byte hashes. To find these thresholds we can run a rake task with hardcoded test cases (pairs of photos from the same photosession are not the same but are considered to be enough 'similar' for the purpose of this benchmark):
 
+      $ vips -v
+      vips-8.9.2-Tue Apr 21 09:26:11 UTC 2020
+      $ identify -version | head -1
+      Version: ImageMagick 6.9.11-24 Q16 x86_64 2020-07-18 https://imagemagick.org
       $ rake compare_quality
 
-                            Dhash  Phamilie  DHashVips::DHash  DHashVips::IDHash  DHashVips::IDHash(4) 
-          The same image:    0..0      0..0              0..0               0..0                  0..0 
-      'Jordan Voth case':       4         2                 4                  0                     0 
-          Similar images:   1..17    14..34             2..23              6..22               53..166 
-        Different images:   9..57    22..42             9..50             18..65              120..233 
-                1/FMI^2 =    1.25       4.0             1.556               1.25                 1.306 
-                 FP, FN =  [2, 0]    [0, 6]            [1, 2]             [2, 0]                [1, 1] 
+                            Dhash  Phamilie  DHashVips::DHash  DHashVips::IDHash  DHashVips::IDHash(4)
+          The same image:    0..0      0..0              0..0               0..0                  0..0
+      'Jordan Voth case':       2         2                 4                  0                     0
+          Similar images:   1..15    14..34             2..23              6..22               53..166
+        Different images:  10..54    22..42            10..50             17..65              120..233
+                1/FMI^2 =   1.375       4.0             1.556               1.25                 1.306
+                 FP, FN =  [3, 0]    [0, 6]            [1, 2]             [2, 0]                [1, 1]
 
-    The `FMI` line here is the "quality of algorithm", i.e. the best achievable function from the ["Fowlkes–Mallows index"](https://en.wikipedia.org/wiki/Fowlkes%E2%80%93Mallows_index) value if you take the "similar" and "different" test pairs and try to draw the treshold line. Smaller number is better. Here I've added the [`phamilie` gem](https://github.com/toy/phamilie) that is DCT based (not a kind of dhash). The last line shows number of false positives (`FP`) and false negatives (`FN`) in case of the best achieved FMI.
+    The `FMI` line here is the "quality of algorithm", i.e. the best achievable function from the ["Fowlkes–Mallows index"](https://en.wikipedia.org/wiki/Fowlkes%E2%80%93Mallows_index) value if you take the "similar" and "different" test pairs and try to draw the threshold line. Smaller number is better. The last line shows number of false positives (`FP`) and false negatives (`FN`) in case of the best achieved FMI. Here I've added the [`phamilie` gem](https://github.com/toy/phamilie) that is DCT based (not a kind of dhash).
 
 * Methods were renamed from `#calculate` to `#fingerprint` and from `#hamming` to `#distance`.  
 * The `DHash#calculate` accepts `hash_size` optional parameter that is 8 by default. The `IDHash#fingerprint`'s optional parameter is called `power` and works in a bit different way: 3 means 8 and 4 means 16 -- other sizes are not supported because they don't seem to be useful (higher fingerprint resolution makes it vulnerable to image shifts and croppings, also `#distance` becomes much slower). Because IDHash's fingerprint is more complex than DHash's one it's not that straight forward to compare them so under the hood the `#distance` method have to check the size of fingerprint. If you are sure that fingerprints were made with power=3 then to skip the check you may use the `#distance3` method directly.  
@@ -130,7 +124,7 @@ end
         DHashVips::IDHash     1.060000   0.090000   1.150000 (  1.100332)
         DHashVips::IDHash 4   1.030000   0.080000   1.110000 (  1.089148)
 
-        measure the distance (1000 times):
+        measure the distance (32*32*1000 times):
                                             user     system      total        real
         Dhash hamming                   3.140000   0.020000   3.160000 (  3.179392)
         DHashVips::DHash hamming        3.040000   0.020000   3.060000 (  3.095190)
@@ -147,7 +141,7 @@ end
         DHashVips::IDHash     1.080000   0.100000   1.180000 (  1.156446)
         DHashVips::IDHash 4   1.030000   0.090000   1.120000 (  1.076117)
 
-        measure the distance (1000 times):
+        measure the distance (32*32*1000 times):
                                             user     system      total        real
         Dhash hamming                   1.770000   0.010000   1.780000 (  1.815612)
         DHashVips::DHash hamming        1.810000   0.010000   1.820000 (  1.875666)
@@ -165,7 +159,7 @@ end
         DHashVips::IDHash     0.769975   0.071087   0.841062 (  0.790470)
         DHashVips::IDHash 4   0.805311   0.077918   0.883229 (  0.825897)
 
-        measure the distance (2000 times):
+        measure the distance (32*32*2000 times):
                                                user     system      total        real
         Dhash hamming                      1.810000   0.000000   1.810000 (  1.824719)
         Phamilie distance                  1.000000   0.010000   1.010000 (  1.006127)
@@ -177,7 +171,21 @@ end
 
 * Also note that to make `#distance` able to assume the fingerprint resolution from the size of Integer that represents it, the change in its structure was needed (left half of bits was swapped with right one), so fingerprints between versions 0.0.4 and 0.0.5 became incompatible, but you probably can convert them manually. Otherwise if we put the version or structure information inside fingerprint it would became slow to (de)serialize and store.
 
-## Development
+## Development notes
+
+    $ ruby test.rb
+
+* You might need to prepend `bundle exec` to all the `rake` commands.
+
+* You get this:
+
+        Can't install RMagick 2.16.0. Can't find MagickWand.h.
+
+    because Imagemagick sucks but we need it to benchmark alternative gems, so:
+
+        $ brew install imagemagick@6
+        $ brew unlink imagemagick@7
+        $ brew link imagemagick@6 --force
 
 * OS X El Captain and rbenv may cause environment issues that would make you do things like:
 
@@ -202,10 +210,14 @@ end
 
         $ PKG_CONFIG_PATH="/usr/local/Cellar/imagemagick@6/6.9.10-74/lib/pkgconfig" bundle install
 
-* You might need to prepend `bundle exec` to all the `rake` commands.
-
 * Execute the `rake compare_quality` at least once before executing other rake tasks because it's currently the only one that downloads the test images.
 
+* The tag `v0.0.0.4` is not semver and not real gem version -- it's only for Github Actions testing purposes.
+
+* To quickly find out what does the dhash-vips Docker image include: `docker run --rm <image_name> sh -c "cat /etc/alpine-release; ruby -v; vips -v; gem list dhash-vips` (TODO: write in this README about the existing Docker image).
+
+* Phamilie works with filenames instead of fingerprints and caches them but not distances.
+
 ## Credits
 
 [John Cupitt](https://github.com/jcupitt) (libvips and ruby-vips maintainer) helped me a lot.

data/Rakefile

@@ -201,8 +201,7 @@ task :compare_images do |_|
   a.join(b, :horizontal, shim: 15).write_to_file "ab.png"
 end
 
-# ./ruby `rbenv which rake` compare_speed
-desc "Benchmarks Dhash, DHashVips::DHash and DHashVips::IDHash"
+desc "Benchmark speed of Dhash, DHashVips::DHash, DHashVips::IDHash and Phamilie"
 task :compare_speed do
   require "dhash"
   require "phamilie"
@@ -247,10 +246,11 @@ task :compare_speed do
   end
 
   # for `distance`, `distance3_ruby` and `distance3_c` we use the same hashes
+  # this array manipulation converts [1, 2, 3, 4, 5] into [1, 2, 3, 4, 4, 4, 5]
   hashes[-1, 1] = hashes[-2, 2]
   hashes[-1, 1] = hashes[-2, 2]
 
-  puts "\nmeasure the distance (2000 times):"
+  puts "\nmeasure the distance (32*32*2000 times):"
   Benchmark.bm 32 do |bm|
     [
       [Dhash, :hamming],
@@ -271,3 +271,86 @@ task :compare_speed do
   end
 
 end
+
+desc "Benchmarks everything about Dhash, DHashVips::DHash, DHashVips::IDHash and Phamilie"
+task :benchmark do
+  abort "provide a folder with images grouped by similarity" unless 2 === ARGV.size
+  abort "invalid folder provided" unless Dir.exist?(dir = ARGV.last)
+
+  require "dhash"
+  require "phamilie"
+  phamilie = Phamilie.new
+  require_relative "lib/dhash-vips"
+
+  filenames = Dir.glob("#{dir}/*").map{ |_| Dir.glob "#{_}/*" }
+  puts "image groups sizes: #{filenames.map(&:size)}"
+  require "benchmark"
+
+  puts "step 1 / 3 (fingerprinting)"
+  hashes = []
+  bm1 = [
+    [phamilie, :fingerprint],
+    [Dhash, :calculate],
+    [DHashVips::DHash, :calculate],
+    [DHashVips::IDHash, :fingerprint],
+  ].map do |m, calc, power|
+    Benchmark.realtime do
+      hashes.push filenames.flatten.map{ |filename| m.send calc, filename, *power }
+    end
+  end
+
+  puts "step 2 / 3 (comparing fingerprints)"
+  combs = filenames.flatten.size ** 2
+  n = 10_000_000_000_000 / Dir.glob("#{dir}/*/*").map(&File.method(:size)).inject(:+) / combs
+  bm2 = [
+    [phamilie, :distance, nil, filenames.flatten],
+    [Dhash, :hamming],
+    [DHashVips::DHash, :hamming],
+    [DHashVips::IDHash, :distance3_c],
+  ].zip(hashes).map do |(m, dm, power, ii), hs|
+    Benchmark.realtime do
+      _ = ii || hs
+      _.product _ do |h1, h2|
+        n.times{ m.public_send dm, h1, h2 }
+      end
+    end
+  end
+
+  puts "step 3 / 3 (looking for the best threshold)"
+  bm3 = [
+    [phamilie, :fingerprint, :distance, nil, 0],
+    [Dhash, :calculate, :hamming],
+    [DHashVips::DHash, :calculate, :hamming],
+    [DHashVips::IDHash, :fingerprint, :distance],
+  ].map do |m, calc, dm, power, ii|
+    require_relative "common"
+    hashes = Dir.glob("#{dir}/*").flat_map{ |_| Dir.glob "#{_}/*" }.map{ |filename| [filename, m.public_send(calc, filename, *power)] }
+    report = Struct.new(:same, :sim, :not_sim).new [], [], []
+    hashes.size.times.to_a.repeated_combination(2) do |i, j|
+      report[
+        case
+        when i == j                                                   ; :same
+        when File.split(File.split(hashes[i][0]).first).last ==
+             File.split(File.split(hashes[j][0]).first).last && i < j ; :sim
+        else                                                          ; :not_sim
+        end
+      ].push m.method(dm).call hashes[i][ii||1], hashes[j][ii||1]
+    end
+    min, max = [*report.sim, *report.not_sim].minmax
+    fmi, fp, fn = (min..max+1).map do |b|
+      fp = report.not_sim.count{ |_| _ < b }
+      tp = report.sim.count{ |_| _ < b }
+      fn = report.sim.count{ |_| _ >= b }
+      [((tp + fp) * (tp + fn)).fdiv(tp * tp), fp, fn]
+    end.reject{ |_,| _.nan? }.min_by(&:first)
+    fmi
+  end
+
+  require "mll"
+  puts MLL::grid.call %w{ \  Fingerprint Compare 1/FMI^2 }.zip(*[
+    %w{ Phamilie Dhash DHash IDHash },
+    *[bm1, bm2].map{ |bm| bm.map{ |_| "%.3f" % _ } },
+    bm3.map{ |_| "%.3f" % _ }
+  ].transpose).transpose, spacings: [1.5, 0], alignment: :right
+  puts "(lower numbers are better)"
+end

data/dhash-vips.gemspec

@@ -1,16 +1,20 @@
 Gem::Specification.new do |spec|
   spec.name          = "dhash-vips"
-  spec.version       = "0.1.0.1"
+  spec.version       = "0.1.0.3"
   spec.author        = "Victor Maslov"
   spec.email         = "nakilon@gmail.com"
   spec.summary       = "dHash and IDHash powered by Vips"
   spec.homepage      = "https://github.com/nakilon/dhash-vips"
   spec.license       = "MIT"
 
-  spec.test_files    = %w{ test.rb }
-  spec.files         = `git ls-files -z`.split("\x0") - spec.test_files - %w{ .gitignore } - Dir.glob("example_ocr/**")
   spec.require_path  = "lib"
+  spec.test_files    = %w{ test.rb }
   spec.extensions    = %w{ extconf.rb }
+  spec.files         = `git ls-files -z`.split("\x0") -
+                       spec.test_files -
+                       %w{ .gitignore Dockerfile } -
+                       Dir.glob("example_*/**/*") -
+                       Dir.glob(".github/**/*")
 
   spec.add_dependency "ruby-vips", "~>2.0.16"
 

data/test.rb

@@ -6,6 +6,7 @@ require "dhash-vips"
 
 [
   [DHashVips::DHash, :hamming, :calculate, 2, 23, 18, 50, 4],
+    # vips-8.9.1-Tue Jan 28 13:05:46 UTC 2020
     # [[0, 14, 26, 27, 31, 27, 32, 28, 43, 43, 34, 37, 37, 34, 35, 42],
     #  [14, 0, 28, 25, 39, 35, 32, 32, 43, 43, 38, 41, 41, 38, 37, 50],
     #  [26, 28, 0, 13, 35, 41, 28, 30, 41, 41, 36, 33, 35, 32, 27, 36],
@@ -23,22 +24,23 @@ require "dhash-vips"
     #  [35, 37, 27, 26, 40, 34, 23, 27, 28, 28, 29, 30, 26, 21, 0, 23],
     #  [42, 50, 36, 33, 31, 27, 34, 34, 27, 27, 18, 19, 23, 26, 23, 0]]
   [DHashVips::IDHash, :distance, :fingerprint, 6, 22, 23, 65, 0],
-    # [[0, 17, 32, 35, 57, 45, 51, 50, 48, 47, 54, 48, 60, 50, 47, 56],
-    #  [17, 0, 30, 35, 58, 46, 54, 55, 47, 51, 57, 49, 62, 52, 52, 60],
+    # vips-8.9.1-Tue Jan 28 13:05:46 UTC 2020
+    # [[0, 16, 32, 35, 57, 45, 51, 50, 48, 47, 54, 48, 60, 50, 47, 56],
+    #  [16, 0, 30, 34, 58, 47, 55, 56, 47, 50, 57, 49, 62, 52, 52, 61],
     #  [32, 30, 0, 9, 47, 54, 45, 41, 65, 62, 42, 37, 51, 44, 49, 49],
-    #  [35, 35, 9, 0, 54, 64, 42, 40, 57, 56, 48, 39, 50, 40, 41, 51],
+    #  [35, 34, 9, 0, 54, 64, 42, 40, 57, 56, 48, 39, 50, 40, 41, 51],
     #  [57, 58, 47, 54, 0, 22, 43, 45, 64, 61, 48, 47, 35, 43, 47, 48],
-    #  [45, 46, 54, 64, 22, 0, 53, 54, 55, 54, 40, 46, 39, 42, 43, 42],
-    #  [51, 54, 45, 42, 43, 53, 0, 6, 33, 35, 52, 43, 46, 45, 44, 47],
-    #  [50, 55, 41, 40, 45, 54, 6, 0, 38, 41, 53, 50, 48, 45, 41, 42],
+    #  [45, 47, 54, 64, 22, 0, 53, 54, 55, 54, 40, 46, 39, 42, 43, 42],
+    #  [51, 55, 45, 42, 43, 53, 0, 6, 33, 35, 52, 43, 46, 45, 44, 47],
+    #  [50, 56, 41, 40, 45, 54, 6, 0, 38, 41, 53, 50, 48, 45, 41, 42],
     #  [48, 47, 65, 57, 64, 55, 33, 38, 0, 9, 51, 53, 47, 47, 41, 46],
-    #  [47, 51, 62, 56, 61, 54, 35, 41, 9, 0, 51, 57, 50, 49, 44, 43],
+    #  [47, 50, 62, 56, 61, 54, 35, 41, 9, 0, 51, 57, 50, 49, 44, 43],
     #  [54, 57, 42, 48, 48, 40, 52, 53, 51, 51, 0, 10, 33, 36, 38, 25],
     #  [48, 49, 37, 39, 47, 46, 43, 50, 53, 57, 10, 0, 27, 30, 37, 27],
     #  [60, 62, 51, 50, 35, 39, 46, 48, 47, 50, 33, 27, 0, 20, 23, 28],
     #  [50, 52, 44, 40, 43, 42, 45, 45, 47, 49, 36, 30, 20, 0, 35, 39],
     #  [47, 52, 49, 41, 47, 43, 44, 41, 41, 44, 38, 37, 23, 35, 0, 19],
-    #  [56, 60, 49, 51, 48, 42, 47, 42, 46, 43, 25, 27, 28, 39, 19, 0]]
+    #  [56, 61, 49, 51, 48, 42, 47, 42, 46, 43, 25, 27, 28, 39, 19, 0]]
 ].each do |lib, dm, calc, min_similar, max_similar, min_not_similar, max_not_similar, bw_exceptional|
 
   describe lib do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dhash-vips
 version: !ruby/object:Gem::Version
-  version: 0.1.0.1
+  version: 0.1.0.3
 platform: ruby
 authors:
 - Victor Maslov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-01-09 00:00:00.000000000 Z
+date: 2020-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-vips