mindee 2.2.0 → 3.0.0

data/lib/mindee/geometry.rb

@@ -1,118 +1,7 @@
 # frozen_string_literal: true
 
-module Mindee
-  # Various helper functions for geometry.
-  module Geometry
-    # A relative set of coordinates (X, Y) on the document.
-    class Point
-      # @return [Float]
-      attr_accessor :x
-      # @return [Float]
-      attr_accessor :y
-
-      # @param x [Float]
-      # @param y [Float]
-      # rubocop:disable Naming/MethodParameterName
-      def initialize(x, y)
-        @x = x
-        @y = y
-      end
-      # rubocop:enable Naming/MethodParameterName
-
-      # @return [Float]
-      def [](key)
-        case key
-        when 0
-          @x
-        when 1
-          @y
-        else
-          throw '0 or 1 only'
-        end
-      end
-    end
-
-    # Contains exactly 4 relative vertices coordinates (Points).
-    class Quadrilateral
-      # @return [Mindee::Geometry::Point]
-      attr_accessor :top_left
-      # @return [Mindee::Geometry::Point]
-      attr_accessor :top_right
-      # @return [Mindee::Geometry::Point]
-      attr_accessor :bottom_right
-      # @return [Mindee::Geometry::Point]
-      attr_accessor :bottom_left
-
-      # @param top_left [Mindee::Geometry::Point]
-      # @param top_right [Mindee::Geometry::Point]
-      # @param bottom_right [Mindee::Geometry::Point]
-      # @param bottom_left [Mindee::Geometry::Point]
-      def initialize(top_left, top_right, bottom_right, bottom_left)
-        @top_left = top_left
-        @top_right = top_right
-        @bottom_right = bottom_right
-        @bottom_left = bottom_left
-      end
-
-      # @return [Mindee::Geometry::Point]
-      def [](key)
-        case key
-        when 0
-          @top_left
-        when 1
-          @top_right
-        when 2
-          @bottom_right
-        when 3
-          @bottom_left
-        else
-          throw '0, 1, 2, 3 only'
-        end
-      end
-    end
-
-    class Polygon < Array
-    end
-
-    # Transform a prediction into a Quadrilateral.
-    def self.quadrilateral_from_prediction(prediction)
-      throw "Prediction must have exactly 4 points, found #{prediction.size}" if prediction.size != 4
-
-      Quadrilateral.new(
-        Point.new(prediction[0][0], prediction[0][1]),
-        Point.new(prediction[1][0], prediction[1][1]),
-        Point.new(prediction[2][0], prediction[2][1]),
-        Point.new(prediction[3][0], prediction[3][1])
-      )
-    end
-
-    # Transform a prediction into a Polygon.
-    def self.polygon_from_prediction(prediction)
-      polygon = Polygon.new
-      return polygon if prediction.nil?
-
-      prediction.each do |point|
-        polygon << Point.new(point[0], point[1])
-      end
-      polygon
-    end
-
-    # @return [Array<Float>]
-    def self.get_bbox(vertices)
-      x_coords = vertices.map(&:x)
-      y_coords = vertices.map(&:y)
-      [x_coords.min, y_coords.min, x_coords.max, y_coords.max]
-    end
-
-    # @return [Mindee::Geometry::Quadrilateral]
-    def self.get_bounding_box(vertices)
-      x_min, y_min, x_max, y_max = get_bbox(vertices)
-      Quadrilateral.new(
-        Point.new(x_min, y_min),
-        Point.new(x_max, y_min),
-        Point.new(x_max, y_max),
-        Point.new(x_min, y_max)
-      )
-    end
-  end
-end
+require_relative 'geometry/min_max'
+require_relative 'geometry/point'
+require_relative 'geometry/quadrilateral'
+require_relative 'geometry/polygon'
+require_relative 'geometry/utils'

data/lib/mindee/http/endpoint.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'net/http'
 require_relative '../version'
 
@@ -32,12 +33,58 @@ module Mindee
         @url_root = "#{BASE_URL_DEFAULT}/products/#{@owner}/#{@url_name}/v#{@version}"
       end
 
