mindee 3.1.0 → 3.2.0

data/lib/mindee/input/sources.rb

@@ -8,6 +8,7 @@ require_relative '../pdf'
 module Mindee
   module Input
     module Source
+      # Mime types accepted by the server.
       ALLOWED_MIME_TYPES = [
         'application/pdf',
         'image/heic',
@@ -17,36 +18,99 @@ module Mindee
         'image/webp',
       ].freeze
 
+      # Standard error for invalid mime types
+      class MimeTypeError < StandardError
+      end
+
+      # Error sent if the file's mimetype isn't allowed
+      class InvalidMimeTypeError < MimeTypeError
+        # @return [String]
+        attr_reader :invalid_mimetype
+
+        # @param mime_type [String]
+        def initialize(mime_type)
+          @invalid_mimetype = mime_type
+          super("'#{@invalid_mimetype}' mime type not allowed, must be one of #{ALLOWED_MIME_TYPES.join(', ')}")
+        end
+      end
+
+      # Error sent if a pdf file couldn't be fixed
+      class UnfixablePDFError < MimeTypeError
+        def initialize
+          super("Corrupted PDF couldn't be repaired.")
+        end
+      end
+
       # Base class for loading documents.
       class LocalInputSource
         # @return [String]
         attr_reader :filename
         # @return [String]
         attr_reader :file_mimetype
-        # @return [StreamIO]
+        # @return [StringIO]
         attr_reader :io_stream
 
-        # @param io_stream [StreamIO]
-        def initialize(io_stream, filename)
+        # @param io_stream [StringIO]
+        # @param filename [String]
+        # @param fix_pdf [Boolean]
+        def initialize(io_stream, filename, fix_pdf: false)
           @io_stream = io_stream
           @filename = filename
-          @file_mimetype = Marcel::MimeType.for @io_stream, name: @filename
-
+          @file_mimetype = if fix_pdf
+                             Marcel::MimeType.for @io_stream
+                           else
+                             Marcel::MimeType.for @io_stream, name: @filename
+                           end
           return if ALLOWED_MIME_TYPES.include? @file_mimetype
 
-          raise "File type not allowed, must be one of #{ALLOWED_MIME_TYPES.join(', ')}"
+          if filename.end_with?('.pdf') && fix_pdf
+            rescue_broken_pdf(@io_stream)
+            @file_mimetype = Marcel::MimeType.for @io_stream
+
+            return if ALLOWED_MIME_TYPES.include? @file_mimetype
+          end
+
+          raise InvalidMimeTypeError, @file_mimetype.to_s
+        end
+
+        # Attempts to fix pdf files if mimetype is rejected.
+        # "Broken PDFs" are often a result of third-party injecting invalid headers.
+        # This attempts to remove them and send the file
+        # @param stream [StringIO]
+        def rescue_broken_pdf(stream)
+          stream.gets('%PDF-')
+          raise UnfixablePDFError if stream.eof? || stream.pos > 500
+
+          stream.pos = stream.pos - 5
+          data = stream.read
+          @io_stream.close
+
+          @io_stream = StringIO.new
+          @io_stream << data
         end
 
+        # Shorthand for pdf mimetype validation.
         def pdf?
           @file_mimetype.to_s == 'application/pdf'
         end
 
+        # Parses a PDF file according to provided options.
+        # @param options [Hash, nil] Page cutting/merge options:
+        #
+        #  * `:page_indexes` Zero-based list of page indexes.
+        #  * `:operation` Operation to apply on the document, given the `page_indexes specified:
+        #      * `:KEEP_ONLY` - keep only the specified pages, and remove all others.
+        #      * `:REMOVE` - remove the specified pages, and keep all others.
+        #  * `:on_min_pages` Apply the operation only if document has at least this many pages.
         def process_pdf(options)
           @io_stream.seek(0)
           @io_stream = PdfProcessor.parse(@io_stream, options)
         end
 
