mindee-lite 5.0.0.beta1

data/lib/mindee/image/image_utils.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Image processing module.
+  module Image
+    # Miscellaneous image operations.
+    module ImageUtils
+      # Resizes a provided MiniMagick Image with the given width & height, if present.
+      # @param image [MiniMagick::Image] MiniMagick image handle.
+      # @param width [Integer] Width to comply with.
+      # @param height [Integer] Height to comply with.
+      def self.resize_image(image, width, height)
+        if width && height
+          image.resize "#{width}x#{height}"
+        elsif width
+          image.resize width.to_s
+        elsif height
+          image.resize "x#{height}"
+        end
+      end
+
+      # Compresses the quality of the provided MiniMagick image.
+      # @param image [MiniMagick::Image] MiniMagick image handle.
+      # @param quality [Integer] Quality to apply to the image. This is independent of a JPG's base quality.
+      def self.compress_image_quality(image, quality)
+        image.quality quality.to_s
+      end
+
+      # Mostly here so that IDEs don't get confused on the type (@type annotation fails sometimes.)
+      # @param [MiniMagick::Image, StringIO, File, Tempfile] image The input image
+      # @return [MiniMagick::Image]
+      def self.to_image(image)
+        if image.is_a?(MiniMagick::Image)
+          image
+        elsif image.is_a?(StringIO) || image.is_a?(IO) || image.is_a?(File) || image.is_a?(Tempfile)
+          image.rewind
+          MiniMagick::Image.read(image)
+        else
+          img_class = image.class ? image.class.to_s : 'unknown format'
+          raise Error::MindeeImageError, "Expected an I/O object or a MiniMagick::Image. '#{img_class}' given instead."
+        end
+      end
+
+      # Converts a StringIO containing an image into a MiniMagick image.
+      # @param image [MiniMagick::Image] the input image.
+      # @param format [String] Format parameter, left open for the future, but should be JPEG for current use-cases.
+      # @return [StringIO]
+      def self.image_to_stringio(image, format = 'JPEG')
+        image.format format
+        blob = image.to_blob
+        stringio = StringIO.new(blob)
+        stringio.rewind
+
+        stringio
+      end
+
+      # Computes the new dimensions for a given SKBitmap, and returns a scaled down version of it relative to the
+      # provided bounds.
+      # @param [MiniMagick::Image] original Input MiniMagick image.
+      # @param max_width [Integer] Maximum width. If not specified, the horizontal ratio will remain the same.
+      # @param max_height [Integer] Maximum height. If not specified, the vertical ratio will remain the same.
+      def self.calculate_new_dimensions(original, max_width: nil, max_height: nil)
+        raise Error::MindeeImageError, 'Provided image could not be processed for resizing.' if original.nil?
+
+        return [original.width, original.height] if max_width.nil? && max_height.nil?
+
+        width_ratio = max_width ? max_width.to_f / original.width : Float::INFINITY
+        height_ratio = max_height ? max_height.to_f / original.height : Float::INFINITY
+
+        scale_factor = [width_ratio, height_ratio].min
+
+        new_width = (original.width.to_f * scale_factor).to_i
+        new_height = (original.height.to_f * scale_factor).to_i
+
+        [new_width, new_height]
+      end
+
+      # Computes the Height & Width from a page's media box. Falls back to the size of the initial image.
+      # @param image [MiniMagick::Image] The initial image that will fit into the page.
+      # @param media_box [Array<Integer>, nil]
+      # @return [Array<Integer>]
+      def self.calculate_dimensions_from_media_box(image, media_box)
+        if !media_box.nil? && media_box.any?
+          [
+            media_box[2]&.to_i || image[:width].to_i,
+            media_box[3]&.to_i || image[:height].to_i,
+          ]
+        else
+          [image[:width].to_i, image[:height].to_i]
+        end
+      end
+
+      # Transforms a PDF into a MagickImage. This is currently used for single-page PDFs.
+      # @param pdf_stream [StringIO] Input stream.
+      # @param image_quality [Integer] Quality to apply to the image.
+      # @return [MiniMagick::Image]
+      def self.pdf_to_magick_image(pdf_stream, image_quality)
+        compressed_image = MiniMagick::Image.read(pdf_stream.read)
+        compressed_image.format('jpg')
+        compressed_image.quality image_quality.to_s
+        compressed_image
+      end
+
+      # Retrieves the bounding box of a polygon.
+      #
+      # @param [Array<Point>, Mindee::Geometry::Polygon] polygon
+      def self.normalize_polygon(polygon)
+        if polygon.is_a?(Mindee::Geometry::Polygon) ||
+           (polygon.is_a?(Array) && polygon[0].is_a?(Mindee::Geometry::Point))
+          Mindee::Geometry.get_bounding_box(polygon)
+        elsif polygon.is_a?(Mindee::Geometry::Quadrilateral)
+          polygon
+        else
+          raise Error::MindeeGeometryError, 'Provided polygon has an invalid type.'
+        end
+      end
+
+      # Loads a buffer into a MiniMagick Image.
+      #
+      # @param [StringIO] pdf_stream Buffer containg the PDF
+      # @return [MiniMagick::Image] a valid MiniMagick image handle.
+      def self.read_page_content(pdf_stream)
+        pdf_stream.rewind
+        MiniMagick::Image.read(pdf_stream)
+      end
+
+      # Crops a MiniMagick Image from a the given bounding box.
+      #
+      # @param [MiniMagick::Image] image Input Image.
+      # @param [Mindee::Geometry::MinMax] min_max_x minimum & maximum values for the x coordinates.
+      # @param [Mindee::Geometry::MinMax] min_max_y minimum & maximum values for the y coordinates.
+      def self.crop_image(image, min_max_x, min_max_y)
+        width = image[:width].to_i
+        height = image[:height].to_i
+
+        image.format('jpg')
+        new_width = (min_max_x.max - min_max_x.min) * width
+        new_height = (min_max_y.max - min_max_y.min) * height
+        image.crop("#{new_width}x#{new_height}+#{min_max_x.min * width}+#{min_max_y.min * height}")
+
+        image
+      end
+
+      # Writes a MiniMagick::Image to a buffer.
+      #
+      # @param [MiniMagick::Image] image a valid MiniMagick image.
+      # @param [StringIO] buffer
+      def self.write_image_to_buffer(image, buffer)
+        image.write(buffer)
+      end
+
+      # Retrieves the file extension from the main file to apply it to the extracted images. Note: coerces pdf as jpg.
+      #
+      # @param [Mindee::Input::Source::LocalInputSource] input_source Local input source.
+      # @return [String, nil] A valid file extension.
+      def self.determine_file_extension(input_source)
+        if input_source.pdf? || input_source.filename.downcase.end_with?('pdf')
+          'jpg'
+        else
+          File.extname(input_source.filename.to_s).strip.downcase[1..].to_s
+        end
+      end
+    end
+  end
+end

