pHash 1.0.0

data/.gitignore

@@ -0,0 +1,12 @@
+/pkg/
+/*.gem
+
+/doc/
+/rdoc/
+/.yardoc/
+/coverage/
+
+Makefile
+*.o
+*.bundle
+/tmp/

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Ivan Kuchin
+
+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.

data/README.markdown

@@ -0,0 +1,53 @@
+# pHash
+
+Interface to [pHash](http://pHash.org/).
+
+## Installation
+
+    gem install pHash
+
+Audio hash functions needs to be compiled with C linkage, so if you get `FFI::NotFoundError` check names of methods in `libpHash`. Tiny patch for pHash 0.9.4 is in `audiophash.diff`.
+
+## Usage
+
+Compare two mp3s:
+
+    require 'phash/audio'
+
+    a = Phash::Audio.new('first.mp3')
+    b = Phash::Audio.new('second.mp3')
+    a.similarity(b)
+
+or just
+
+    a % b
+
+Get bunch of comparators and work with them:
+
+    audios = Phash::Audio.for_paths(Dir['**/*.{mp3,wav}'])
+    audios.combination(2) do |a, b|
+      similarity = a % b
+      # work with similarity
+    end
+
+Videos:
+
+    require 'phash/video'
+
+    Phash::Video.new('first.mp4') % Phash::Video.new('second.mp4')
+
+Images:
+
+    require 'phash/image'
+
+    Phash::Image.new('first.jpg') % Phash::Image.new('second.png')
+
+Texts:
+
+    require 'phash/text'
+
+    Phash::Text.new('first.txt') % Phash::Text.new('second.txt')
+
+## Copyright
+
+Copyright (c) 2011 Ivan Kuchin. See LICENSE.txt for details.

data/audiophash.diff

@@ -0,0 +1,17 @@
+--- src/audiophash.h.orig	2011-12-13 14:47:08.000000000 +0100
++++ src/audiophash.h	2011-12-13 14:47:12.000000000 +0100
+@@ -34,7 +34,6 @@
+ 
+ extern "C" {
+ #include "ph_fft.h"
+-}
+ 
+ /*  /brief count number of samples in file
+  *  
+@@ -105,4 +104,6 @@
+  */
+ double* ph_audio_distance_ber(uint32_t *hash_a , const int Na, uint32_t *hash_b, const int Nb, const float threshold, const int block_size, int &Nc);
+ 
++}
++
+ #endif

data/lib/phash.rb

@@ -0,0 +1,44 @@
+require 'ffi'
+
+module Phash
+  class HashData
+    attr_reader :data, :length
+    def initialize(data, length = nil)
+      @data, @length = data, length
+    end
+  end
+
+  class FileHash
+    attr_reader :path
+
+    # File path
+    def initialize(path)
+      @path = path
+    end
+
+    # Init multiple image instances
+    def self.for_paths(paths, *args)
+      paths.map do |path|
+        new(path, *args)
+      end
+    end
+
+    # Cached hash of text
+    def phash
+      @phash ||= compute_phash
+    end
+
+    def %(other)
+      similarity(other)
+    end
+  end
+
+  extend FFI::Library
+
+  ffi_lib(ENV['PHASH_LIB'] || Dir['/{usr,usr/local,opt/local}/lib/libpHash.{dylib,so}'].first)
+
+  autoload :Audio, 'phash/audio'
+  autoload :Image, 'phash/image'
+  autoload :Text, 'phash/text'
+  autoload :Video, 'phash/video'
+end

data/lib/phash/all.rb

@@ -0,0 +1,3 @@
+%w[audio image text video].each do |type|
+  require "phash/#{type}"
+end

data/lib/phash/audio.rb

