deepstack 1.4.0 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '02929889eabbeeb8b76cd2f588cef7452ef0bb6dd3687fad749105e6956191e9'
-  data.tar.gz: 2625f0bc5aac522d23461530dda2e581718c4f967c053db13c13ff0dcaa46f92
+  metadata.gz: 8894b856fe894840f7b0178501000f4bd3c05dc0f8e5d3199f3782ac3bfbff86
+  data.tar.gz: 4e42c6f313e00d6c909de463c7a5a3874861d48a06a73c62970c5a064beedf7c
 SHA512:
-  metadata.gz: fd37e76b9ad0fd30ddcc8a995fe2267d01f056cb3aa3a1d134b6335d91b6b300f61ce9929ab6b2e183ead1036135d2854a53858306395caadfaca7f2baf083d2
-  data.tar.gz: 275bba97d88a57d51de45a0ae2be230df5d2a8c749324ea748cd2a16c9e45de9c8f6c44d0d61fd860985400093e1caec636f1905bfbcab680631b39087bfbffa
+  metadata.gz: 6eff77cc8ea43965ba5ba60aaccc2eea39839d7986ff5c88304f7a09dd12487d758b83b62743a216b6bb98a1f1f27807815b3c0dcef085573b6878809c6eea89
+  data.tar.gz: aa7f18c4fbfb6e1cac966f315c540bcbb08e9d52d391283d264df849b78ad0a1b442ea0217d8ced45e888882b0260f156cd4a8768aaeec21cf5f744bc62669cc

data/README.md