data/lib/mindee/image.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'image/extracted_image'
+require_relative 'image/image_compressor'
+require_relative 'image/image_extractor'
+require_relative 'image/image_utils'

data/lib/mindee/input/base_parameters.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Input
+    # Base class for parameters accepted by all V2 endpoints.
+    class BaseParameters
+      # @return [String] ID of the model (required).
+      attr_reader :model_id
+
+      # @return [String, nil] Optional alias for the file.
+      attr_reader :file_alias
+
+      # @return [Array<String>, nil] Optional list of Webhooks IDs to propagate the API response to.
+      attr_reader :webhook_ids
+
+      # @return [PollingOptions] Options for polling. Set only if having timeout issues.
+      attr_reader :polling_options
+
+      # @return [Boolean, nil] Whether to close the file after parsing.
+      attr_reader :close_file
+
+      # @param [String] model_id ID of the model
+      # @param [String, nil] file_alias File alias, if applicable.
+      # @param [Array<String>, nil] webhook_ids List of webhook IDs to propagate the API response to.
+      # @param [Hash, nil] polling_options Options for polling. Set only if having timeout issues.
+      # @param [Boolean, nil] close_file Whether to close the file after parsing.
+      def initialize(
+        model_id,
+        file_alias: nil,
+        webhook_ids: nil,
+        polling_options: nil,
+        close_file: true
+      )
+        raise Error::MindeeInputError, 'Model ID is required.' if model_id.empty? || model_id.nil?
+
+        @model_id = model_id
+        @file_alias = file_alias
+        @webhook_ids = webhook_ids || []
+        @polling_options = get_clean_polling_options(polling_options)
+        @close_file = close_file.nil? || close_file
+      end
+
+      # @return [String] Slug for the endpoint.
+      def self.slug
+        if self == BaseParameters
+          raise NotImplementedError, 'Cannot access `slug` directly on the BaseParameters class.'
+        end
+
+        ''
+      end
+
+      # @return [String] Slug for the endpoint.
+      def slug
+        self.class.slug
+      end
+
+      # Load from a hash
+      # @param [Hash] params Parameters to provide as a hash.
+      # @return [BaseParameters]
+      def self.from_hash(params: {})
+        load_from_hash(params: params)
+        new(
+          params[:model_id],
+          file_alias: params[:file_alias],
+          webhook_ids: params[:webhook_ids],
+          polling_options: params[:polling_options],
+          close_file: params[:close_file]
+        )
+      end
+
+      # Loads a prediction from a Hash.
+      # @param [Hash] params Parameters to provide as a hash.
+      # @return [Hash]
+      def self.load_from_hash(params: {})
+        params.transform_keys!(&:to_sym)
+
+        if params.empty? || params[:model_id].nil? || params[:model_id].empty?
+          raise Error::MindeeInputError, 'Model ID is required.'
+        end
+
+        polling_options_input = params.fetch(:page_options, PollingOptions.new)
+        if polling_options_input.is_a?(Hash)
+          polling_options_input = polling_options_input.transform_keys(&:to_sym)
+          PollingOptions.new(
+            initial_delay_sec: polling_options_input.fetch(:initial_delay_sec, 2.0),
+            delay_sec: polling_options_input.fetch(:delay_sec, 1.5),
+            max_retries: polling_options_input.fetch(:max_retries, 80)
+          )
+        end
+        params
+      end
+
+      # Appends base form data to the provided array.
+      # @param [Array] form_data Array of form fields
+      # @return [Array]
+      def append_form_data(form_data)
+        form_data.push(['file_alias', @file_alias]) if @file_alias
+        webhook_ids = @webhook_ids || []
+        form_data.push(['webhook_ids', webhook_ids.join(',')]) unless @webhook_ids.nil? || webhook_ids.empty?
+        form_data
+      end
+
+      # Validates the parameters for async auto-polling
+      def validate_async_params
+        min_delay_sec = 1
+        min_initial_delay_sec = 1
+        min_retries = 2
+
+        if @polling_options.delay_sec < min_delay_sec
+          raise ArgumentError,
+                "Cannot set auto-poll delay to less than #{min_delay_sec} second(s)"
+        end
+        if @polling_options.initial_delay_sec < min_initial_delay_sec
+          raise ArgumentError,
+                "Cannot set initial parsing delay to less than #{min_initial_delay_sec} second(s)"
+        end
+        return unless @polling_options.max_retries < min_retries
+
+        raise ArgumentError,
+              "Cannot set auto-poll retries to less than #{min_retries}"
+      end
+
+      private
+
+      # Cleans a proper polling options object potentially from a hash.
+      # @param [Hash, PollingOptions, nil] polling_options Polling options.
+      # @return [PollingOptions] Valid polling options object.
+      def get_clean_polling_options(polling_options)
+        return PollingOptions.new if polling_options.is_a?(PollingOptions)
+
+        if polling_options.is_a?(Hash)
+          polling_options = polling_options.transform_keys(&:to_sym)
+          output_polling_options = PollingOptions.new(
+            initial_delay_sec: polling_options.fetch(:initial_delay_sec, 2.0),
+            delay_sec: polling_options.fetch(:delay_sec, 1.5),
+            max_retries: polling_options.fetch(:max_retries, 80)
+          )
+        else
+          output_polling_options = if polling_options.is_a?(PollingOptions)
+                                     polling_options || PollingOptions.new
+                                   else
+                                     PollingOptions.new
+                                   end
+        end
+        output_polling_options
+      end
+    end
+  end
+end