+        # Reads a document. Packs it into bytes if needed.
+        # Note: only needs filename in case of some pdf files.
         # @param close [Boolean]
+        # @return [Array<String, [String, aBinaryString ], [Hash, nil] >]
         def read_document(close: true)
           @io_stream.seek(0)
           # Avoids needlessly re-packing some files
@@ -54,16 +118,17 @@ module Mindee
           @io_stream.close if close
           return ['document', data, { filename: @filename }] if pdf?
 
-          ['document', [data].pack('m'), { filename: @filename }]
+          ['document', [data].pack('m')]
         end
       end
 
       # Load a document from a path.
       class PathInputSource < LocalInputSource
         # @param filepath [String]
-        def initialize(filepath)
+        # @param fix_pdf [Boolean]
+        def initialize(filepath, fix_pdf: false)
           io_stream = File.open(filepath, 'rb')
-          super(io_stream, File.basename(filepath))
+          super(io_stream, File.basename(filepath), fix_pdf: fix_pdf)
         end
       end
 
@@ -71,10 +136,11 @@ module Mindee
       class Base64InputSource < LocalInputSource
         # @param base64_string [String]
         # @param filename [String]
-        def initialize(base64_string, filename)
+        # @param fix_pdf [Boolean]
+        def initialize(base64_string, filename, fix_pdf: false)
           io_stream = StringIO.new(base64_string.unpack1('m*'))
           io_stream.set_encoding Encoding::BINARY
-          super(io_stream, filename)
+          super(io_stream, filename, fix_pdf: fix_pdf)
         end
       end
 
@@ -82,19 +148,22 @@ module Mindee
       class BytesInputSource < LocalInputSource
         # @param raw_bytes [String]
         # @param filename [String]
-        def initialize(raw_bytes, filename)
+        # @param fix_pdf [Boolean]
+        def initialize(raw_bytes, filename, fix_pdf: false)
           io_stream = StringIO.new(raw_bytes)
           io_stream.set_encoding Encoding::BINARY
-          super(io_stream, filename)
+          super(io_stream, filename, fix_pdf: fix_pdf)
         end
       end
 
       # Load a document from a file handle.
       class FileInputSource < LocalInputSource
+        # @param file_handle [String]
         # @param filename [String]
-        def initialize(file_handle, filename)
+        # @param fix_pdf [Boolean]
+        def initialize(file_handle, filename, fix_pdf: false)
           io_stream = file_handle
-          super(io_stream, filename)
+          super(io_stream, filename, fix_pdf: fix_pdf)
         end
       end
 

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

@@ -6,14 +6,21 @@ require 'time'
 module Mindee
   module Parsing
     module Common
+      # Potential values for queue in asynchronous calls.
       module JobStatus
+        # Document is waiting to be processed.
         WAITING = :waiting
+        # Document is currently being parsed.
         PROCESSING = :processing
+        # Document parsing is complete.
         COMPLETED = :completed
       end
 
+      # Potential values for requests.
       module RequestStatus
+        # Failed.
         FAILURE = :failure
+        # Success.
         SUCCESS = :success
       end
 
@@ -88,10 +95,13 @@ module Mindee
         attr_reader :job
         # @return [Mindee::Parsing::Common::ApiRequest]
         attr_reader :api_request
+        # @return [String]
+        attr_reader :raw_http
 
         # @param product_class [Class<Mindee::Product>]
         # @param http_response [Hash]
-        def initialize(product_class, http_response)
+        def initialize(product_class, http_response, raw_http)
+          @raw_http = raw_http
           if http_response.key?('api_request')
             @api_request = Mindee::Parsing::Common::ApiRequest.new(http_response['api_request'])
           end

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

@@ -33,8 +33,8 @@ module Mindee
           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 << "\n#{@prediction.to_s.size.positive? ? "#{@prediction}\n" : ''}"
