remove_bg 1.4.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 728a996008009c54dc10d72f0b0db353b1156182a8379c51ed0cf5f9fbe4b27e
-  data.tar.gz: 991a7201af58af739e73af965d082b43a0427d79878e0db2f17d13c3ac575053
+  metadata.gz: 47f8cd273ddfe8639badf0fd59050342af16e542a508162f77fbec7b7a2a5dd4
+  data.tar.gz: 5adcc396f765f7a4858e7c7c4d82d7610b5d42e2200401be29b5ea543f5fdc88
 SHA512:
-  metadata.gz: 2800e1a449e12e3168c7e15d9fd85b8424434ff568821600464a05d6448529e22514ab1e80cdd7c76c7a6ab91e45db01f99b7a7e7dab617d00b797f6788aa872
-  data.tar.gz: 556b0ded824694cffb639cab278eb00ffea8df314c5beee20a2565528671d8548fb856a3d14a52af73c5147f54d016b457268101046ce6c75647fb0a6b606c61
+  metadata.gz: 4ad4065335850911ee8b45604ed0de465742bdf183078d0ae4e9de52fb1f77519d4d9bd5aa7a042d04e9c0960a8af4f3d0e84cfdb49c6ae48e773626c6ad9639
+  data.tar.gz: a265d257a9e77bd9d87b9ef42c2aff4b0d7b8b7b3482a8717a44b4d3192c5064b0e4e67e62b9d513ecbb67e317c8b470db19194b350ade66d73b602b6ec9a7c8

data/.circleci/config.yml

@@ -56,6 +56,8 @@ jobs:
       - image: circleci/ruby:2.6
   ruby-2.7:
     <<: *base_job
+    environment:
+      UPLOAD_COVERAGE: 1
     docker:
       - image: circleci/ruby:2.7
 

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+
+## 1.5.0
+
+- Auto-detect any available image processing libraries
+- Reduce bandwidth usage by using ZIP format where possible
+
 ## 1.4.1
 
 - Fixes binary encoding issue - via [#15](https://github.com/remove-bg/ruby/pull/15)

data/Gemfile.lock

@@ -11,7 +11,7 @@ GIT
 PATH
   remote: .
   specs:
-    remove_bg (1.4.1)
+    remove_bg (1.5.0)
       faraday (>= 0.15, < 2)
       image_processing (>= 1.9, < 2)
       rubyzip (>= 2.0, < 3)
@@ -21,18 +21,24 @@ GEM
   specs:
     addressable (2.7.0)
       public_suffix (>= 2.0.2, < 5.0)
+    codecov (0.1.16)
+      json
+      simplecov
+      url
     coderay (1.1.2)
     crack (0.4.3)
       safe_yaml (~> 1.0.0)
     diff-lcs (1.3)
+    docile (1.3.2)
     dotenv (2.7.5)
     faraday (1.0.1)
       multipart-post (>= 1.2, < 3)
-    ffi (1.12.2)
+    ffi (1.13.1)
     hashdiff (1.0.1)
     image_processing (1.11.0)
       mini_magick (>= 4.9.5, < 5)
       ruby-vips (>= 2.0.17, < 3)
+    json (2.3.0)
     method_source (1.0.0)
     mini_magick (4.10.1)
     multipart-post (2.1.1)
@@ -47,7 +53,7 @@ GEM
       rspec-mocks (~> 3.9.0)
     rspec-core (3.9.2)
       rspec-support (~> 3.9.3)
-    rspec-expectations (3.9.1)
+    rspec-expectations (3.9.2)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.9.0)
     rspec-mocks (3.9.1)
@@ -62,12 +68,20 @@ GEM
       ffi (~> 1.9)
     rubyzip (2.3.0)
     safe_yaml (1.0.5)
+    simplecov (0.18.5)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+    simplecov-html (0.12.2)
     thor (1.0.1)
+    url (0.3.2)
     vcr (5.1.0)
+    vcr_better_binary (0.1.0)
+      vcr (~> 5.0)
     webmock (3.8.3)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.25)
 
 PLATFORMS
   ruby
@@ -75,6 +89,7 @@ PLATFORMS
 DEPENDENCIES
   appraisal!
   bundler (~> 2.0)
+  codecov
   dotenv
   pry
   rake
@@ -82,8 +97,11 @@ DEPENDENCIES
   rspec (~> 3.8)
   rspec-with_params
   rspec_junit_formatter