@@ -0,0 +1,116 @@
+require 'phash'
+
+module Phash
+  # read audio
+  #
+  # param filename - path and name of audio file to read
+  # param sr - sample rate conversion
+  # param channels - nb channels to convert to (always 1) unused
+  # param buf - preallocated buffer
+  # param buflen - (in/out) param for buf length
+  # param nbsecs - float value for duration (in secs) to read from file
+  #
+  # return float* - float pointer to start of buffer - one channel of audio, NULL if error
+  #
+  # float* ph_readaudio(const char *filename, int sr, int channels, float *sigbuf, int &buflen, const float nbsecs = 0);
+  #
+  attach_function :ph_readaudio, [:string, :int, :int, :pointer, :pointer, :float], :pointer
+
+  # audio hash calculation
+  # purpose: hash calculation for each frame in the buffer.
+  #          Each value is computed from successive overlapping frames of the input buffer.
+  #          The value is based on the bark scale values of the frame fft spectrum. The value
+  #          computed from temporal and spectral differences on the bark scale.
+  #
+  # param buf - pointer to start of buffer
+  # param N   - length of buffer
+  # param sr  - sample rate on which to base the audiohash
+  # param nb_frames - (out) number of frames in audio buf and length of audiohash buffer returned
+  #
+  # return uint32 pointer to audio hash, NULL for error
+  #
+  # uint32_t* ph_audiohash(float *buf, int nbbuf, const int sr, int &nbframes);
+  #
+  attach_function :ph_audiohash, [:pointer, :int, :int, :pointer], :pointer
+
+  # distance function between two hashes
+  #
+  # param hash_a - first hash
+  # param Na     - length of first hash
+  # param hash_b - second hash
+  # param Nb     - length of second hash
+  # param threshold - threshold value to compare successive blocks, 0.25, 0.30, 0.35
+  # param block_size - length of block_size, 256
+  # param Nc     - (out) length of confidence score vector
+  #
+  # return double - ptr to confidence score vector
+  #
+  # double* ph_audio_distance_ber(uint32_t *hash_a, const int Na, uint32_t *hash_b, const int Nb, const float threshold, const int block_size, int &Nc);
+  #
+  attach_function :ph_audio_distance_ber, [:pointer, :int, :pointer, :int, :float, :int, :pointer], :pointer
+
+  class << self
+    class AudioHash < HashData; end
+
+    # Read audio file specified by path and optional length using <tt>ph_readaudio</tt> and get its hash using <tt>ph_audiohash</tt>
+    def audio_hash(path, length = 0)
+      sample_rate = 8000
+      audio_data_length_p = FFI::MemoryPointer.new :int
+      if audio_data = ph_readaudio(path.to_s, sample_rate, 1, nil, audio_data_length_p, length.to_f)
+        audio_data_length = audio_data_length_p.get_int(0)
+        audio_data_length_p.free
+
+        hash_data_length_p = FFI::MemoryPointer.new :int
+        if hash_data = ph_audiohash(audio_data, audio_data_length, sample_rate, hash_data_length_p)
+          hash_data_length = hash_data_length_p.get_int(0)
+          hash_data_length_p.free
+
+          AudioHash.new(hash_data, hash_data_length)
+        end
+      end
+    end
+
+    # Get distance between two audio hashes using <tt>ph_audio_distance_ber</tt>
+    def audio_distance_ber(hash_a, hash_b, threshold = 0.25, block_size = 256)
+      hash_a.is_a?(AudioHash) or raise ArgumentError.new('hash_a is not an AudioHash')
+      hash_b.is_a?(AudioHash) or raise ArgumentError.new('hash_b is not an AudioHash')
+
+      distance_vector_length_p = FFI::MemoryPointer.new :int
+      block_size = [block_size.to_i, hash_a.length, hash_b.length].min
+      if distance_vector = ph_audio_distance_ber(hash_a.data, hash_a.length, hash_b.data, hash_b.length, threshold.to_f, block_size, distance_vector_length_p)
+        distance_vector_length = distance_vector_length_p.get_int(0)
+        distance_vector_length_p.free
+
+        distance = distance_vector.get_array_of_double(0, distance_vector_length)
+        distance_vector.free
+        distance
+      end
+    end
+
+    # Get similarity from audio_distance_ber
+    def audio_similarity(hash_a, hash_b, *args)
+      audio_distance_ber(hash_a, hash_b, *args).max
+    end
+  end
+
+  # Class to store audio file hash and compare to other
+  class Audio < FileHash
+    attr_reader :length
+
+    # Audio path and optional length in seconds to read
+    def initialize(path, length = 0)
+      @path, @length = path, length
+    end
+
+    # Similarity with other audio
+    def similarity(other, *args)
+      Phash.audio_similarity(phash, other.phash, *args)
+    end
+
+  private
+
+    def compute_phash
+      Phash.audio_hash(@path, @length)
+    end
+  end
+end

