remove_bg 1.4.1 → 2.0.0

data/lib/remove_bg/api_client.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "json"
 require "tempfile"
 
@@ -16,21 +18,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)
+      data = options.data.merge(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
@@ -51,26 +72,24 @@ module RemoveBg
         # Faraday v0.16 & v1.0+ support streaming, v0.17 did not (rollback release)
         if req.options.respond_to?(:on_data)
           streaming = true
-          req.options.on_data = Proc.new do |chunk, _|
+          req.options.on_data = proc do |chunk, _|
             download.write(chunk)
           end
         end
       end
 
-      # Faraday v0.15 / v0.17
-      if !streaming
-        download.write(response.body)
-      end
+      # Faraday v0.17
+      download.write(response.body) unless streaming
 
       download.rewind
 
       if response.status == 200
-        parse_image_result(headers: response.headers, download: download)
+        parse_image_result(headers: response.headers, download:)
       else
         response_body = download.read
         download.close
         download.unlink
-        handle_http_error(response: response, body: response_body)
+        handle_http_error(response:, body: response_body)
       end
     end
 
@@ -82,7 +101,7 @@ module RemoveBg
       if response.status == 200
         parse_account_result(response)
       else
-        handle_http_error(response: response, body: response.body)
+        handle_http_error(response:, body: response.body)
       end
     end
 
@@ -104,7 +123,7 @@ module RemoveBg
 
     def parse_image_result(headers:, download:)
       result_for_content_type(headers["Content-Type"]).new(
-        download: download,
+        download:,
         metadata: ResultMetadata.new(headers),
         rate_limit: RateLimitInfo.new(headers)
       )
@@ -120,8 +139,8 @@ module RemoveBg
 
     def parse_account_result(response)
       attributes = JSON.parse(response.body, symbolize_names: true)
-        .fetch(:data)
-        .fetch(:attributes)
+                       .fetch(:data)
+                       .fetch(:attributes)
 
       RemoveBg::AccountInfo.new(attributes)
     end

data/lib/remove_bg/base_request_options.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "error"
 
 module RemoveBg

data/lib/remove_bg/composite_result.rb

@@ -1,15 +1,36 @@
+# frozen_string_literal: true
+
 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)
-      end
+      raise FileOverwriteError.new(file_path) if File.exist?(file_path) && !overwrite
+
+      warn("DEPRECATION WARNING: overwrite: true is deprecated and will be removed from remove_bg 2.0 (use save_zip! instead)") if overwrite
 
       FileUtils.cp(download, file_path)
     end
 
+    # Saves the ZIP archive containing the alpha.png and color.jpg files, overwriting any exisiting files
+    # (useful if you want to handle composition yourself)
+    # @param file_path [string]
+    # @return [nil]
+    #
+    def save_zip!(file_path)
+      FileUtils.cp(download, file_path)
+    end
+
     private
 
     def image_file
@@ -17,10 +38,8 @@ module RemoveBg
     end
 
     def composite_file
-      @composite_file ||= begin
-        binary_tempfile(["composed", ".png"])
-          .tap { |file| compose_to_file(file) }
-      end
+      @composite_file ||= binary_tempfile(["composed", ".png"])
+                          .tap { |file| compose_to_file(file) }
     end
 
     def color_file
@@ -35,8 +54,8 @@ module RemoveBg
       extract_parts
 
       ImageComposer.new.compose(
-        color_file: color_file,
-        alpha_file: alpha_file,
+        color_file:,
+        alpha_file:,
         destination_path: destination.path
       )
     end
@@ -49,7 +68,7 @@ module RemoveBg
     end
 
     def binary_tempfile(basename)
-      Tempfile.new(basename).tap { |file| file.binmode }
+      Tempfile.new(basename).tap(&:binmode)
     end
   end
 end

data/lib/remove_bg/configuration.rb

@@ -1,13 +1,26 @@
+# frozen_string_literal: true
+
+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

@@ -1,8 +1,14 @@
+# frozen_string_literal: true
+
 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 +17,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
 
@@ -40,7 +50,7 @@ module RemoveBg
 
   class FileOverwriteError < FileError
     def initialize(file_path)
-      super("The file already exists: '#{file_path}' (specify #save(overwrite: true) to ignore)", file_path)
+      super("The file already exists: '#{file_path}' (use #save! or #save_zip! to overwrite existing files)", file_path)
     end
   end
 

data/lib/remove_bg/http_connection.rb

@@ -1,21 +1,26 @@
+# frozen_string_literal: true
+
 require "faraday"
+require "faraday/retry"
+
 require_relative "api"
 require_relative "version"
 
 module RemoveBg
   class HttpConnection