-      # @param input_doc [Mindee::InputDocument]
-      # @param include_words [Boolean]
+      # Call the prediction API.
+      # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
+      # @param all_words [Boolean]
+      # @param close_file [Boolean]
+      # @param cropper [Boolean]
+      # @return [Hash]
+      def predict(input_source, all_words, close_file, cropper)
+        check_api_key
+        response = predict_req_post(input_source, all_words: all_words, close_file: close_file, cropper: cropper)
+        hashed_response = JSON.parse(response.body, object_class: Hash)
+        return hashed_response if (200..299).include?(response.code.to_i)
+
+        error = Parsing::Common::HttpError.new(hashed_response['api_request']['error'])
+        raise error
+      end
+
+      # Call the prediction API.
+      # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
+      # @param close_file [Boolean]
+      # @param cropper [Boolean]
+      # @return [Hash]
+      def predict_async(input_source, all_words, close_file, cropper)
+        check_api_key
+        response = document_queue_req_get(input_source, all_words, close_file, cropper)
+        hashed_response = JSON.parse(response.body, object_class: Hash)
+        return hashed_response if (200..299).include?(response.code.to_i)
+
+        error = Parsing::Common::HttpError.new(hashed_response['api_request']['error'])
+        raise error
+      end
+
+      # Calls the parsed async doc.
+      # @param job_id [String]
+      # @return [Hash]
+      def parse_async(job_id)
+        check_api_key
+        response = document_queue_req(job_id)
+        hashed_response = JSON.parse(response.body, object_class: Hash)
+        return hashed_response if (200..299).include?(response.code.to_i)
+
+        error = Parsing::Common::HttpError.new(hashed_response['api_request']['error'])
+        raise error
+      end
+
+      private
+
+      # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
+      # @param all_words [Boolean]
       # @param close_file [Boolean]
       # @param cropper [Boolean]
       # @return [Net::HTTPResponse]
-      def predict_req_post(input_doc, include_words: false, close_file: true, cropper: false)
+      def predict_req_post(input_source, all_words: false, close_file: true, cropper: false)
         uri = URI("#{@url_root}/predict")
 
         params = {}
@@ -49,11 +96,51 @@ module Mindee
           'User-Agent' => USER_AGENT,
         }
         req = Net::HTTP::Post.new(uri, headers)
+        form_data = if input_source.is_a?(Mindee::Input::Source::UrlInputSource)
+                      {
+                        'document' => input_source.url,
+                      }
+                    else
+                      {
+                        'document' => input_source.read_document(close: close_file),
+                      }
+                    end
+        form_data.push ['include_mvision', 'true'] if all_words
+
+        req.set_form(form_data, 'multipart/form-data')
+
+        Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, read_timeout: @request_timeout) do |http|
+          http.request(req)
+        end
+      end
+
+      # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
+      # @param all_words [Boolean]
+      # @param close_file [Boolean]
+      # @param cropper [Boolean]
+      # @return [Net::HTTPResponse]
+      def document_queue_req_get(input_source, all_words, close_file, cropper)
+        uri = URI("#{@url_root}/predict_async")
+
+        params = {}
+        params[:cropper] = 'true' if cropper
+        uri.query = URI.encode_www_form(params)
 
-        form_data = {
-          'document' => input_doc.read_document(close: close_file),
+        headers = {
+          'Authorization' => "Token #{@api_key}",
+          'User-Agent' => USER_AGENT,
         }
-        form_data.push ['include_mvision', 'true'] if include_words
+        req = Net::HTTP::Post.new(uri, headers)
+        form_data = if input_source.is_a?(Mindee::Input::Source::UrlInputSource)
+                      {
+                        'document' => input_source.url,
+                      }
+                    else
+                      {
+                        'document' => input_source.read_document(close: close_file),
+                      }
+                    end
+        form_data.push ['include_mvision', 'true'] if all_words
 
         req.set_form(form_data, 'multipart/form-data')
 
@@ -61,19 +148,39 @@ module Mindee
           http.request(req)
         end
       end
-    end
 
-    # Receipt API endpoint
-    class StandardEndpoint < Endpoint
-      def initialize(endpoint_name, version, api_key)
-        super('mindee', endpoint_name, version, api_key: api_key)
+      # @param job_id [String]
+      # @return [Net::HTTPResponse]
+      def document_queue_req(job_id)
+        uri = URI("#{@url_root}/documents/queue/#{job_id}")
+
+        headers = {
+          'Authorization' => "Token #{@api_key}",
+          'User-Agent' => USER_AGENT,
+        }
+
+        req = Net::HTTP::Get.new(uri, headers)
+
+        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, read_timeout: @request_timeout) do |http|
+          http.request(req)
+        end
+
+        if response.code.to_i > 299 && response.code.to_i < 400
+          req = Net::HTTP::Get.new(response['location'], headers)
+          response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, read_timeout: @request_timeout) do |http|
+            http.request(req)
+          end
+        end
+        response
       end
