mindee 1.2.0 → 2.0.0

data/lib/mindee/geometry.rb

@@ -3,19 +3,116 @@
 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_min = vertices.map { |v| v[0] }.min
-      x_max = vertices.map { |v| v[0] }.max
-      y_min = vertices.map { |v| v[1] }.min
-      y_max = vertices.map { |v| v[1] }.max
-      [x_min, y_min, x_max, y_max]
+      x_coords = vertices.map(&:x)
+      y_coords = vertices.map(&:y)
+      [x_coords.min, y_coords.min, x_coords.max, y_coords.max]
     end
 
-    # @return [Array<Array<Float>>]
-    def self.get_bbox_as_polygon(vertices)
+    # @return [Mindee::Geometry::Quadrilateral]
+    def self.get_bounding_box(vertices)
       x_min, y_min, x_max, y_max = get_bbox(vertices)
-      [[x_min, y_min], [x_max, y_min], [x_max, y_max], [x_min, y_max]]
+      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

data/lib/mindee/http/endpoint.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require_relative '../version'
+
+module Mindee
+  module HTTP
+    API_KEY_ENV_NAME = 'MINDEE_API_KEY'
+    API_KEY_DEFAULT = nil
+
+    BASE_URL_ENV_NAME = 'MINDEE_BASE_URL'
+    BASE_URL_DEFAULT = 'https://api.mindee.net/v1'
+
+    REQUEST_TIMEOUT_ENV_NAME = 'MINDEE_REQUEST_TIMEOUT'
+    TIMEOUT_DEFAULT = 120
+
+    USER_AGENT = "mindee-api-ruby@v#{Mindee::VERSION} ruby-v#{RUBY_VERSION} #{Mindee::PLATFORM}"
+
+    # Generic API endpoint for a product.
+    class Endpoint
+      # @return [String]
+      attr_reader :api_key
+      # @return [Integer]
+      attr_reader :request_timeout
+
+      def initialize(owner, url_name, version, api_key: '')
+        @owner = owner
+        @url_name = url_name
+        @version = version
+        @request_timeout = ENV.fetch(REQUEST_TIMEOUT_ENV_NAME, TIMEOUT_DEFAULT).to_i
+        @api_key = api_key.nil? || api_key.empty? ? ENV.fetch(API_KEY_ENV_NAME, API_KEY_DEFAULT) : api_key
+        @url_root = "#{BASE_URL_DEFAULT}/products/#{@owner}/#{@url_name}/v#{@version}"
+      end
+
+      # @param input_doc [Mindee::InputDocument]
+      # @param include_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)
+        uri = URI("#{@url_root}/predict")
+
+        params = {}
+        params[:cropper] = 'true' if cropper
+        uri.query = URI.encode_www_form(params)
+
+        headers = {
+          'Authorization' => "Token #{@api_key}",
+          'User-Agent' => USER_AGENT,
+        }
+        req = Net::HTTP::Post.new(uri, headers)
+
+        form_data = {
+          'document' => input_doc.read_document(close: close_file),
+        }
+        form_data.push ['include_mvision', 'true'] if include_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
+    end
+
+    # Receipt API endpoint
+    class StandardEndpoint < Endpoint
+      def initialize(endpoint_name, version, api_key)
+        super('mindee', endpoint_name, version, api_key: api_key)
+      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)
+      end
+    end
+  end
+end