-    USER_AGENT = "remove-bg-ruby-#{RemoveBg::VERSION}"
-    HTTP_BASE_TIMEOUT = 10
+    USER_AGENT = "remove-bg-ruby-#{RemoveBg::VERSION}".freeze
+    HTTP_BASE_TIMEOUT = 20
     HTTP_WRITE_TIMEOUT = 120
 
+    # @return [Faraday::Connection]
+    #
     def self.build(api_url = RemoveBg::Api::URL)
       retry_options = {
         max: 2,
         interval: 0.2,
         backoff_factor: 2,
         methods: [:post],
-        exceptions: Faraday::Request::Retry::DEFAULT_EXCEPTIONS +
-          [Faraday::ConnectionFailed]
+        exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS + [Faraday::ConnectionFailed],
       }
 
       request_options = Faraday::RequestOptions.new.tap do |req_options|

data/lib/remove_bg/image_composer.rb

@@ -1,18 +1,37 @@
+# frozen_string_literal: true
+
 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)
+      if detector.call("magick") || detector.call("convert") || detector.call("gm")
+        :minimagick
+      elsif detector.call("vips")
+        :vips
+      end
+    end
+
     def compose(color_file:, alpha_file:, destination_path:)
       image = case configured_image_processor
-        when :vips
-          then vips_compose(color_file: color_file, alpha_file: alpha_file)
-        when :minimagick
-          then minimagick_compose(color_file: color_file, alpha_file: alpha_file)
-        when nil
-          raise RemoveBg::Error, "Please configure an image processor to use image composition"
-        else
-          raise RemoveBg::Error, "Unsupported image processor: #{configured_image_processor.inspect}"
-        end
+              when :vips
+                vips_compose(color_file:, alpha_file:)
+              when :minimagick
+                minimagick_compose(color_file:, alpha_file:)
+              when nil
+                raise RemoveBg::Error, "Please configure an image processor to use image composition"
+              else
+                raise RemoveBg::Error, "Unsupported image processor: #{configured_image_processor.inspect}"
+              end
 
       image.call(destination: destination_path)
     end

data/lib/remove_bg/rate_limit_info.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "time"
 
 module RemoveBg
@@ -15,16 +17,17 @@ module RemoveBg
 
     def reset_at
       return if reset_timestamp.nil?
+
       Time.at(reset_timestamp).utc
     end
 
     def to_s
-      "<RateLimit"\
-      " reset_at='#{reset_at.iso8601}'"\
-      " retry_after_seconds=#{retry_after_seconds}"\
-      " total=#{total}"\
-      " remaining=#{remaining}"\
-      ">"
+      "<RateLimit " \
+        "reset_at='#{reset_at.iso8601}' " \
+        "retry_after_seconds=#{retry_after_seconds} " \
+        "total=#{total} " \
+        "remaining=#{remaining}" \
+        ">"
     end
 
     private

data/lib/remove_bg/request_options.rb

@@ -1,6 +1,10 @@
+# frozen_string_literal: true
+
 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 +19,38 @@ 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
+
+      options[:format] = optimize_format(options[:format]) if options.key?(:format)
+
       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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "fileutils"
 require "forwardable"
 require "zip"
@@ -5,10 +7,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,14 +27,30 @@ 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)
-      end
+      raise FileOverwriteError.new(file_path) if File.exist?(file_path) && !overwrite
+
+      warn("DEPRECATION WARNING: overwrite: true is deprecated and will be removed from remove_bg 2.0 (use save! instead)") if overwrite
+
+      FileUtils.cp(image_file, file_path)
+    end
 
+    # Saves the processed image to the path specified, overwriting any existing file at the specified path
+    # @param file_path [string]
+    # @return [nil]
+    #
+    def save!(file_path)
       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/result_metadata.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative "api"
 
 module RemoveBg

data/lib/remove_bg/upload.rb

@@ -1,12 +1,13 @@
+# frozen_string_literal: true
+
 require "faraday"
+require "faraday/multipart"
 require_relative "error"
 
 module RemoveBg
   class Upload
     def self.for_file(file_path)
-      if !File.exist?(file_path)
-        raise RemoveBg::FileMissingError.new(file_path)
-      end
+      raise RemoveBg::FileMissingError.new(file_path) unless File.exist?(file_path)
 
       content_type = determine_content_type(file_path)
       FARADAY_FILE.new(file_path, content_type)
@@ -23,8 +24,9 @@ module RemoveBg
 
     private_class_method :determine_content_type
 
-    # UploadIO for Faraday < 0.16.0
-    FARADAY_FILE = defined?(Faraday::FilePart) ? Faraday::FilePart : Faraday::UploadIO
+    FARADAY_FILE = File
+    FARADAY_FILE = Faraday::Multipart::FilePart if defined?(Faraday::Multipart::FilePart)
+
     private_constant :FARADAY_FILE
   end
 end