+          out_str << "\nPage Predictions\n================\n\n"
           out_str << @pages.map(&:to_s).join("\n\n")
         end
       end

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

@@ -5,6 +5,7 @@ require_relative 'mvision_v1'
 module Mindee
   module Parsing
     module Common
+      # Ocr-specific parsing fields and options
       module Ocr
         # A single word.
         class OcrWord

data/lib/mindee/parsing/common.rb

@@ -2,7 +2,6 @@
 
 require_relative 'common/api_response'
 require_relative 'common/document'
-require_relative 'common/error'
 require_relative 'common/inference'
 require_relative 'common/ocr'
 require_relative 'common/prediction'

data/lib/mindee/parsing/standard/company_registration_field.rb

@@ -4,7 +4,7 @@ module Mindee
   module Parsing
     module Standard
       # Company registration number or code, and its type.
-      class CompanyRegistration < Field
+      class CompanyRegistrationField < Field
         # @return [String]
         attr_reader :type
 

data/lib/mindee/parsing/standard/locale_field.rb

@@ -4,7 +4,7 @@ module Mindee
   module Parsing
     module Standard
       # Represents locale information
-      class Locale
+      class LocaleField
         # The confidence score, value will be between 0.0 and 1.0
         # @return [Float]
         attr_reader :confidence

data/lib/mindee/parsing/standard/payment_details_field.rb

@@ -6,7 +6,7 @@ module Mindee
   module Parsing
     module Standard
       # Represents payment details for invoices and receipts
-      class PaymentDetails < Field
+      class PaymentDetailsField < Field
         # @return [String, nil]
         attr_reader :account_number
         # @return [String, nil]

data/lib/mindee/parsing/standard/position_field.rb

@@ -29,12 +29,19 @@ module Mindee
           @value = @polygon
         end
 
+        # rubocop:disable Metrics/CyclomaticComplexity
+        # rubocop:disable Metrics/PerceivedComplexity
         # @return [String]
         def to_s
-          out_str = String.new
-          out_str << "Polygon with #{@polygon.size} points." if @polygon
-          out_str
+          return "Polygon with #{@polygon.size} points." if @polygon&.size&.positive?
+          return "Polygon with #{@bounding_box.size} points." if @bounding_box&.size&.positive?
+          return "Polygon with #{@rectangle.size} points." if @rectangle&.size&.positive?
+          return "Polygon with #{@quadrangle.size} points." if @quadrangle&.size&.positive?
+
+          ''
         end
+        # rubocop:enable Metrics/CyclomaticComplexity
+        # rubocop:enable Metrics/PerceivedComplexity
 
         private
 

data/lib/mindee/parsing/standard/{text_field.rb → string_field.rb}

@@ -6,7 +6,7 @@ module Mindee
   module Parsing
     module Standard
       # Represents basic text information.
-      class TextField < Field
+      class StringField < Field
         # Value as String
         # @return [String, nil]
         attr_reader :value

data/lib/mindee/parsing/standard.rb

@@ -8,5 +8,5 @@ require_relative 'standard/date_field'
 require_relative 'standard/payment_details_field'
 require_relative 'standard/position_field'
 require_relative 'standard/tax_field'
-require_relative 'standard/text_field'
+require_relative 'standard/string_field'
 require_relative 'standard/locale_field'

data/lib/mindee/pdf/pdf_processing.rb

@@ -6,9 +6,10 @@ require_relative 'pdf_tools'
 
 module Mindee
   module PDF
-    # Module for PDF document handling
+    # PDF document processing
     module PdfProcessor
       Origami::PDF.class_eval { include PDFTools }