data/lib/mindee/input/local_response.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'openssl'
+require 'stringio'
+require 'pathname'
+require 'tempfile'
+
+module Mindee
+  module Input
+    # Response loaded locally.
+    class LocalResponse
+      attr_reader :file
+
+      # @param input_file [File, Tempfile, IO, StringIO, String, Pathname] The input file, which can be a StringIO.
+      def initialize(input_file)
+        case input_file
+        when IO, StringIO, File, Tempfile
+          str_stripped = input_file.read.to_s.gsub(%r{[\r\n]}, '')
+          @file = StringIO.new(str_stripped)
+          @file.rewind
+        when Pathname, String
+          @file = if Pathname(input_file.to_s).exist?
+                    StringIO.new(File.read(input_file.to_s, encoding: 'utf-8').gsub(%r{[\r\n]}, ''))
+                  else
+                    StringIO.new(input_file.to_s.gsub(%r{[\r\n]}, ''))
+                  end
+          @file.rewind
+        else
+          raise Error::MindeeInputError, "Incompatible type for input '#{input_file.class}'."
+        end
+      end
+
+      # Returns the file as a hash.
+      # @return [Hash]
+      def as_hash
+        @file.rewind
+        file_str = @file.read or raise 'File could not be read'
+        JSON.parse(file_str, object_class: Hash)
+      rescue JSON::ParserError
+        raise Error::MindeeInputError, "File is not a valid dict. #{file_str}"
+      end
+
+      # Processes the secret key
+      # @param secret_key [String] the secret key as plain text.
+      # @return [String]
+      def self.process_secret_key(secret_key)
+        secret_key.is_a?(String) ? secret_key.encode('utf-8') : secret_key
+      end
+
+      # @param [String] secret_key [String] Secret key, either a string or a byte/byte array.
+      # @return [String]
+      def get_hmac_signature(secret_key)
+        algorithm = OpenSSL::Digest.new('sha256')
+        begin
+          @file.rewind
+          mac = OpenSSL::HMAC.hexdigest(algorithm, self.class.process_secret_key(secret_key),
+                                        @file.read || raise('File could not be read'))
+        rescue StandardError
+          raise Error::MindeeInputError, 'Could not get HMAC signature from payload.'
+        end
+        mac
+      end
+
+      # @param secret_key [String] Secret key, either a string or a byte/byte array.
+      # @param signature [String] Signature to match
+      # @return [bool]
+      def valid_hmac_signature?(secret_key, signature)
+        signature == get_hmac_signature(secret_key)
+      end
+
+      # Deserializes a loaded response
+      # @param response_class [Class<V2::Parsing::BaseResponse>] class to return.
+      # @return [V2::Parsing::JobResponse, Mindee::V2::Parsing::BaseResponse]
+      def deserialize_response(response_class)
+        response_class.new(as_hash) # : Mindee::V2::Parsing::JobResponse | Mindee::V2::Parsing::BaseResponse
+      end
+    end
+  end
+end