data/lib/phash/image.rb

@@ -0,0 +1,59 @@
+require 'phash'
+
+module Phash
+  # compute dct robust image hash
+  #
+  # param file string variable for name of file
+  # param hash of type ulong64 (must be 64-bit variable)
+  # return int value - -1 for failure, 1 for success
+  #
+  # int ph_dct_imagehash(const char* file, ulong64 &hash);
+  #
+  attach_function :ph_dct_imagehash, [:string, :pointer], :int
+
+  # no info in pHash.h
+  #
+  # int ph_hamming_distance(const ulong64 hash1,const ulong64 hash2);
+  #
+  attach_function :ph_hamming_distance, [:uint64, :uint64], :int
+
+  class << self
+    # Get image file hash using <tt>ph_dct_imagehash</tt>
+    def image_hash(path)
+      hash_p = FFI::MemoryPointer.new :ulong_long
+      if -1 != ph_dct_imagehash(path.to_s, hash_p)
+        hash = hash_p.get_uint64(0)
+        hash_p.free
+
+        hash
+      end
+    end
+
+    # Get distance between two image hashes using <tt>ph_hamming_distance</tt>
+    def image_hamming_distance(hash_a, hash_b)
+      hash_a.is_a?(Integer) or raise ArgumentError.new('hash_a is not an Integer')
+      hash_b.is_a?(Integer) or raise ArgumentError.new('hash_b is not an Integer')
+
+      ph_hamming_distance(hash_a, hash_b)
+    end
+
+    # Get similarity from hamming_distance
+    def image_similarity(hash_a, hash_b)
+      1 - image_hamming_distance(hash_a, hash_b) / 64.0
+    end
+  end
+
+  # Class to store image file hash and compare to other
+  class Image < FileHash
+    # Similarity with other image
+    def similarity(other)
+      Phash.image_similarity(phash, other.phash)
+    end
+
+  private
+
+    def compute_phash
+      Phash.image_hash(@path)
+    end
+  end
+end

data/lib/phash/text.rb