+  simplecov
   vcr
+  vcr_better_binary
   webmock
+  yard
 
 BUNDLED WITH
    2.1.4

data/README.md

@@ -2,16 +2,58 @@
 
 # Ruby library
 
-[![CircleCI](https://circleci.com/gh/remove-bg/ruby/tree/master.svg?style=shield)](https://circleci.com/gh/remove-bg/ruby/tree/master) [![Gem Version](https://badge.fury.io/rb/remove_bg.svg)](https://rubygems.org/gems/remove_bg)
+[![CircleCI](https://circleci.com/gh/remove-bg/ruby/tree/master.svg?style=shield)](https://circleci.com/gh/remove-bg/ruby/tree/master) [![Gem Version](https://badge.fury.io/rb/remove_bg.svg)](https://rubygems.org/gems/remove_bg) [![codecov](https://codecov.io/gh/remove-bg/ruby/branch/master/graph/badge.svg)](https://codecov.io/gh/remove-bg/ruby)
 
-## Installation
+## Quickstart installation
 
-- Add `gem "remove_bg"` to your application's Gemfile and then execute `bundle`.
-- Or install it yourself as: `gem install remove_bg`
+Add the gem to your `Gemfile` and run `bundle install`:
 
-## Usage
+```
+gem "remove_bg"
+```
+
+Or run `gem install remove_bg` to install globally.
+
+Please note the base configuration has the following resolution limits:
+
+| Output format | Resolution limit |
+|---------------|------------------|
+| PNG           | 10 megapixels    |
+| JPG           | 25 megapixels    |
+
+## Full installation
+
+For best performance and quality the gem requires an image processing library.
+Please install one of the following libraries:
+
+- [ImageMagick](https://www.imagemagick.org/)
+- [GraphicsMagick](http://www.graphicsmagick.org/)
+- [libvips](http://libvips.github.io/libvips/)
+
+The gem will auto-detect any image processing libraries present. However you may
+prefer to explicitly configure which library to use:
+
+```ruby
+RemoveBg.configure do |config|
+  config.image_processor = :minimagick # For ImageMagick or GraphicsMagick
+  # or
+  config.image_processor = :vips
+end
+```
+
+The full installation has the following resolution limits:
+
+| Output format | Resolution limit |
+|---------------|------------------|
+| PNG           | 25 megapixels    |
+| JPG           | 25 megapixels    |
+| ZIP           | 25 megapixels    |
 
-### Configuring an API key
+# Usage
+
+For more in-depth documentation please see [RubyDoc](https://www.rubydoc.info/gems/remove_bg)
+
+## Configuring an API key
 
 To configure a global API key (used by default unless overridden per request):
 
@@ -25,7 +67,7 @@ It's not recommended to commit your API key to version control. You may want to
 read the API key from an environment variable (e.g.
 `ENV.fetch("REMOVE_BG_API_KEY")`) or find an alternative method.
 
-### Removing the background from an image
+## Removing the background from an image
 
 Currently the gem supports removing the background from a file or a URL:
 
@@ -34,7 +76,7 @@ RemoveBg.from_file("image.png")
 RemoveBg.from_url("http://example.com/image.png")
 ```
 
-#### Request options
+## Request options
 
 The processing options outlined in the [API reference](https://www.remove.bg/api)
 can be specified per request:
@@ -49,7 +91,7 @@ The API key can also be specified per request:
 RemoveBg.from_file("image.png", api_key: "<api-key>")
 ```
 
-#### Handling the result
+## Handling the result
 
 Background removal requests return a result object which includes the processed
 image data and the metadata about the operation.
@@ -69,30 +111,13 @@ result.save("processed/image.png")
 result.save("image.png", overwrite: true) # Careful!
 ```
 
-#### Processing images over 10 megapixels
-
-The Remove.bg API provides a [ZIP format](https://www.remove.bg/api#zip-format)
-which includes all the information required to efficiently composite a large
-image with transparency.
+## Producing transparent images over 10 megapixels
 
-The gem can handle this composition for you, but you'll need
-[ImageMagick]/[GraphicsMagick] or [libvips] available on your computer.
+After configuring a full installation (detailed above) you can process images
+over 10 megapixels with a transparent output.
 
-[ImageMagick]: https://www.imagemagick.org
-[GraphicsMagick]: http://www.graphicsmagick.org
-[libvips]: http://libvips.github.io/libvips/
-
-Please configure the image processing library you'd like to use:
-
-```ruby
-RemoveBg.configure do |config|
-  config.image_processor = :minimagick # For ImageMagick or GraphicsMagick
-  # or
-  config.image_processor = :vips
-end
-```
-
-Then process images specifying the `zip` format:
+Process images with either the `png` or `zip` format. If you specify the `zip`
+format it's possible to save the archive and handle composition yourself.
 
 ```ruby
 result = RemoveBg.from_file("large-image.jpg", format: "zip")
@@ -102,7 +127,7 @@ result.save("result-with-transparency.png")
 result.save_zip("result.zip") # If you want to handle composition yourself
 ```
 
-#### Rate limits
+## Rate limits
 
 The [API has rate limits][rate-limits]. Image processing results include the
 rate limit information:
@@ -118,7 +143,7 @@ raised. This also contains further information via the `#rate_limit` method.
 
 [rate-limits]: https://www.remove.bg/api#rate-limit
 
-### Fetching account information
+## Fetching account information
 
 To display the [account information][account-info] for the currently configured
 API key:
@@ -150,11 +175,22 @@ Bug reports and pull requests are welcome on GitHub at [remove-bg/ruby](https://
 
 ## Development
 
+### Setup
+
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
 `rake spec` to run the tests.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To
-release a new version, update the version number in `version.rb`, and then run
+### Releasing a new version
+To release a new version, update the version number in `version.rb`, and then run
 `bundle exec rake release`, which will create a git tag for the version, push
 git commits and tags, and push the `.gem` file to
 [rubygems.org](https://rubygems.org).
+
+### Documentation
+
+To preview the [YARD documentation](https://yardoc.org/) locally run:
+
+```
+bundle exec yard server --reload
+open http://localhost:8808/
+```

data/lib/remove_bg.rb

@@ -4,21 +4,38 @@ require "remove_bg/configuration"
 require "remove_bg/request_options"
 
 module RemoveBg
+  # Removes the background from an image on the local file system
+  # @param image_path [String] Path to the input image
+  # @param options [Hash<Symbol, Object>] Image processing options (see API docs)
+  # @return [RemoveBg::Result|RemoveBg::CompositeResult] a processed image result
+  #
   def self.from_file(image_path, raw_options = {})
     options = RemoveBg::RequestOptions.new(raw_options)
     ApiClient.new.remove_from_file(image_path, options)
   end
 
+  # Removes the background from the image at the URL specified
+  # @param image_url [String] Absolute URL of the input image
+  # @param options [Hash<Symbol, Object>] Image processing options (see API docs)
+  # @return [RemoveBg::Result|RemoveBg::CompositeResult] A processed image result
+  #
   def self.from_url(image_url, raw_options = {})
     options = RemoveBg::RequestOptions.new(raw_options)
     ApiClient.new.remove_from_url(image_url, options)
   end
 
+  # Fetches account information for the globally configured API key, or a
+  # specific API key if provided
+  # @param options [Hash<Symbol, Object>]
+  # @return [RemoveBg::AccountInfo]
+  #
   def self.account_info(raw_options = {})
     options = RemoveBg::BaseRequestOptions.new(raw_options)
     ApiClient.new.account_info(options)
   end
 
+  # Yields the global Remove.bg configuration
+  # @yield [RemoveBg::Configuration]
   def self.configure
     yield RemoveBg::Configuration.configuration
   end

data/lib/remove_bg/account_info.rb

@@ -1,6 +1,10 @@
 module RemoveBg
   class AccountInfo
-    attr_reader :api, :credits
+    # @return [RemoveBg::AccountInfo::ApiInfo]
+    attr_reader :api
+
+    # @return [RemoveBg::AccountInfo::CreditsInfo]
+    attr_reader :credits
 
     def initialize(attributes)
       @api = ApiInfo.new(**attributes.fetch(:api))

data/lib/remove_bg/api_client.rb

@@ -16,21 +16,40 @@ module RemoveBg
   class ApiClient
     include RemoveBg::Api
 
+    # @param connection [Faraday::Connection]
+    #
     def initialize(connection: RemoveBg::HttpConnection.build)
       @connection = connection
     end
 
+    # Removes the background from an image on the local file system
+    # @param image_path [String]
+    # @param options [RemoveBg::RequestOptions]
+    # @return [RemoveBg::Result|RemoveBg::CompositeResult]
+    # @raise [RemoveBg::Error]
+    #
     def remove_from_file(image_path, options)
       data = options.data.merge(image_file: Upload.for_file(image_path))
       request_remove_bg(data, options.api_key)
     end
 
+    # Removes the background from the image at the URL specified
+    # @param image_url [String]
+    # @param options [RemoveBg::RequestOptions]
+    # @return [RemoveBg::Result|RemoveBg::CompositeResult]
+    # @raise [RemoveBg::Error]
+    #
     def remove_from_url(image_url, options)
       RemoveBg::UrlValidator.validate(image_url)
       data = options.data.merge(image_url: image_url)
       request_remove_bg(data, options.api_key)
     end
 
+    # Fetches account information
+    # @param options [RemoveBg::BaseRequestOptions]
+    # @return [RemoveBg::AccountInfo]
+    # @raise [RemoveBg::Error]
+    #
     def account_info(options)
       request_account_info(options.api_key)
     end

data/lib/remove_bg/composite_result.rb

@@ -1,7 +1,17 @@
 require_relative "result"
 
 module RemoveBg
+  # Handles image composition for larger images (over 10MP) where transparency is
+  # required.
+  # @see RemoveBg::Result
+  #
   class CompositeResult < Result
+    # Saves the ZIP archive containing the alpha.png and color.jpg files
+    # (useful if you want to handle composition yourself)
+    # @param file_path [string]
+    # @param overwrite [boolean] Overwrite any existing file at the specified path
+    # @return [nil]
+    #
     def save_zip(file_path, overwrite: false)
       if File.exist?(file_path) && !overwrite
         raise FileOverwriteError.new(file_path)

data/lib/remove_bg/configuration.rb

@@ -1,13 +1,24 @@
+require_relative "image_composer"
+
 module RemoveBg
   class Configuration
-    attr_accessor :api_key, :image_processor
+    attr_accessor :api_key, :image_processor, :auto_upgrade_png_to_zip
 
     def self.configuration
-      @configuration ||= Configuration.new
+      @configuration ||= Configuration.new.tap do |config|
+        config.image_processor = ImageComposer.detect_image_processor
+
+        # Upgrade to ZIP where possible to save bandwith
+        config.auto_upgrade_png_to_zip = true
+      end
     end
 
     def self.reset
-      @configuration = Configuration.new
+      @configuration = nil
+    end
+
+    def can_process_images?
+      !image_processor.nil?
     end
   end
 end

data/lib/remove_bg/error.rb

@@ -2,7 +2,11 @@ module RemoveBg
   class Error < StandardError; end
 
   class HttpError < Error
-    attr_reader :http_response, :http_response_body
+    # @return [Faraday::Response]
+    attr_reader :http_response
+
+    # @return [String]
+    attr_reader :http_response_body
 
     def initialize(message, http_response, http_response_body)
       @http_response = http_response
@@ -11,9 +15,13 @@ module RemoveBg
     end
   end
 
+  # Raised for all HTTP 4XX errors
   class ClientHttpError < HttpError; end
+
+  # Raised for all HTTP 5XX errors
   class ServerHttpError < HttpError; end
 
+  # Raised for HTTP 429 status code
   class RateLimitError < ClientHttpError
     attr_reader :rate_limit
 

data/lib/remove_bg/http_connection.rb

@@ -8,6 +8,8 @@ module RemoveBg
     HTTP_BASE_TIMEOUT = 10
     HTTP_WRITE_TIMEOUT = 120
 
+    # @return [Faraday::Connection]
+    #
     def self.build(api_url = RemoveBg::Api::URL)
       retry_options = {
         max: 2,

data/lib/remove_bg/image_composer.rb

@@ -1,7 +1,25 @@
 require_relative "error"
 
 module RemoveBg
+  # Combines alpha.png and color.jpg files to produce a full-sized transparent PNG.
+  # An image processing library (ImageMagick, GraphicsMagick, or libvips) must
+  # be available on the system.
+  # @see RemoveBg::CompositeResult
+  #
   class ImageComposer
+    DEFAULT_BINARY_DETECTOR = lambda do |binary_name|
+      system("which", binary_name, out: File::NULL)
+    end
+
+    def self.detect_image_processor(detector: DEFAULT_BINARY_DETECTOR)
+      case
+      when detector.call("magick"), detector.call("convert"), detector.call("gm")
+        :minimagick
+      when detector.call("vips")
+        :vips
+      end
+    end
+
     def compose(color_file:, alpha_file:, destination_path:)
       image = case configured_image_processor
         when :vips

data/lib/remove_bg/request_options.rb

@@ -1,6 +1,8 @@
 require_relative "base_request_options"
 
 module RemoveBg
+  # Options for image processing requests. Arbitary options are passed directly to the API.
+  #
   class RequestOptions < BaseRequestOptions
     SIZE_REGULAR = "regular"
     SIZE_MEDIUM = "medium"
@@ -15,10 +17,40 @@ module RemoveBg
     CHANNELS_RGBA = "rgba"
     CHANNELS_ALPHA = "alpha"
 
+    FORMAT_PNG = "png"
+    FORMAT_ZIP = "zip"
+    FORMAT_JPG = "jpg"
+
     def initialize(raw_options = {})
       options = raw_options.dup
       options[:size] ||= SIZE_AUTO
+
+      if options.key?(:format)
+        options[:format] = optimize_format(options[:format])
+      end
+
       super(options)
     end
+
+    private
+
+    # Save bandwidth where possible
+    def optimize_format(requested_format)
+      requested_png = requested_format.to_s.casecmp?(FORMAT_PNG)
+
+      if requested_png && optimization_enabled? && can_process_images?
+        FORMAT_ZIP
+      else
+        requested_format
+      end
+    end
+
+    def can_process_images?
+      RemoveBg::Configuration.configuration.can_process_images?
+    end
+
+    def optimization_enabled?
+      RemoveBg::Configuration.configuration.auto_upgrade_png_to_zip
+    end
   end
 end

data/lib/remove_bg/result.rb

@@ -5,10 +5,17 @@ require_relative "error"
 require_relative "image_composer"
 
 module RemoveBg
+  # Provides convenience methods to save the processed image, read the image data,
+  # and access metadata such as the image height/width and credits charged.
+  #
   class Result
     extend ::Forwardable
 
-    attr_reader :metadata, :rate_limit
+    # @return [RemoveBg::ResultMetadata]
+    attr_reader :metadata
+
+    # @return [RemoveBg::RateLimitInfo]
+    attr_reader :rate_limit
 
     def_delegators :metadata, :type, :width, :height, :credits_charged
 
@@ -18,6 +25,11 @@ module RemoveBg
       @rate_limit = rate_limit
     end
 
+    # Saves the processed image to the path specified
+    # @param file_path [string]
+    # @param overwrite [boolean] Overwrite any existing file at the specified path
+    # @return [nil]
+    #
     def save(file_path, overwrite: false)
       if File.exist?(file_path) && !overwrite
         raise FileOverwriteError.new(file_path)
@@ -26,6 +38,9 @@ module RemoveBg
       FileUtils.cp(image_file, file_path)
     end
 
+    # Returns the binary data of the processed image
+    # @return [String]
+    #
     def data
       image_file.rewind
       image_file.read

data/lib/remove_bg/version.rb

@@ -1,3 +1,3 @@
 module RemoveBg
-  VERSION = "1.4.1"
+  VERSION = "1.5.0"
 end

data/remove_bg.gemspec

@@ -28,12 +28,16 @@ Gem::Specification.new do |spec|
   spec.add_dependency "rubyzip", ">= 2.0", "< 3"
 
   spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "codecov"
   spec.add_development_dependency "dotenv"
   spec.add_development_dependency "pry"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec_junit_formatter"
   spec.add_development_dependency "rspec-with_params"
   spec.add_development_dependency "rspec", "~> 3.8"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "vcr_better_binary"
   spec.add_development_dependency "vcr"
   spec.add_development_dependency "webmock"
+  spec.add_development_dependency "yard"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: remove_bg
 version: !ruby/object:Gem::Version
-  version: 1.4.1
+  version: 1.5.0
 platform: ruby
 authors:
 - Oliver Peate
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-05-25 00:00:00.000000000 Z
+date: 2020-06-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -84,6 +84,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: codecov
+  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: dotenv
   requirement: !ruby/object:Gem::Requirement
@@ -168,6 +182,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.8'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  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: vcr_better_binary
+  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: vcr
   requirement: !ruby/object:Gem::Requirement
@@ -196,6 +238,20 @@ dependencies:
     - - ">="
       - !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:
 - team@remove.bg