-    end
 
-    # Custom (constructed) API endpoint
-    class CustomEndpoint < Endpoint
-      def initialize(account_name, endpoint_name, version, api_key)
-        super(account_name, endpoint_name, version, api_key: api_key)
+      def check_api_key
+        return unless @api_key.nil? || @api_key.empty?
+
+        raise "Missing API key for product \"'#{@url_name}' v#{@version}\" (belonging to \"#{@owner}\"), " \
+              "check your Client Configuration.\n" \
+              'You can set this using the ' \
+              "'#{HTTP::API_KEY_ENV_NAME}' environment variable."
       end
     end
   end

data/lib/mindee/http.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'http/endpoint'

data/lib/mindee/input/sources.rb

@@ -3,94 +3,108 @@
 require 'stringio'
 require 'marcel'
 
-require_relative 'pdf_processing'
+require_relative '../pdf'
 
 module Mindee
   module Input
-    ALLOWED_MIME_TYPES = [
-      'application/pdf',
-      'image/heic',
-      'image/png',
-      'image/jpeg',
-      'image/tiff',
-      'image/webp',
-    ].freeze
-
-    # Base class for loading documents.
-    class InputDocument
-      # @return [String]
-      attr_reader :filename
-      # @return [String]
-      attr_reader :file_mimetype
-      # @return [StreamIO]
-      attr_reader :io_stream
-
-      # @param io_stream [StreamIO]
-      def initialize(io_stream, filename)
-        @io_stream = io_stream
-        @filename = filename
-        @file_mimetype = Marcel::MimeType.for @io_stream, name: @filename
-
-        return if ALLOWED_MIME_TYPES.include? @file_mimetype
-
-        raise "File type not allowed, must be one of #{ALLOWED_MIME_TYPES.join(', ')}"
-      end
+    module Source
+      ALLOWED_MIME_TYPES = [
+        'application/pdf',
+        'image/heic',
+        'image/png',
+        'image/jpeg',
+        'image/tiff',
+        'image/webp',
+      ].freeze
 
-      def pdf?
-        @file_mimetype == 'application/pdf'
-      end
+      # Base class for loading documents.
+      class LocalInputSource
+        # @return [String]
+        attr_reader :filename
+        # @return [String]
+        attr_reader :file_mimetype
+        # @return [StreamIO]
+        attr_reader :io_stream
+
+        # @param io_stream [StreamIO]
+        def initialize(io_stream, filename)
+          @io_stream = io_stream
+          @filename = filename
+          @file_mimetype = Marcel::MimeType.for @io_stream, name: @filename
+
+          return if ALLOWED_MIME_TYPES.include? @file_mimetype
+
+          raise "File type not allowed, must be one of #{ALLOWED_MIME_TYPES.join(', ')}"
+        end
+
+        def pdf?
+          @file_mimetype == 'application/pdf'
+        end
+
+        def process_pdf(options)
+          @io_stream.seek(0)
+          @io_stream = PdfProcessor.parse(@io_stream, options)
+        end
 
-      def process_pdf(options)
-        @io_stream.seek(0)
-        @io_stream = PdfProcessor.parse(@io_stream, options)
+        # @param close [Boolean]
+        def read_document(close: true)
+          @io_stream.seek(0)
+          data = @io_stream.read
+          @io_stream.close if close
+          [data].pack('m')
+        end
       end
 