data/lib/remove_bg/url_validator.rb

@@ -1,16 +1,16 @@
+# frozen_string_literal: true
+
 require "uri"
 require_relative "error"
 
 module RemoveBg
   class UrlValidator
-    PERMITTED_SCHEMES = ["http", "https"].freeze
+    PERMITTED_SCHEMES = %w[http https].freeze
 
     def self.validate(url)
       parsed = URI.parse(url)
 
-      unless parsed.absolute? && PERMITTED_SCHEMES.include?(parsed.scheme)
-        raise RemoveBg::InvalidUrlError.new(url)
-      end
+      raise RemoveBg::InvalidUrlError.new(url) unless parsed.absolute? && PERMITTED_SCHEMES.include?(parsed.scheme)
     rescue URI::InvalidURIError
       raise RemoveBg::InvalidUrlError.new(url)
     end

data/lib/remove_bg/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module RemoveBg
-  VERSION = "1.4.1"
+  VERSION = "2.0.0"
 end

data/lib/remove_bg.rb

@@ -1,24 +1,43 @@
+# frozen_string_literal: true
+
 require "remove_bg/version"
 require "remove_bg/api_client"
 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/remove_bg.gemspec

@@ -1,39 +1,66 @@
-lib = File.expand_path("../lib", __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "remove_bg/version"
 
 Gem::Specification.new do |spec|
   spec.name = "remove_bg"
   spec.version = RemoveBg::VERSION
-  spec.authors = ["Oliver Peate"]
-  spec.email = ["team@remove.bg"]
+  spec.authors = ["Canva Austria GmbH"]
+  spec.email = ["ops@kaleido.ai"]
+
+  spec.platform = Gem::Platform::RUBY
 
   spec.summary = "Remove image background - 100% automatically"
+  spec.description = "Use remove.bg with our official Ruby library to quickly, easily and 100% automatically remove the background from images."
   spec.homepage = "https://www.remove.bg/"
   spec.license = "MIT"
-  spec.metadata["source_code_uri"] = "https://github.com/remove-bg/ruby"
-  spec.metadata["changelog_uri"] = "https://github.com/remove-bg/ruby/blob/master/CHANGELOG.md"
+  spec.metadata = {
+    "bug_tracker_uri" => "https://github.com/remove-bg/ruby/issues",
+    "source_code_uri" => "https://github.com/remove-bg/ruby",
+    "changelog_uri" => "https://github.com/remove-bg/ruby/blob/main/CHANGELOG.md",
+    "allowed_push_host" => "https://rubygems.org",
+    "rubygems_mfa_required" => "true",
+  }
+
+  # Require at least Ruby 3.1
+  spec.required_ruby_version = ">= 3.1"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|examples)/}) }
   end
   spec.bindir = "exe"
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "faraday", ">= 0.15", "< 2"
-  spec.add_dependency "image_processing", ">= 1.9", "< 2"
+  spec.add_dependency "faraday", ">= 2", "<= 3"
+  spec.add_dependency "faraday-multipart", "~> 1.0"
+  spec.add_dependency "faraday-retry", "~> 2.2"
+
+  spec.add_dependency "image_processing", "~> 1.12"
   spec.add_dependency "rubyzip", ">= 2.0", "< 3"
 
+  spec.add_development_dependency "appraisal", "~> 2.5"
+
   spec.add_development_dependency "bundler", "~> 2.0"
-  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 "vcr"
-  spec.add_development_dependency "webmock"
+  spec.add_development_dependency "pry", "~> 0.14"
+  spec.add_development_dependency "rake", "~> 13.2"
+  spec.add_development_dependency "rspec", "~> 3.13"
+  spec.add_development_dependency "rspec_junit_formatter", "~> 0.6"
+  spec.add_development_dependency "rspec-sonarqube-formatter", "~> 1.5"
+  spec.add_development_dependency "rspec-with_params", "~> 0.3"
+  spec.add_development_dependency "rubocop", "~> 1.64"
+  spec.add_development_dependency "rubocop-performance", "~> 1.21"
+  spec.add_development_dependency "rubocop-rake", "~> 0.6"
+  spec.add_development_dependency "rubocop-rspec", "~> 3.0"
+  spec.add_development_dependency "simplecov", "~> 0.22"
+  spec.add_development_dependency "simplecov-cobertura", "~> 2.1"
+  spec.add_development_dependency "simplecov_json_formatter", "~> 0.1"
+  spec.add_development_dependency "vcr", "~> 6.2"
+  spec.add_development_dependency "vcr_better_binary", "~> 0.2"
+  spec.add_development_dependency "webmock", "~> 3.23"
+  spec.add_development_dependency "yard", "~> 0.9"
 end