data/lib/mindee/input/polling_options.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Input
+    # Options for asynchronous polling.
+    class PollingOptions
+      # @return [Integer, Float] Initial delay before the first polling attempt (in seconds).
+      attr_reader :initial_delay_sec
+
+      # @return [Integer, Float] Delay between each polling attempt (in seconds).
+      attr_reader :delay_sec
+
+      # @return [Integer] Total number of polling attempts.
+      attr_reader :max_retries
+
+      # @param initial_delay_sec [Float] Initial delay before the first attempt (default:2.0).
+      # @param delay_sec [Float] Delay between attempts (default: 1.5).
+      # @param max_retries [Integer] Maximum number of retries (default:80).
+      def initialize(initial_delay_sec: 2.0, delay_sec: 1.5, max_retries: 80)
+        @initial_delay_sec = initial_delay_sec
+        @delay_sec = delay_sec
+        @max_retries = max_retries
+      end
+    end
+  end
+end

data/lib/mindee/input/sources/base64_input_source.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module Mindee
+  module Input
+    module Source
+      # Load a document from a base64 string.
+      class Base64InputSource < LocalInputSource
+        # @param base64_string [String]
+        # @param filename [String]
+        # @param repair_pdf [bool]
+        def initialize(base64_string, filename, repair_pdf: false)
+          io_stream = StringIO.new(base64_string.unpack1('m*').to_s)
+          io_stream.set_encoding Encoding::BINARY
+          super(io_stream, filename, repair_pdf: repair_pdf)
+        end
+
+        # Overload of the same function to prevent a base64 from being re-encoded.
+        # @param close [bool]
+        # @return [Array<[String, aBinaryString ], [Hash, nil] >]
+        def read_contents(close: true)
+          @io_stream.seek(0)
+          data = @io_stream.read
+          @io_stream.close if close
+          [[data].pack('m'), { filename: Source.convert_to_unicode_escape(@filename) }]
+        end
+      end
+    end
+  end
+end

data/lib/mindee/input/sources/bytes_input_source.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module Mindee
+  module Input
+    module Source
+      # Load a document from raw bytes.
+      class BytesInputSource < LocalInputSource
+        # @param raw_bytes [String]
+        # @param filename [String]
+        # @param repair_pdf [bool]
+        def initialize(raw_bytes, filename, repair_pdf: false)
+          io_stream = StringIO.new(raw_bytes)
+          io_stream.set_encoding Encoding::BINARY
+          super(io_stream, filename, repair_pdf: repair_pdf)
+        end
+      end
+    end
+  end
+end

data/lib/mindee/input/sources/file_input_source.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module Mindee
+  module Input
+    module Source
+      # Load a document from a file handle.
+      class FileInputSource < LocalInputSource
+        # @param input_file [File]
+        # @param filename [String]
+        # @param repair_pdf [bool]
+        def initialize(input_file, filename, repair_pdf: false)
+          io_stream = input_file
+          super(io_stream, filename, repair_pdf: repair_pdf)
+        end
+      end
+    end
+  end
+end