-      # @param close [Boolean]
-      def read_document(close: true)
-        @io_stream.seek(0)
-        data = @io_stream.read
-        @io_stream.close if close
-        [data].pack('m')
+      # Load a document from a path.
+      class PathInputSource < LocalInputSource
+        # @param filepath [String]
+        def initialize(filepath)
+          io_stream = File.open(filepath, 'rb')
+          super(io_stream, File.basename(filepath))
+        end
       end
-    end
 
-    # Load a document from a path.
-    class PathDocument < InputDocument
-      # @param filepath [String]
-      def initialize(filepath)
-        io_stream = File.open(filepath, 'rb')
-        super(io_stream, File.basename(filepath))
+      # Load a document from a base64 string.
+      class Base64InputSource < LocalInputSource
+        # @param base64_string [String]
+        # @param filename [String]
+        def initialize(base64_string, filename)
+          io_stream = StringIO.new(base64_string.unpack1('m*'))
+          io_stream.set_encoding Encoding::BINARY
+          super(io_stream, filename)
+        end
       end
-    end
 
-    # Load a document from a base64 string.
-    class Base64Document < InputDocument
-      # @param base64_string [String]
-      # @param filename [String]
-      def initialize(base64_string, filename)
-        io_stream = StringIO.new(base64_string.unpack1('m*'))
-        io_stream.set_encoding Encoding::BINARY
-        super(io_stream, filename)
+      # Load a document from raw bytes.
+      class BytesInputSource < LocalInputSource
+        # @param raw_bytes [String]
+        # @param filename [String]
+        def initialize(raw_bytes, filename)
+          io_stream = StringIO.new(raw_bytes)
+          io_stream.set_encoding Encoding::BINARY
+          super(io_stream, filename)
+        end
       end
-    end
 
-    # Load a document from raw bytes.
-    class BytesDocument < InputDocument
-      # @param raw_bytes [String]
-      # @param filename [String]
-      def initialize(raw_bytes, filename)
-        io_stream = StringIO.new(raw_bytes)
-        io_stream.set_encoding Encoding::BINARY
-        super(io_stream, filename)
+      # Load a document from a file handle.
+      class FileInputSource < LocalInputSource
+        # @param filename [String]
+        def initialize(file_handle, filename)
+          io_stream = file_handle
+          super(io_stream, filename)
+        end
       end
-    end
 
-    # Load a document from a file handle.
-    class FileDocument < InputDocument
-      # @param filename [String]
-      def initialize(file_handle, filename)
-        io_stream = file_handle
-        super(io_stream, filename)
+      # Load a remote document from a file url.
+      class UrlInputSource
+        # @return [String]
+        attr_reader :url
+
+        def initialize(url)
+          raise 'URL must be HTTPS' unless url.start_with? 'https://'
+
+          @url = url
+        end
       end
     end
   end

