deepstack 1.6.0 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 830f650f0001d9ace30cbcf6758aa58cae9d4bf7089300f0e22261e58274e1cb
-  data.tar.gz: 2a9b1c9d03f3c04d6f159f9216b85791904f8c279155c9142bf5248eb719769a
+  metadata.gz: 8894b856fe894840f7b0178501000f4bd3c05dc0f8e5d3199f3782ac3bfbff86
+  data.tar.gz: 4e42c6f313e00d6c909de463c7a5a3874861d48a06a73c62970c5a064beedf7c
 SHA512:
-  metadata.gz: fc573a46b62325ef299af50d25a7c9c760df25025f87f1c8c1eb588a3ee148fceb38ace946d3d39e92236d48c96da4f474a239ecfc2821660886e6f020b77ea4
-  data.tar.gz: '08e0a71c109b87a81ef475aa85e8ea2750ed615adf65a03299b4b3df805911fac898597f94a4cdb5aa597fa03fab6367ccf04004c7545980e3a6b2261ff86d1d'
+  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

@@ -9,7 +9,12 @@ 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
@@ -18,31 +23,36 @@ class DeepStack
   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] api_key an optional API-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 SSL/TLS session.
+  #                  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')
   #
-  #   # Using API KEY:
+  #   # Using an API KEY
   #   DeepStack.new('http://127.0.0.1:5000', api_key: 'secret', admin_key: 'supersecret')
   #
-  #   # Connect to SSL with a self-signed certificate
+  #   # 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
     uri = URI(base_url)
-    http_options = {}
-    http_options[:verify_mode] = verify_mode if verify_mode
-    @http = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.instance_of?(URI::HTTPS), **http_options)
+    @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
 
   #
@@ -71,7 +81,9 @@ 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.finish if @http&.started?

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/version.rb

@@ -5,5 +5,5 @@
 #
 class DeepStack
   # @return [String] Version of DeepStack helper libraries
-  VERSION = '1.6.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.6.0
+  version: 1.6.1
 platform: ruby
 authors:
 - Jimmy Tanagra
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-05-12 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,6 +101,7 @@ 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
@@ -25,6 +110,7 @@ files:
 - 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
@@ -52,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