data/lib/mindee/input/pdf_processing.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'origami'
+
+# Monkey-patching for Origami
+module PDFTools
+  def to_io_stream(params = {})
+    options = {
+      delinearize: true,
+      recompile: true,
+      decrypt: false,
+    }
+    options.update(params)
+
+    if frozen? # incompatible flags with frozen doc (signed)
+      options[:recompile] = nil
+      options[:rebuild_xrefs] = nil
+      options[:noindent] = nil
+      options[:obfuscate] = false
+    end
+    load_all_objects unless @loaded
+
+    intents_as_pdfa1 if options[:intent] =~ %r{pdf[/-]?A1?/i}
+    delinearize! if options[:delinearize] && linearized?
+    compile(options) if options[:recompile]
+
+    io_stream = StringIO.new(output(options))
+    io_stream.set_encoding Encoding::BINARY
+    io_stream
+  end
+end
+
+Origami::PDF.class_eval { include PDFTools }
+
+module Mindee
+  module Input
+    # Class for PDF documents
+    module PdfProcessor
+      DEFAULT_OPTIONS = {
+        page_indexes: [0],
+        operation: :KEEP_ONLY,
+        on_min_pages: 0,
+      }.freeze
+
+      # @param io_stream [StreamIO]
+      # @param options [Hash]
+      def self.parse(io_stream, options)
+        options = DEFAULT_OPTIONS.merge(options)
+
+        current_pdf = open_pdf(io_stream)
+        pages_count = current_pdf.pages.size
+        return if options[:on_min_pages] > pages_count
+
+        all_pages = (0..pages_count - 1).to_a
+
+        case options[:operation]
+        when :KEEP_ONLY
+          pages_to_remove = indexes_from_keep(options[:page_indexes], all_pages)
+        when :REMOVE
+          pages_to_remove = indexes_from_remove(options[:page_indexes], all_pages)
+        else
+          raise "operation must be one of :KEEP_ONLY or :REMOVE, sent '#{behavior}'"
+        end
+
+        current_pdf.delete_pages_at(pages_to_remove) if pages_to_remove.to_a != all_pages.to_a
+        current_pdf.to_io_stream
+      end
+
+      # @param page_indexes [Array]
+      # @param all_pages [Array]
+      def self.indexes_from_keep(page_indexes, all_pages)
+        pages_to_keep = Set.new
+        page_indexes.each do |idx|
+          idx = (all_pages.length - (idx + 2)) if idx.negative?
+          page = all_pages[idx]
+          next if page.nil?
+
+          pages_to_keep << page
+        end
+        all_pages.to_set - pages_to_keep
+      end
+
+      # @param page_indexes [Array]
+      # @param all_pages [Array]
+      def self.indexes_from_remove(page_indexes, all_pages)
+        pages_to_remove = Set.new
+        page_indexes.each do |idx|
+          idx = (all_pages.length - (idx + 2)) if idx.negative?
+          page = all_pages[idx]
+          next if page.nil?
+
+          pages_to_remove << page
+        end
+      end
+
+      # @param io_stream [StringIO]
+      # @return [Origami::PDF]
+      def self.open_pdf(io_stream)
+        pdf_parser = Origami::PDF::LinearParser.new({ verbosity: Origami::Parser::VERBOSE_QUIET })
+        io_stream.seek(0)
+        pdf_parser.parse(io_stream)
+      end
+    end
+  end
+end

data/lib/mindee/input/sources.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'stringio'
+require 'marcel'
+
+require_relative 'pdf_processing'
+
+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
+
+      def pdf?
+        @file_mimetype == 'application/pdf'
+      end
+
+      def process_pdf(options)
+        @io_stream.seek(0)
+        @io_stream = PdfProcessor.parse(@io_stream, options)
+      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')
+      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))
+      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)
+      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)
+      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)
+      end
+    end
+  end
+end

data/lib/mindee/input.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'input/sources'

data/lib/mindee/parsing/document.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'inference'
+
+module Mindee
+  # 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
+
+    # @param prediction_class [Class<Mindee::Prediction::Prediction>]
+    # @param http_response [Hash]
+    def initialize(prediction_class, http_response)
+      @id = http_response['id']
+      @name = http_response['name']
+      @inference = Mindee::Inference.new(prediction_class, http_response['inference'])
+    end
+
+    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

data/lib/mindee/parsing/error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Parsing
+    # API Error
+    class Error < 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

data/lib/mindee/parsing/inference.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'page'
+
+module Mindee
+  # Product information
+  class Product
+    attr_reader :name, :type, :version
+
+    # @param http_response [Hash]
+    def initialize(http_response)
+      @name = http_response['name']
+      @type = http_response['type']
+      @version = http_response['version']
+    end
+  end
+
+  # Inference holds all predictions
+  class Inference
+    # @return [Boolean]
+    attr_reader :is_rotation_applied
+    # @return [Array<Mindee::Page>]
+    attr_reader :pages
+    # @return [Mindee::Prediction]
+    attr_reader :prediction
+    # @return [Mindee::Product]
+    attr_reader :product
+
+    # @param prediction_class [Class<Mindee::Prediction::Prediction>]
+    # @param http_response [Hash]
+    def initialize(prediction_class, http_response)
+      @is_rotation_applied = http_response['is_rotation_applied']
+      @prediction = prediction_class.new(http_response['prediction'], nil)
+      @product = Product.new(http_response['product'])
+      @pages = []
+      http_response['pages'].each do |page|
+        @pages.push(Page.new(prediction_class, page))
+      end
+    end
+
+    def to_s
+      is_rotation_applied = @is_rotation_applied ? 'Yes' : 'No'
+      out_str = String.new
+      out_str << "Inference\n#########"
+      out_str << "\n:Product: #{@product.name} v#{@product.version}"
+      out_str << "\n:Rotation applied: #{is_rotation_applied}"
+      out_str << "\n\nPrediction\n=========="
+      out_str << "\n#{@prediction}"
+      out_str << "\n\nPage Predictions\n================\n\n"
+      out_str << @pages.map(&:to_s).join("\n\n")
+    end
+  end
+end