data/lib/mindee/parsing/common/api_response.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative 'document'
+require 'time'
+
+module Mindee
+  module Parsing
+    module Common
+      module JobStatus
+        WAITING = :waiting
+        PROCESSING = :processing
+        COMPLETED = :completed
+      end
+
+      module RequestStatus
+        FAILURE = :failure
+        SUCCESS = :success
+      end
+
+      # Job (queue) information on async parsing.
+      class Job
+        # @return [String] Mindee ID of the document
+        attr_reader :id
+        # @return [Mindee::Parsing::Standard::DateField]
+        attr_reader :issued_at
+        # @return [Mindee::Parsing::Standard::DateField, nil]
+        attr_reader :available_at
+        # @return [JobStatus, Symbol]
+        attr_reader :status
+        # @return [Integer, nil]
+        attr_reader :millisecs_taken
+
+        # @param http_response [Hash]
+        def initialize(http_response)
+          @id = http_response['id']
+          @issued_at = Time.iso8601(http_response['issued_at'])
+          if http_response.key?('available_at') && !http_response['available_at'].nil?
+            @available_at = Time.iso8601(http_response['available_at'])
+            @millisecs_taken = (1000 * (@available_at.to_time - @issued_at.to_time).to_f).to_i
+          end
+          @status = case http_response['status']
+                    when 'waiting'
+                      JobStatus::WAITING
+                    when 'processing'
+                      JobStatus::PROCESSING
+                    when 'completed'
+                      JobStatus::COMPLETED
+                    else
+                      http_response['status']&.to_sym
+                    end
+        end
+      end
+
+      # HTTP request response.
+      class ApiRequest
+        # @return [Hash]
+        attr_reader :error
+        # @return [Array<String>]
+        attr_reader :ressources
+        # @return [RequestStatus, Symbol]
+        attr_reader :status
+        # @return [Integer]
+        attr_reader :status_code
+        # @return [String]
+        attr_reader :url
+
+        def initialize(server_response)
+          @error = server_response['error']
+          @ressources = server_response['ressources']
+
+          @status = if server_response['status'] == 'failure'
+                      RequestStatus::FAILURE
+                    elsif server_response['status'] == 'success'
+                      RequestStatus::SUCCESS
+                    else
+                      server_response['status']&.to_sym
+                    end
+          @status_code = server_response['status_code']
+          @url = server_response['url']
+        end
+      end
+
+      # Wrapper class for all predictions (synchronous and asynchronous)
+      class ApiResponse
+        # @return [Mindee::Parsing::Common::Document, nil]
+        attr_reader :document
+        # @return [Mindee::Parsing::Common::Job, nil]
+        attr_reader :job
+        # @return [Mindee::Parsing::Common::ApiRequest]
+        attr_reader :api_request
+
+        # @param product_class [Class<Mindee::Product>]
+        # @param http_response [Hash]
+        def initialize(product_class, http_response)
+          if http_response.key?('api_request')
+            @api_request = Mindee::Parsing::Common::ApiRequest.new(http_response['api_request'])
+          end
+          if http_response.key?('document') &&
+             (!http_response.key?('job') ||
+             http_response['job']['status'] == 'completed') &&
+             @api_request.status == RequestStatus::SUCCESS
+            @document = Mindee::Parsing::Common::Document.new(product_class, http_response['document'])
+          end
+          @job = Mindee::Parsing::Common::Job.new(http_response['job']) if http_response.key?('job')
+        end
+      end
+    end
+  end
+end

data/lib/mindee/parsing/common/document.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'inference'
+
+module Mindee
+  module Parsing
+    module Common
+      # Stores all response attributes.
+      class Document
+        # @return [Mindee::Inference]
+        attr_reader :inference
+        # @return [String] Filename sent to the API
+        attr_reader :name
+        # @return [String] Mindee ID of the document
+        attr_reader :id
+        # @return [Mindee::Parsing::Common::Ocr::Ocr, nil]
+        attr_reader :ocr
+
+        # @param http_response [Hash]
+        # @return [Mindee::Parsing::Common::Ocr::Ocr]
+        def self.load_ocr(http_response)
+          ocr_prediction = http_response.fetch('ocr', nil)
+          return nil if ocr_prediction.nil? || ocr_prediction.fetch('mvision-v1', nil).nil?
+
+          Ocr(ocr_prediction)
+        end
+
+        # @param product_class [Class<Mindee::Product>]
+        # @param http_response [Hash]
+        def initialize(product_class, http_response)
+          @id = http_response['id']
+          @name = http_response['name']
+          @inference = product_class.new(http_response['inference'])
+          @ocr = self.class.load_ocr(http_response)
+        end
+
+        # @return [String]
+        def to_s
+          out_str = String.new
+          out_str << "########\nDocument\n########"
+          out_str << "\n:Mindee ID: #{@id}"
+          out_str << "\n:Filename: #{@name}"
+          out_str << "\n\n#{@inference}"
+        end
+      end
+    end
+  end
+end

data/lib/mindee/parsing/common/error.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Parsing
+    module Common
+      # API HttpError
+      class HttpError < StandardError
+        # @return [String]
+        attr_reader :api_code
+        # @return [String]
+        attr_reader :api_details
+        # @return [String]
+        attr_reader :api_message
+
+        def initialize(error)
+          @api_code = error['code']
+          @api_details = error['details']
+          @api_message = error['message']
+          super("#{@api_code}: #{@api_details} - #{@api_message}")
+        end
+      end
+    end
+  end
+end