@@ -0,0 +1,100 @@
+require 'phash'
+
+module Phash
+  class TxtHashPoint < FFI::Struct
+    layout  :hash, :uint64,
+            :index, :off_t
+  end
+
+  class TxtMatch < FFI::Struct
+    layout  :index_a, :off_t,
+            :index_b, :off_t,
+            :length, :uint32
+  end
+
+  # textual hash for file
+  #
+  # param filename - char* name of file
+  # param nbpoints - int length of array of return value (out)
+  # return TxtHashPoint* array of hash points with respective index into file.
+  #
+  # TxtHashPoint* ph_texthash(const char *filename, int *nbpoints);
+  #
+  attach_function :ph_texthash, [:string, :pointer], :pointer
+
+  # compare 2 text hashes
+  #
+  # param hash1 -TxtHashPoint
+  # param N1 - int length of hash1
+  # param hash2 - TxtHashPoint
+  # param N2 - int length of hash2
+  # param nbmatches - int number of matches found (out)
+  # return TxtMatch* - list of all matches
+  #
+  # TxtMatch* ph_compare_text_hashes(TxtHashPoint *hash1, int N1, TxtHashPoint *hash2, int N2, int *nbmatches);
+  #
+  attach_function :ph_compare_text_hashes, [:pointer, :int, :pointer, :int, :pointer], :pointer
+
+  class << self
+    class TextHash < HashData; end
+
+    # Get text file hash using <tt>ph_texthash</tt>
+    def text_hash(path)
+      hash_data_length_p = FFI::MemoryPointer.new :int
+      if hash_data = ph_texthash(path.to_s, hash_data_length_p)
+        hash_data_length = hash_data_length_p.get_int(0)
+        hash_data_length_p.free
+
+        TextHash.new(hash_data, hash_data_length)
+      end
+    end
+
+    # Get distance between two text hashes using <tt>text_distance</tt>
+    def text_hash_matches(hash_a, hash_b)
+      hash_a.is_a?(TextHash) or raise ArgumentError.new('hash_a is not a TextHash')
+      hash_b.is_a?(TextHash) or raise ArgumentError.new('hash_b is not a TextHash')
+
+      matches_length_p = FFI::MemoryPointer.new :int
+      if data = ph_compare_text_hashes(hash_a.data, hash_a.length, hash_b.data, hash_b.length, matches_length_p)
+        matches_length = matches_length_p.get_int(0)
+        matches_length_p.free
+
+        matches = matches_length.times.map{ |i| TxtMatch.new(data + i * TxtMatch.size) }
+        data.free
+        matches
+      end
+    end
+
+    def text_similarity(hash_a, hash_b)
+      matches = text_hash_matches(hash_a, hash_b)
+      # p [hash_a.length, hash_b.length, matches.length]
+      matched_a = Array.new(hash_a.length)
+      matched_b = Array.new(hash_b.length)
+      matches.each do |match|
+        index_a = match[:index_a]
+        index_b = match[:index_b]
+        match[:length].times do |i|
+          matched_a[index_a + i] = true
+          matched_b[index_b + i] = true
+        end
+      end
+      coverage_a = matched_a.nitems / hash_a.length.to_f
+      coverage_b = matched_b.nitems / hash_b.length.to_f
+      (coverage_a + coverage_b) * 0.5
+    end
+  end
+
+  # Class to store text file hash and compare to other
+  class Text < FileHash
+    # Distance from other file, for now bit useless thing
+    def similarity(other)
+      Phash.text_similarity(phash, other.phash)
+    end
+
+  private
+
+    def compute_phash
+      Phash.text_hash(@path)
+    end
+  end
+end

data/lib/phash/video.rb

@@ -0,0 +1,55 @@
+require 'phash'
+
+module Phash
+  # no info in pHash.h
+  #
+  # ulong64* ph_dct_videohash(const char *filename, int &Length);
+  #
+  attach_function :ph_dct_videohash, [:string, :pointer], :pointer
+
+  # no info in pHash.h
+  #
+  # double ph_dct_videohash_dist(ulong64 *hashA, int N1, ulong64 *hashB, int N2, int threshold=21);
+  #
+  attach_function :ph_dct_videohash_dist, [:pointer, :int, :pointer, :int, :int], :double
+
+  class << self
+    class VideoHash < HashData; end
+
+    # Get video hash using <tt>ph_dct_videohash</tt>
+    def video_hash(path)
+      hash_data_length_p = FFI::MemoryPointer.new :int
+      if hash_data = ph_dct_videohash(path.to_s, hash_data_length_p)
+        hash_data_length = hash_data_length_p.get_int(0)
+        hash_data_length_p.free
+
+        VideoHash.new(hash_data, hash_data_length)
+      end
+    end
+
+    # Get distance between two video hashes using <tt>ph_dct_videohash_dist</tt>
+    def video_dct_distance(hash_a, hash_b, threshold = 21)
+      hash_a.is_a?(VideoHash) or raise ArgumentError.new('hash_a is not a VideoHash')
+      hash_b.is_a?(VideoHash) or raise ArgumentError.new('hash_b is not a VideoHash')
+
+      ph_dct_videohash_dist(hash_a.data, hash_a.length, hash_b.data, hash_b.length, threshold.to_i)
+    end
+
+    # Get similarity from video_dct_distance
+    alias_method :video_similarity, :video_dct_distance
+  end
+
+  # Class to store video file hash and compare to other
+  class Video < FileHash
+    # Similarity with other video
+    def similarity(other, *args)
+      Phash.video_similarity(phash, other.phash, *args)
+    end
+
+  private
+
+    def compute_phash
+      Phash.video_hash(@path)
+    end
+  end
+end