+      # Default options for pdf documents processing.
       DEFAULT_OPTIONS = {
         page_indexes: [0],
         operation: :KEEP_ONLY,

data/lib/mindee/product/barcode_reader/barcode_reader_v1.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative '../../parsing'
+require_relative 'barcode_reader_v1_document'
+require_relative 'barcode_reader_v1_page'
+
+module Mindee
+  module Product
+    # Barcode Reader module.
+    module BarcodeReader
+      # Barcode Reader V1 prediction inference.
+      class BarcodeReaderV1 < Mindee::Parsing::Common::Inference
+        @endpoint_name = 'barcode_reader'
+        @endpoint_version = '1'
+
+        # @param prediction [Hash]
+        def initialize(prediction)
+          super
+          @prediction = BarcodeReaderV1Document.new(prediction['prediction'], nil)
+          @pages = []
+          prediction['pages'].each do |page|
+            @pages.push(BarcodeReaderV1Page.new(page))
+          end
+        end
+
+        class << self
+          # Name of the endpoint for this product.
+          # @return [String]
+          attr_reader :endpoint_name
+          # Version for this product.
+          # @return [String]
+          attr_reader :endpoint_version
+        end
+      end
+    end
+  end
+end

data/lib/mindee/product/barcode_reader/barcode_reader_v1_document.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative '../../parsing'
+
+module Mindee
+  module Product
+    module BarcodeReader
+      # Barcode Reader V1 document prediction.
+      class BarcodeReaderV1Document < Mindee::Parsing::Common::Prediction
+        include Mindee::Parsing::Standard
+        # List of decoded 1D barcodes.
+        # @return [Array<Mindee::Parsing::Standard::StringField>]
+        attr_reader :codes_1d
+        # List of decoded 2D barcodes.
+        # @return [Array<Mindee::Parsing::Standard::StringField>]
+        attr_reader :codes_2d
+
+        # @param prediction [Hash]
+        # @param page_id [Integer, nil]
+        def initialize(prediction, page_id)
+          super()
+          @codes_1d = []
+          prediction['codes_1d'].each do |item|
+            @codes_1d.push(StringField.new(item, page_id))
+          end
+          @codes_2d = []
+          prediction['codes_2d'].each do |item|
+            @codes_2d.push(StringField.new(item, page_id))
+          end
+        end
+
+        # @return [String]
+        def to_s
+          codes_1d = @codes_1d.join("\n #{' ' * 13}")
+          codes_2d = @codes_2d.join("\n #{' ' * 13}")
+          out_str = String.new
+          out_str << "\n:Barcodes 1D: #{codes_1d}".rstrip
+          out_str << "\n:Barcodes 2D: #{codes_2d}".rstrip
+          out_str[1..].to_s
+        end
+      end
+    end
+  end
+end

data/lib/mindee/product/barcode_reader/barcode_reader_v1_page.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative '../../parsing'
+require_relative 'barcode_reader_v1_document'
+
+module Mindee
+  module Product
+    module BarcodeReader
+      # Barcode Reader V1 page.
+      class BarcodeReaderV1Page < Mindee::Parsing::Common::Page
+        # @param prediction [Hash]
+        def initialize(prediction)
+          super(prediction)
+          @prediction = BarcodeReaderV1PagePrediction.new(
+            prediction['prediction'],
+            prediction['id']
+          )
+        end
+      end
+
+      # Barcode Reader V1 page prediction.
+      class BarcodeReaderV1PagePrediction < BarcodeReaderV1Document
+        # @return [String]
+        def to_s
+          out_str = String.new
+          out_str << "\n#{super}"
+          out_str
+        end
+      end
+    end
+  end
+end

data/lib/mindee/product/cropper/cropper_v1.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative '../../parsing'
+require_relative 'cropper_v1_document'
+require_relative 'cropper_v1_page'
+
+module Mindee
+  module Product
+    # Cropper module.
+    module Cropper
+      # Cropper V1 prediction inference.
+      class CropperV1 < Mindee::Parsing::Common::Inference
+        @endpoint_name = 'cropper'
+        @endpoint_version = '1'
+
+        # @param prediction [Hash]
+        def initialize(prediction)
+          super
+          @prediction = CropperV1Document.new
+          @pages = []
+          prediction['pages'].each do |page|
+            @pages.push(CropperV1Page.new(page))
+          end
+        end
+
+        class << self
+          # Name of the endpoint for this product.
+          # @return [String]
+          attr_reader :endpoint_name
+          # Version for this product.
+          # @return [String]
+          attr_reader :endpoint_version
+        end
+      end
+    end
+  end
+end

data/lib/mindee/product/cropper/cropper_v1_document.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative '../../parsing'
+
+module Mindee
+  module Product
+    module Cropper
+      # Cropper V1 document prediction.
+      class CropperV1Document < Mindee::Parsing::Common::Prediction
+      end
+    end
+  end
+end

data/lib/mindee/product/cropper/cropper_v1_page.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative '../../parsing'
+require_relative 'cropper_v1_document'
+
+module Mindee
+  module Product
+    module Cropper
+      # Cropper V1 page.
+      class CropperV1Page < Mindee::Parsing::Common::Page
+        # @param prediction [Hash]
+        def initialize(prediction)
+          super(prediction)
+          @prediction = CropperV1PagePrediction.new(
+            prediction['prediction'],
+            prediction['id']
+          )
+        end
+      end
+
+      # Cropper V1 page prediction.
+      class CropperV1PagePrediction < CropperV1Document
+        include Mindee::Parsing::Standard
+
+        # List of documents found in the image.
+        # @return [Array<Mindee::Parsing::Standard::PositionField>]
+        attr_reader :cropping
+
+        # @param prediction [Hash]
+        # @param page_id [Integer, nil]
+        def initialize(prediction, page_id)
+          @cropping = []
+          prediction['cropping'].each do |item|
+            @cropping.push(PositionField.new(item, page_id))
+          end
+          super()
+        end
+
+        # @return [String]
+        def to_s
+          cropping = @cropping.join("\n #{' ' * 18}")
+          out_str = String.new
+          out_str << "\n:Document Cropper: #{cropping}".rstrip
+          out_str
+        end
+      end
+    end
+  end
+end

data/lib/mindee/product/custom/custom_v1.rb

@@ -5,6 +5,7 @@ require_relative 'custom_v1_page'
 
 module Mindee
   module Product
+    # Custom product module.
     module Custom
       # Custom Document V1 prediction inference.
       class CustomV1 < Mindee::Parsing::Common::Inference

data/lib/mindee/product/eu/license_plate/license_plate_v1.rb

@@ -7,6 +7,7 @@ require_relative 'license_plate_v1_page'
 module Mindee
   module Product
     module EU
+      # License Plate module.
       module LicensePlate
         # License Plate V1 prediction inference.
         class LicensePlateV1 < Mindee::Parsing::Common::Inference

data/lib/mindee/product/eu/license_plate/license_plate_v1_document.rb

@@ -10,7 +10,7 @@ module Mindee
         class LicensePlateV1Document < Mindee::Parsing::Common::Prediction
           include Mindee::Parsing::Standard
           # List of all license plates found in the image.
-          # @return [Array<Mindee::Parsing::Standard::TextField>]
+          # @return [Array<Mindee::Parsing::Standard::StringField>]
           attr_reader :license_plates
 
           # @param prediction [Hash]
@@ -19,7 +19,7 @@ module Mindee
             super()
             @license_plates = []
             prediction['license_plates'].each do |item|
-              @license_plates.push(TextField.new(item, page_id))
+              @license_plates.push(StringField.new(item, page_id))
             end
           end
 

data/lib/mindee/product/financial_document/financial_document_v1.rb

@@ -6,6 +6,7 @@ require_relative 'financial_document_v1_page'
 
 module Mindee
   module Product
+    # Financial Document module.
     module FinancialDocument
       # Financial Document V1 prediction inference.
       class FinancialDocumentV1 < Mindee::Parsing::Common::Inference