@@ -0,0 +1,78 @@
+# DeepStack Ruby Wrapper
+
+A Ruby wrapper for [DeepStack](https://www.deepstack.cc/) HTTP API
+
+## Usage
+
+Install the gem with `gem install deepstack`
+
+~~~ ruby
+require 'deepstack'
+
+deepstack = DeepStack.new('http://192.168.1.10:2000')
+image = File.read('image.jpg')
+
+# Find bounding rects for objects
+predictions = deepstack.detect_objects(image) 
+# => [{"confidence"=>0.86599416, "label"=>"dog", "y_min"=>355, "x_min"=>648, "y_max"=>540, "x_max"=>797},
+#     {"confidence"=>0.918332, "label"=>"person", "y_min"=>113, "x_min"=>442, "y_max"=>524, "x_max"=>601},
+#     {"confidence"=>0.9292374, "label"=>"person", "y_min"=>83, "x_min"=>294, "y_max"=>521, "x_max"=>447}]
+
+# Find bounding rects for faces
+faces = deepstack.detect_faces(image)
+# => [{"confidence"=>0.86419886, "y_min"=>236, "x_min"=>876, "y_max"=>730, "x_max"=>1203},
+#     {"confidence"=>0.8811783, "y_min"=>164, "x_min"=>1617, "y_max"=>692, "x_max"=>1985}]
+
+# Register a face for face recognition
+deepstack.register_face('face1', image)
+
+# List all the registered faces in the system
+face_list = deepstack.face_list
+# => ["face1", "face2"]
+
+# Perform a face recognition, return identified userids
+faces = deepstack.recognize_face(image)
+# => [{"confidence"=>0, "userid"=>"unknown", "y_min"=>236, "x_min"=>876, "y_max"=>730, "x_max"=>1203},
+#     {"confidence"=>0.9824197, "userid"=>"face1", "y_min"=>164, "x_min"=>1617, "y_max"=>692, "x_max"=>1985}]
+
+# Delete a face from the system
+deepstack.delete_face('face1')
+
+# Detect similarities between two face images
+image2 = File.read('image2.jpg')
+similarity = deepstack.face_match(image, image2)
+# => 0.3333
+
+# Perform Scene recognition
+scene = deepstack.identify_scene(image)
+# => {"success"=>true, "confidence"=>0.27867314, "label"=>"archive", "duration"=>0}
+~~~
+
+### Error Handling
+
+The methods will:
+
+* Raise an exception on a connection error.
+* Return nil when DeepStack reports failure (`success=false`)
+
+See the [documentation](https://www.rubydoc.info/gems/deepstack) for more details.
+
+## Development
+
+A Linux development machine is needed in order to run the tests. The test will launch DeepStack docker instances
+to test against. By default, the deepstack docker will listen on ports `8001`-`8004`. 
+To change this, copy `rakelib/deepstack.yml.sample` to `rakelib/deepstack.yml` and change the port numbers as required.
+
+To run the tests run `rake`.
+
+To manually stop the DeepStack docker instance, run `rake deepstack:stop`
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/jimtng/deepstack-ruby).
+
+## License
+
+The gem is available as open source under the terms of the EPL 2.0 License

data/lib/deep_stack/deep_stack.rb

@@ -6,29 +6,53 @@ require_relative 'face'
 require_relative 'detection'
 require_relative 'scene'
 require_relative 'custom_model'
+require_relative 'image'
 require_relative 'version'
 
-# DeepStack API
+#
+# DeepStack API wrapper
+#
+# All the methods that communicate with the server can raise an +Errno::ECONNREFUSED+ exception
+# if the server is down or the connection details are incorrect.
+#
 class DeepStack
   include DeepStack::Face
   include DeepStack::Detection
   include DeepStack::Scene
+  include DeepStack::Image
   include DeepStack::CustomModel
 
   #
-  # Create a deepstack object connected to the given URL
+  # Create a deepstack object for the given server URL. HTTP connections are not made within the constructor
+  # so the deepstack object can be created against a server that's currently down without
+  # raising an exception.
+  #
+  # A persistent HTTP connection will be initiated on the first method request.
   #
   # @param [String] base_url the url to DeepStack's server:port
-  # @param [String] api_key an optional API-KEY to use when connecting to DeepStack
-  # @param [String] admin_key an optional ADMIN-KEY to use when connecting to DeepStack
+  # @param [String] api_key an optional +API-KEY+ to use when connecting to DeepStack
+  # @param [String] admin_key an optional +ADMIN-KEY+ to use when connecting to DeepStack
+  # @param [Integer] verify_mode sets the flags for server the certification verification at
+  #                  beginning of an SSL/TLS session.
+  #                  +OpenSSL::SSL::VERIFY_NONE+ or +OpenSSL::SSL::VERIFY_PEER+ are acceptable.
+  #                  The default is +OpenSSL::SSL::VERIFY_PEER+.
   #
   # @example
   #   DeepStack.new('http://127.0.0.1:5000')
   #
-  def initialize(base_url, api_key: nil, admin_key: nil)
+  #   # Using an API KEY
+  #   DeepStack.new('http://127.0.0.1:5000', api_key: 'secret', admin_key: 'supersecret')
+  #
+  #   # SSL connection with a self-signed certificate
+  #   DeepStack.new('https://localhost:443', verify_mode: OpenSSL::SSL::VERIFY_NONE)
+  #
+  def initialize(base_url, api_key: nil, admin_key: nil, verify_mode: nil)
     @base_url = base_url
     @auth = { api_key: api_key, admin_key: admin_key }.select { |_k, v| v } # remove nil values
-    @http_mutex = Mutex.new
+    uri = URI(base_url)
+    @http = Net::HTTP.new(uri.hostname, uri.port)
+    @http.use_ssl = uri.instance_of?(URI::HTTPS)
+    @http.verify_mode = verify_mode if verify_mode
   end
 
   #
@@ -57,12 +81,12 @@ class DeepStack
   end
 
   #
-  # Close the HTTP connection to DeepStack server
+  # Close the persistent HTTP connection to DeepStack server. This should be called after
+  # a period of inactivity to close the TCP connection. Subsequent API calls will
+  # re-open the connection automatically.
   #
   def close
-    @http_mutex.synchronize do
-      @http.finish if @http&.started?
-    end
+    @http.finish if @http&.started?
   end
 
   private
@@ -79,11 +103,8 @@ class DeepStack
     form_data = combine_images_and_args(images.flatten, **args)
     req = Net::HTTP::Post.new(uri)
     req.set_form(form_data, 'multipart/form-data')
-    @http_mutex.synchronize do
-      @http ||= Net::HTTP.start(uri.hostname, uri.port)
-      @http.start unless @http.started?
-      @http.request(req)
-    end
+    @http.start unless @http.started?
+    @http.request(req)
   end
 
   def combine_images_and_args(*images, **args)

data/lib/deep_stack/face.rb

@@ -86,8 +86,8 @@ class DeepStack
     #   image2 = File.read('obama2.jpg')
     #   puts deepstack.face_match(image1, image2) > 0.6 ? 'similar' : 'different'
     #
-    # @param [Array] *images two images to compare
-    # @param [kwargs] **args optional arguments to the API call
+    # @param [Array] images two images to compare
+    # @param [kwargs] args optional arguments to the API call
     #
     # @return [Float] The similarity score (0-1)
     # @return [nil] if failed

data/lib/deep_stack/image.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+class DeepStack
+  # Support Image Enhance feature
+  module Image
+    #
+    # Enhance image {https://docs.deepstack.cc/api-reference/index.html#image-enhance}
+    #
+    # @param [Image] image the raw image data or a File object of an image file
+    #
+    # @return [Image] the enhanced image object
+    # @return [nil] if failed
+    #
+    def enhance_image(image)
+      target = 'vision/enhance'
+      result = api_post(target, image)
+      return unless result&.dig('success') == true
+
+      Base64.decode64(result['base64'])
+    end
+  end
+end

data/lib/deep_stack/scene.rb

@@ -4,14 +4,15 @@ class DeepStack
   # Scene Recognition
   module Scene
     #
-    # Return
+    # Call the scene recognition API to classify an image into one of the supported scenes.
     #
     # @param [Object] image binary data or a File object
     # @param [Hash] options additional fields for DeepStack, e.g. min_confidence: 0.5
     #
-    # @return [Hash] if successful, DeepStack result hash {'label' => 'scene', 'confidence' => 2.2}
+    # @return [Hash] if successful, DeepStack result hash +{'label' => 'scene', 'confidence' => 2.2}+
     #
     # @return [nil] if error
+    #
     def identify_scene(image, **options)
       target = 'vision/scene'
       api_post(target, image, **options)

data/lib/deep_stack/version.rb

@@ -5,5 +5,5 @@
 #
 class DeepStack
   # @return [String] Version of DeepStack helper libraries
-  VERSION = '1.4.0'
+  VERSION = '1.6.1'
 end

data/spec/deepstack_spec.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require 'rake'
+require 'pp'
+require 'deepstack'
+
+Rake.application.rake_require 'docker_support', ['rakelib']
+Rake.application.rake_require 'deepstack', ['rakelib']
+
+# http is used in persistence check below
+class DeepStack
+  attr_reader :http
+end
+
+def deepstack
+  @deepstack ||= DeepStack.new("http://localhost:#{port[:no_auth][:http]}")
+end
+
+def auth_deepstack
+  @auth_deepstack ||= DeepStack.new("http://localhost:#{port[:auth][:http]}", api_key: 'myapikey',
+                                                                              admin_key: 'myadminkey')
+end
+
+def deepstack_ssl
+  @deepstack_ssl ||= DeepStack.new("https://localhost:#{port[:no_auth][:https]}",
+                                   verify_mode: OpenSSL::SSL::VERIFY_NONE)
+end
+
+def restart_deepstack_server
+  Rake::Task['deepstack:stop1'].execute
+  Rake::Task['deepstack:stop2'].execute
+  Rake::Task['deepstack:stop3'].execute
+  Rake::Task['deepstack:start'].execute
+end
+
+# rubocop:disable Metrics/BlockLength
+RSpec.describe DeepStack do
+  image = File.read('spec/test_images/person-dog.jpg')
+
+  context 'Basic Usage' do
+    it 'can be initialized with a url' do
+      expect(deepstack).not_to be_nil
+    end
+
+    it 'can close and reopen its http connection' do
+      result = deepstack.face_list
+      expect(result).to be_an Array
+      expect(deepstack.http.started?).to be true
+      deepstack.close
+      expect(deepstack.http.started?).to be false
+      result = deepstack.face_list
+      expect(deepstack.http.started?).to be true
+      expect(result).to be_an Array
+      expect(deepstack.http.started?).to be true
+    end
+
+    it 'can recover from a server restart' do
+      result = deepstack.face_list
+      expect(result).to be_an Array
+
+      Rake::Task['deepstack:stop1'].execute
+      expect { deepstack.face_list }.to raise_exception(Errno::ECONNREFUSED)
+      Rake::Task['deepstack:start'].execute
+      sleep 1
+
+      result = deepstack.face_list
+      expect(result).to be_an Array
+    end
+
+    it 'can work with an api key' do
+      result = auth_deepstack.detect_objects(image)
+      expect(result).to be_an Array
+    end
+
+    it 'can use ssl' do
+      result = deepstack_ssl.face_list
+      expect(result).to be_an Array
+    end
+
+    it 'does not raise an exception in its constructor' do
+      result = DeepStack.new('http://192.168.254.254')
+      expect(result).to be_truthy
+    end
+  end
+
+  context 'Object Detection' do
+    it 'can detect objects' do
+      result = deepstack.detect_objects(image)
+      # pp result
+      expect(result).to be_an Array
+      expect(result.size).to be > 0
+      expect(result.first).to be_a Hash
+      expect(result.first.keys).to include(*%w[confidence label x_max x_min y_max y_min])
+    end
+  end
+
+  context 'Face Detection' do
+    it 'can detect faces' do
+      result = deepstack.detect_faces(image)
+      # pp result
+      expect(result).to be_an Array
+      expect(result.first).to be_a Hash
+      expect(result.first.keys).to include(*%w[confidence x_min y_min x_max y_max])
+    end
+  end
+
+  context 'Face Recognition' do
+    it 'can return a list of registered faces' do
+      faces = deepstack.face_list
+      expect(faces).to be_an Array
+    end
+
+    it 'can register a face with one image object' do
+      # image = File.read('spec/test_images/idriselba3.jpeg')
+      result = deepstack.register_face('user1', image)
+      expect(result).to be true
+
+      faces = deepstack.face_list
+      expect(faces).to include 'user1'
+    end
+
+    it 'can register a face given a File object of an image file' do
+      result = File.open('spec/test_images/person-dog.jpg') do |img|
+        deepstack.register_face('user2', img)
+      end
+      expect(result).to be true
+
+      faces = deepstack.face_list
+      expect(faces).to include 'user2'
+    end
+
+    it 'can register a face with multiple image objects' do
+      face_count_before = deepstack.face_list.size
+      images = []
+      images << File.read('spec/test_images/person-dog.jpg')
+      images << File.read('spec/test_images/person-dog.jpg')
+      images << File.read('spec/test_images/person-dog.jpg')
+
+      result = deepstack.register_face('user3', images)
+      expect(result).to be true
+
+      faces = deepstack.face_list
+      expect(faces).to include 'user3'
+      expect(faces.size).to be > face_count_before
+    end
+
+    it 'can register multiple faces/users' do
+      deepstack.delete_faces(deepstack.face_list)
+      faces = deepstack.face_list
+      expect(faces.size).to be 0
+
+      3.times do |i|
+        deepstack.register_face("user#{i}", image)
+      end
+      faces = deepstack.face_list
+      expect(faces.size).to be 3
+
+      3.times do |i|
+        expect(faces).to include "user#{i}"
+      end
+    end
+
+    it 'can recognize faces from an image' do
+      result = deepstack.recognize_faces(image)
+      # pp result
+      expect(result).to be_an Array
+      expect(result.first.keys).to include(*%w[confidence userid x_min y_min x_max y_max])
+    end
+
+    it 'can delete a registered face' do
+      face_count_before = deepstack.face_list.size
+      result = deepstack.delete_face('user1')
+      expect(result).to be true
+      expect(deepstack.face_list.size).to be < face_count_before
+    end
+
+    it 'can delete all registered faces' do
+      faces = deepstack.face_list
+      expect(faces.size).to be > 0
+      result = deepstack.delete_faces(faces)
+      expect(result).to be_a Hash
+      faces = deepstack.face_list
+      expect(faces.size).to eq 0
+    end
+
+    it 'can perform face matching' do
+      image2 = image
+      result = deepstack.face_match(image, image2)
+      expect(result).to be_a_kind_of(Numeric)
+    end
+  end
+
+  context 'Scene Recognition' do
+    it 'can detect scene' do
+      result = deepstack.identify_scene(image)
+      expect(result).to be_a Hash
+      # pp result
+      expect(result.keys).to include(*%w[confidence label])
+    end
+  end
+
+  # context 'Image Enhancer' do
+  #   # before { skip('Skipping because this test is slow') }
+  #   it 'can enhance image' do
+  #     result = deepstack.enhance_image(image)
+  #     expect(result).to be_truthy
+  #   end
+  # end
+
+  context 'Custom Model' do
+    it 'can use a custom model' do
+      result = deepstack.custom_model('combined', image)
+      expect(result).to be_an Array
+    end
+  end
+end
+# rubocop:enable Metrics/BlockLength

metadata

@@ -1,15 +1,99 @@
 --- !ruby/object:Gem::Specification
 name: deepstack
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.6.1
 platform: ruby
 authors:
 - Jimmy Tanagra
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-05-11 00:00:00.000000000 Z
-dependencies: []
+date: 2022-05-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - jcode@tanagra.id.au
@@ -17,13 +101,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - lib/deep_stack/custom_model.rb
 - lib/deep_stack/deep_stack.rb
 - lib/deep_stack/detection.rb
 - lib/deep_stack/face.rb
+- lib/deep_stack/image.rb
 - lib/deep_stack/scene.rb
 - lib/deep_stack/version.rb
 - lib/deepstack.rb
+- spec/deepstack_spec.rb
 homepage: https://github.com/jimtng/deepstack-ruby
 licenses:
 - EPL-2.0
@@ -51,4 +138,5 @@ rubygems_version: 3.0.3.1
 signing_key: 
 specification_version: 4
 summary: A Ruby wrapper for DeepStack API
-test_files: []
+test_files:
+- spec/deepstack_spec.rb