pixmatch 0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+Copyright (c) 2011 Art.sy
+
+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.rdoc

@@ -0,0 +1,86 @@
+= Pixmatch
+
+Pixmatch REST API client library for TinEye[http://www.tineye.com/] reverse-image search.
+
+== Using
+
+    gem install pixmatch
+
+== Example
+
+  require 'rubygems'
+  require 'pixmatch'
+  
+  Pixmatch.configure do |config|
+    config.username     = 'username'
+    config.password     = 'password'
+    config.url          = 'api.tineye.com'
+  end
+
+  # ping the server
+  response = Pixmatch.ping()
+  puts response['status']
+
+  # count the number of images in the collection
+  count = Pixmatch.count()
+  
+  # add an image
+  Pixmatch.add('images/mona-lisa.jpg')
+  Pixmatch.add(File.new('images/mona-lisa.jpg')
+  
+  # add a collection of images
+  Pixmatch.add(Dir.glob('images/*.jpg'))
+  
+  # list images
+  images = Pixmatch.list()
+  images.each { |filename| puts filename }
+
+  # delete an image
+  Pixmatch.delete('mona-lisa.jpg')
+
+  # delete an array of images
+  Pixmatch.delete([ 'mona-lisa.jpg', 'mona-lisa-botero.jpg' ])
+  
+  # search
+  found = Pixmatch.search('images/mona-lisa.jpg')
+  found.each { |find|
+    puts "#{find['filename']}: #{find['score']}"
+  }
+
+== Contributing
+
+* Fork the project
+* Copy 'config/pixmatch.yml.default' to 'config/pixmatch.yml'. Edit your pixmatch API credentials as follows.
+    test:
+      <<: *settings
+      username: '<your username>'
+      password: '<your password>'
+      endpoint: 'http://<your url>.tineye.com'
+* Run 'bundle install'
+* Test with 'rspec spec'
+* Send pull requests.
+  
+== Copyright
+
+Copyright (c) 2011 Art.sy
+
+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/lib/pixmatch/api.rb

@@ -0,0 +1,21 @@
+require File.expand_path('../request', __FILE__)
+
+# Adapted from the Ruby Twitter gem.
+# @see https://github.com/jnunemaker/twitter
+module Pixmatch
+	# @private
+	class API
+		# @private
+		attr_accessor(*Configuration::VALID_OPTIONS_KEYS)
+		
+		# Creates a new API
+		def initialize(options = {})
+			options = Pixmatch.options.merge(options)
+			Configuration::VALID_OPTIONS_KEYS.each do |key|
+				send("#{key}=", options[key])
+			end
+		end
+		
+		include Request
+	end
+end

data/lib/pixmatch/client/add.rb

@@ -0,0 +1,14 @@
+module Pixmatch
+  class Client
+    module Add
+      # Index and Add a list of images to your collection.
+      # @param files [Array] Array of File or String objects.
+      def add(files)
+        files = [ files ] if (files.is_a?(String) || files.is_a?(File))
+        files_hash = { }
+        files.each { |f| files_hash["images[#{files_hash.size}]"] = f.is_a?(File) ? f : File.new(f, "rb") }
+        request(:post, 'rest', { method: :add }, { payload: files_hash })        
+      end
+    end    
+  end
+end

data/lib/pixmatch/client/count.rb

@@ -0,0 +1,16 @@
+module Pixmatch
+  class Client
+    module Count
+      # Get the number of items currently in the collection.
+      # @return Number of items currently in the collection.
+      def count
+        response = request(:get, 'rest', { method: :count })
+        result = response['result']
+        raise "Missing result in response." if result.nil?
+        raise "Invalid result in response (#{result.class.name})." if ! result.is_a?(Array)
+        raise "Invalid count in result response (#{result.size})." if result.size != 1
+        result[0].to_i
+      end
+    end    
+  end
+end

data/lib/pixmatch/client/delete.rb

@@ -0,0 +1,14 @@
+module Pixmatch
+  class Client
+    module Delete
+      # Given a list of image filenames, delete the images from the collection.
+      # @param files [Array] Array of file names.
+      def delete(filenames) 
+        filenames = [ filenames ] if filenames.is_a?(String)
+        filenames_hash = { }
+        filenames.each { |f| filenames_hash["filenames[#{filenames_hash.size}]"] = f }
+        request(:post, 'rest', { method: :delete }, { payload: filenames_hash })
+      end
+    end    
+  end
+end

data/lib/pixmatch/client/list.rb

@@ -0,0 +1,16 @@
+module Pixmatch
+  class Client
+    module List
+      # List the contents of the collection.
+      # @param offset [Integer] Offset to start at, default is zero.
+      # @param limit [Integer] Limit number of results, default is zero (all results).      
+      def list(offset = 0, limit = 0) 
+        response = request(:get, 'rest', { method: 'list', offset: offset, limit: limit })
+        result = response['result']
+        raise "Missing result in response." if result.nil?
+        raise "Invalid result in response (#{result.class.name})." if ! result.is_a?(Array)
+        result
+      end
+    end    
+  end
+end

data/lib/pixmatch/client/ping.rb

@@ -0,0 +1,10 @@
+module Pixmatch
+  class Client
+    module Ping
+      # Check whether the PixMatch server is running.
+      def ping
+        request(:get, 'rest', { method: :ping })
+      end
+    end    
+  end
+end

data/lib/pixmatch/client/search.rb

@@ -0,0 +1,21 @@
+module Pixmatch
+  class Client
+    module Search
+      # Given an image, search against our collection and return any matches with corresponding scores.
+      # @param image [File or String] The image file object that will be searched for.
+      # @param options [Hash] The following options.
+      #   * min_score [Integer] The minimum score that should be returned, defaults to 0. Should be between 0 and 100 (inclusive).
+      #   * max_num_matches [Integer] The maximum number of matches that should be returned, defaults to 10. A value of -1 indicates no limit.
+      #   * check_horizontal_flip [Boolean] Indicates whether the search incorporates checking for horizontal flips, defaults to true.
+      # @return Array of { score, filename } hashes.
+      def search(image, options = {})
+        payload = { "image" => image.is_a?(File) ? image : File.new(image, "rb") }
+        response = request(:post, 'rest', { method: 'search' }.merge(options), { payload: payload })
+        result = response['result']
+        raise "Missing result in response." if result.nil?
+        raise "Invalid result in response (#{result.class.name})." if ! result.is_a?(Array)
+        result
+      end
+    end    
+  end
+end

data/lib/pixmatch/client.rb

@@ -0,0 +1,15 @@
+# Adapted from the Ruby Twitter gem.
+# @see https://github.com/jnunemaker/twitter
+module Pixmatch
+	# Wrapper for the Pixmatch REST API
+	class Client < API
+		Dir[File.expand_path('../client/*.rb', __FILE__)].each { |f| require f }
+		
+		include Pixmatch::Client::Ping
+		include Pixmatch::Client::Count
+		include Pixmatch::Client::Add
+		include Pixmatch::Client::List
+		include Pixmatch::Client::Delete
+		include Pixmatch::Client::Search
+	end
+end

data/lib/pixmatch/configuration.rb

@@ -0,0 +1,49 @@
+# Adapted from the Ruby Twitter gem.
+# @see https://github.com/jnunemaker/twitter
+module Pixmatch
+	# Defines constants and methods related to configuration.
+	module Configuration
+		# An array of valid keys in the options hash when configuring a {Flixated::API}.
+		VALID_OPTIONS_KEYS = [
+			:username,
+			:password,
+			:endpoint
+		].freeze
+	
+		# By default, don't set a username.
+		DEFAULT_USERNAME = nil.freeze
+		
+		# By default, don't set a password.
+		DEFAULT_PASSWORD = nil.freeze
+		
+		# The endpoint that will be used to connect if none is set.
+		DEFAULT_ENDPOINT = 'https://api.tineye.com'.freeze
+		
+		# @private
+		attr_accessor(*VALID_OPTIONS_KEYS)
+		
+		# When this module is extended, set all configuration options to their default values.
+		def self.extended(base)
+			base.reset
+		end
+		
+		# Convenience method to allow configuration options to be set in a block.
+		def configure
+			yield self
+		end
+		
+		# Create a hash of options and their values.
+		def options
+			VALID_OPTIONS_KEYS.inject({}) do |option,key|
+				option.merge!(key => send(key))
+			end
+		end
+		
+		# Reset all configuration options to default.
+		def reset
+			self.username               = DEFAULT_USERNAME
+			self.password               = DEFAULT_PASSWORD
+			self.endpoint               = DEFAULT_ENDPOINT
+		end
+	end
+end

data/lib/pixmatch/error.rb

@@ -0,0 +1,18 @@
+module Pixmatch
+  # Custom error class for rescuing from all known Pixmatch errors.
+  class Error < StandardError
+    attr_accessor :status, :method, :detail 
+    
+    def initialize(json)
+      @status = json['status']
+      @method = json['method']
+      @error = json['error']
+      @result = json['result']
+    end
+    
+    def to_s
+      s = @error.nil? ? 'Unexpected Error' : @error.join('\r\n')
+      s += ("\r\n " + @result.join('\r\n ')) if @result
+    end
+  end
+end

data/lib/pixmatch/request.rb

@@ -0,0 +1,28 @@
+require 'uri'
+require 'rest_client'
+
+module Pixmatch
+	module Request		
+		private
+		
+		def request(http_method, path, query_params = {}, data_params = {})
+		  capture RestClient::Request.new({ 
+		    method: http_method,
+		    url: "#{endpoint}/#{paramify(path, query_params)}", 
+		    user: username,
+		    password: password
+		   }.merge(data_params)).execute   			
+		end
+		
+		def capture(response)
+			json = Utils.parse_json(response)
+		  Utils.handle_error(json)
+			json
+		end
+		
+		def paramify(path, params)
+      URI.encode("#{path}/?#{params.map { |k,v| "#{k}=#{v}" }.join('&')}")
+    end
+    
+	end
+end

data/lib/pixmatch/utils.rb

@@ -0,0 +1,17 @@
+require 'hashie'
+require 'yajl'
+
+module Pixmatch
+  # @private
+  module Utils
+    private 
+      def self.handle_error(json_response)
+        raise Pixmatch::Error.new(json_response) if (json_response['status'] != 'ok')
+      end
+      
+      # Parses JSON and returns a Hashie::Mash
+      def self.parse_json(json)
+        Hashie::Mash.new(Yajl::Parser.new.parse(json))
+      end
+  end
+end

data/lib/pixmatch/version.rb

@@ -0,0 +1,3 @@
+module Pixmatch
+	VERSION = '0.1.0'
+end

data/lib/pixmatch.rb

@@ -0,0 +1,30 @@
+require File.expand_path('../pixmatch/version', __FILE__)
+require File.expand_path('../pixmatch/configuration', __FILE__)
+require File.expand_path('../pixmatch/utils', __FILE__)
+require File.expand_path('../pixmatch/error', __FILE__)
+require File.expand_path('../pixmatch/api', __FILE__)
+require File.expand_path('../pixmatch/client', __FILE__)
+
+# Adapted from the Ruby Twitter gem.
+# @see https://github.com/jnunemaker/twitter
+module Pixmatch
+	extend Configuration
+	
+	# Alias for pixmatch::Client.new
+	#
+	# @return {pixmatch::Client}
+	def self.client(options = {})
+		Pixmatch::Client.new(options)
+	end
+	
+	# Delegate to pixmatch::Client
+	def self.method_missing(method, *args, &block)
+		return super unless client.respond_to?(method)
+		client.send(method, *args, &block)
+	end
+	
+	# Delegate to pixmatch::Client
+	def self.respond_to?(method)
+		return client.respond_to?(method) || super
+	end
+end

data/spec/pixmatch_spec.rb

@@ -0,0 +1,87 @@
+require 'yaml'
+
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Pixmatch" do
+  before(:each) do
+    Pixmatch.configure do |config|
+      pixmatch_yml = File.join(File.dirname(__FILE__), '../config/pixmatch.yml')
+      pixmatch_yml = File.join(File.dirname(__FILE__), '../config/pixmatch.yml.default') if ! File.exists?(pixmatch_yml)
+      raise "missing config/pixmatch.yml" if ! File.exists?(pixmatch_yml) 
+      pixmatch_config = YAML.load_file(pixmatch_yml)['test']
+      config.username = pixmatch_config['username']
+      config.password = pixmatch_config['password']
+      config.endpoint = pixmatch_config['endpoint']
+    end
+  end
+  describe "methods" do
+    it "ping" do
+      response = Pixmatch.ping()
+      response['status'].should == "ok"
+      response['method'].should == "ping"
+    end
+    it "count" do
+      count = Pixmatch.count()
+      count.is_a?(Integer).should be_true
+      count.should >= 0
+    end
+    it "add with one path" do
+      response = Pixmatch.add(File.join(File.dirname(__FILE__), 'assets/mona-lisa.jpg'))
+      response['status'].should == "ok"
+      response['method'].should == "add"
+    end
+    it "add with one path as an array" do
+      response = Pixmatch.add([ File.join(File.dirname(__FILE__), 'assets/mona-lisa.jpg') ])
+      response['status'].should == "ok"
+      response['method'].should == "add"
+    end
+    it "add with one File object" do
+      response = Pixmatch.add(File.new(File.join(File.dirname(__FILE__), 'assets/mona-lisa.jpg')))
+      response['status'].should == "ok"
+      response['method'].should == "add"
+    end
+    it "add with one File object as an array" do
+      response = Pixmatch.add([ File.new(File.join(File.dirname(__FILE__), 'assets/mona-lisa.jpg')) ])
+      response['status'].should == "ok"
+      response['method'].should == "add"
+    end
+    it "add with an array of File objects" do      
+      response = Pixmatch.add(Dir.glob(File.join(File.dirname(__FILE__), 'assets/*.jpg')))
+      response['status'].should == "ok"
+      response['method'].should == "add"
+    end
+    it "list" do
+      result = Pixmatch.list()
+      result.is_a?(Array).should be_true
+      result.size.should >= 0
+    end
+    it "delete with one name" do
+      Pixmatch.add([ File.new(File.join(File.dirname(__FILE__), 'assets/mona-lisa.jpg')) ])
+      count = Pixmatch.count
+      response = Pixmatch.delete('mona-lisa.jpg')
+      response['status'].should == "ok"
+      response['method'].should == "delete"
+      Pixmatch.count.should == count - 1
+    end
+    it "delete an array of names" do
+      Pixmatch.add(Dir.glob(File.join(File.dirname(__FILE__), 'assets/*.jpg')))
+      count = Pixmatch.count
+      filenames = Dir.glob(File.join(File.dirname(__FILE__), 'assets/*.jpg')).map { |f| File.basename(f) }
+      response = Pixmatch.delete(filenames)
+      response['status'].should == "ok"
+      response['method'].should == "delete"
+      Pixmatch.count.should == count - filenames.size
+    end
+    it "search" do      
+      Pixmatch.add(Dir.glob(File.join(File.dirname(__FILE__), 'assets/*.jpg')))
+      response = Pixmatch.search(File.join(File.dirname(__FILE__), 'assets/mona-lisa.jpg'))
+      response.is_a?(Array).should be_true
+      response.size.should >= 0
+      response.each { |result|
+        result.is_a?(Hash).should be_true
+        result.has_key?('score').should be_true
+        result.has_key?('filename').should be_true
+      }
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+require 'rspec'
+require 'pixmatch'
+
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+
+end

metadata

@@ -0,0 +1,183 @@
+--- !ruby/object:Gem::Specification
+name: pixmatch
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  segments:
+  - 0
+  - 1
+  - 0
+  prerelease: false
+platform: ruby
+authors:
+- Daniel Doubrovkine
+autorequire: !!null 
+bindir: bin
+cert_chain: []
+date: 2011-04-13 00:00:00.000000000 -04:00
+default_executable: !!null 
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: &86264460 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.6.1
+        segments:
+        - 1
+        - 6
+        - 1
+  type: :runtime
+  prerelease: false
+  version_requirements: *86264460
+- !ruby/object:Gem::Dependency
+  name: yajl-ruby
+  requirement: &86264070 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.1
+        segments:
+        - 0
+        - 8
+        - 1
+  type: :runtime
+  prerelease: false
+  version_requirements: *86264070
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: &86263680 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+        segments:
+        - 1
+        - 0
+        - 0
+  type: :runtime
+  prerelease: false
+  version_requirements: *86263680
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &86263290 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+        segments:
+        - 2
+        - 5
+        - 0
+  type: :development
+  prerelease: false
+  version_requirements: *86263290
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: &86262900 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.10
+        segments:
+        - 1
+        - 0
+        - 10
+  type: :development
+  prerelease: false
+  version_requirements: *86262900
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: &86262510 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.5.2
+        segments:
+        - 1
+        - 5
+        - 2
+  type: :development
+  prerelease: false
+  version_requirements: *86262510
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &86262120 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.6.4
+        segments:
+        - 0
+        - 6
+        - 4
+  type: :development
+  prerelease: false
+  version_requirements: *86262120
+description: Pixmatch REST API client library for Ruby
+email: dblock@dblock.org
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.rdoc
+files:
+- lib/pixmatch.rb
+- lib/pixmatch/api.rb
+- lib/pixmatch/client.rb
+- lib/pixmatch/client/add.rb
+- lib/pixmatch/client/count.rb
+- lib/pixmatch/client/delete.rb
+- lib/pixmatch/client/list.rb
+- lib/pixmatch/client/ping.rb
+- lib/pixmatch/client/search.rb
+- lib/pixmatch/configuration.rb
+- lib/pixmatch/error.rb
+- lib/pixmatch/request.rb
+- lib/pixmatch/utils.rb
+- lib/pixmatch/version.rb
+- LICENSE.txt
+- README.rdoc
+- spec/pixmatch_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/dblock/pixmatch
+licenses:
+- MIT
+post_install_message: !!null 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -137474991
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+requirements: []
+rubyforge_project: !!null 
+rubygems_version: 1.3.7
+signing_key: !!null 
+specification_version: 3
+summary: Pixmatch REST API client library for Ruby
+test_files:
+- spec/pixmatch_spec.rb
+- spec/spec_helper.rb