data/lib/mindee/parsing/page.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Page orientation
+  class Orientation
+    # @return [Integer]
+    attr_reader :page_id
+    # A prediction among these 3 possible outputs:
+    #   * 0 degrees: the page is already upright
+    #   * 90 degrees: the page must be rotated clockwise to be upright
+    #   * 270 degrees: the page must be rotated counterclockwise to be upright
+    # @return [Integer, nil]
+    attr_reader :value
+
+    # @param prediction [Hash]
+    # @param page_id [Integer]
+    def initialize(prediction, page_id)
+      @value = prediction['value']
+      @page_id = page_id
+    end
+  end
+
+  # Page object
+  class Page
+    # @return [Integer]
+    attr_reader :id
+    # @return [Mindee::Prediction]
+    attr_reader :prediction
+    # @return [Mindee::Orientation]
+    attr_reader :orientation
+
+    def initialize(prediction_class, page)
+      @id = page['id'].to_i
+      @prediction = prediction_class.new(page['prediction'], @id)
+      @orientation = Orientation.new(page['orientation'], @id)
+    end
+
+    def to_s
+      out_str = String.new
+      title = "Page #{@id}"
+      out_str << "#{title}\n"
+      out_str << ('-' * title.size)
+      out_str << "\n#{@prediction}"
+    end
+  end
+end

data/lib/mindee/parsing/prediction/base.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Mindee
+  module Prediction
+    # Base document object.
+    class Prediction
+      # document type
+      # @return [String]
+      attr_reader :document_type
+      # Validation checks for the document
+      # @return [Hash<Symbol, Boolean>]
+      attr_reader :checklist
+      # Original filename of the document
+      # @return [String, nil]
+      attr_reader :filename
+      # Detected MIME type of the document
+      # @return [String, nil]
+      attr_reader :file_mimetype
+
+      def initialize(_prediction, _page_id)
+        @checklist = {}
+      end
+
+      # @return [Boolean]
+      def all_checks
+        @checklist.all? { |_, value| value == true }
+      end
+    end
+  end
+end

data/lib/mindee/{fields → parsing/prediction/common_fields}/amount.rb

@@ -4,7 +4,7 @@ require_relative 'base'
 
 module Mindee
   # Represents tax information.
-  class Amount < Field
+  class AmountField < Field
     # Amount value as 3 decimal float
     # @return [Float, nil]
     attr_reader :value
@@ -13,5 +13,9 @@ module Mindee
       super
       @value = @value.round(3) unless @value.nil?
     end
+
+    def to_s
+      Field.float_to_string(@value)
+    end
   end
 end

data/lib/mindee/{fields → parsing/prediction/common_fields}/base.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative '../geometry'
+require_relative '../../../geometry'
 
 module Mindee
   # Base field object.
@@ -8,8 +8,8 @@ module Mindee
     # @return [String, Float, Integer, Boolean]
     attr_reader :value
     # @return [Array<Array<Float>>]
-    attr_reader :bbox
-    # @return [Array<Array<Float>>]
+    attr_reader :bounding_box
+    # @return [Mindee::Geometry::Polygon]
     attr_reader :polygon
     # @return [Integer, nil]
     attr_reader :page_id
@@ -26,8 +26,8 @@ module Mindee
     def initialize(prediction, page_id, reconstructed: false)
       @value = prediction['value']
       @confidence = prediction['confidence']
-      @polygon = prediction['polygon']
-      @bbox = Geometry.get_bbox_as_polygon(@polygon) unless @polygon.nil? || @polygon.empty?
+      @polygon = Geometry.polygon_from_prediction(prediction['polygon'])
+      @bounding_box = Geometry.get_bounding_box(@polygon) unless @polygon.nil? || @polygon.empty?
       @page_id = page_id || prediction['page_id']
       @reconstructed = reconstructed
     end
@@ -57,5 +57,16 @@ module Mindee
       end
       arr_sum.to_f
     end
+
+    # @param value [Float]
+    # @param min_precision [Integer]
+    def self.float_to_string(value, min_precision = 2)
+      return String.new if value.nil?
+
+      precision = value.to_f.to_s.split('.')[1].size
+      precision = [precision, min_precision].max
+      format_string = "%.#{precision}f"
+      format(format_string, value)
+    end
   end
 end