mindee 3.14.0 → 3.16.0

data/docs/ind_passport_v1.md

@@ -0,0 +1,281 @@
+---
+title: IND Passport - India OCR Ruby
+category: 622b805aaec68102ea7fcbc2
+slug: ruby-ind-passport---india-ocr
+parentDoc: 6294d97ee723f1008d2ab28e
+---
+The Ruby OCR SDK supports the [Passport - India API](https://platform.mindee.com/mindee/ind_passport).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/ind_passport/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![Passport - India sample](https://github.com/mindee/client-lib-test-data/blob/main/products/ind_passport/default_sample.jpg?raw=true)
+
+# Quick-Start
+```rb
+require 'mindee'
+
+# Init a new client
+mindee_client = Mindee::Client.new(api_key: 'my-api-key')
+
+# Load a file from disk
+input_source = mindee_client.source_from_path('/path/to/the/file.ext')
+
+# Parse the file
+result = mindee_client.enqueue_and_parse(
+  input_source,
+  Mindee::Product::IND::IndianPassport::IndianPassportV1
+)
+
+# Print a full summary of the parsed data in RST format
+puts result.document
+
+# Print the document-level parsed data
+# puts result.document.inference.prediction
+
+```
+
+**Output (RST):**
+```rst
+########
+Document
+########
+:Mindee ID: cf88fd43-eaa1-497a-ba29-a9569a4edaa7
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/ind_passport v1.0
+:Rotation applied: Yes
+
+Prediction
+==========
+:Page Number: 1
+:Country: IND
+:ID Number: J8369854
+:Given Names: JOCELYN MICHELLE
+:Surname: DOE
+:Birth Date: 1959-09-23
+:Birth Place: GUNDUGOLANU
+:Issuance Place: HYDERABAD
+:Gender: F
+:Issuance Date: 2011-10-11
+:Expiry Date: 2021-10-10
+:MRZ Line 1: P<DOE<<JOCELYNMICHELLE<<<<<<<<<<<<<<<<<<<<<
+:MRZ Line 2: J8369854<4IND5909234F2110101<<<<<<<<<<<<<<<8
+:Legal Guardian:
+:Name of Spouse:
+:Name of Mother:
+:Old Passport Date of Issue:
+:Old Passport Number:
+:Address Line 1:
+:Address Line 2:
+:Address Line 3:
+:Old Passport Place of Issue:
+:File Number:
+```
+
+# Field Types
+## Standard Fields
+These fields are generic and used in several products.
+
+### Basic Field
+Each prediction object contains a set of fields that inherit from the generic `Field` class.
+A typical `Field` object will have the following attributes:
+
+* **value** (`String`, `Float`, `Integer`, `Boolean`): corresponds to the field value. Can be `nil` if no value was extracted.
+* **confidence** (Float, nil): the confidence score of the field prediction.
+* **bounding_box** (`Mindee::Geometry::Quadrilateral`, `nil`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document.
+* **polygon** (`Mindee::Geometry::Polygon`, `nil`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image.
+* **page_id** (`Integer`, `nil`): the ID of the page, always `nil` when at document-level.
+* **reconstructed** (`Boolean`): indicates whether an object was reconstructed (not extracted as the API gave it).
+
+
+Aside from the previous attributes, all basic fields have access to a `to_s` method that can be used to print their value as a string.
+
+
+### Classification Field
+The classification field `ClassificationField` does not implement all the basic `Field` attributes. It only implements **value**, **confidence** and **page_id**.
+
+> Note: a classification field's `value is always a `String`.
+
+### Date Field
+Aside from the basic `Field` attributes, the date field `DateField` also implements the following: 
+
+* **date_object** (`Date`): an accessible representation of the value as a JavaScript object.
+
+### String Field
+The text field `StringField` only has one constraint: it's **value** is a `String` (or `nil`).
+
+# Attributes
+The following fields are extracted for Passport - India V1:
+
+## Address Line 1
+**address1** ([StringField](#string-field)): The first line of the address of the passport holder.
+
+```rb
+puts result.document.inference.prediction.address1.value
+```
+
+## Address Line 2
+**address2** ([StringField](#string-field)): The second line of the address of the passport holder.
+
+```rb
+puts result.document.inference.prediction.address2.value
+```
+
+## Address Line 3
+**address3** ([StringField](#string-field)): The third line of the address of the passport holder.
+
+```rb
+puts result.document.inference.prediction.address3.value
+```
+
+## Birth Date
+**birth_date** ([DateField](#date-field)): The birth date of the passport holder, ISO format: YYYY-MM-DD.
+
+```rb
+puts result.document.inference.prediction.birth_date.value
+```
+
+## Birth Place
+**birth_place** ([StringField](#string-field)): The birth place of the passport holder.
+
+```rb
+puts result.document.inference.prediction.birth_place.value
+```
+
+## Country
+**country** ([StringField](#string-field)): ISO 3166-1 alpha-3 country code (3 letters format).
+
+```rb
+puts result.document.inference.prediction.country.value
+```
+
+## Expiry Date
+**expiry_date** ([DateField](#date-field)): The date when the passport will expire, ISO format: YYYY-MM-DD.
+
+```rb
+puts result.document.inference.prediction.expiry_date.value
+```
+
+## File Number
+**file_number** ([StringField](#string-field)): The file number of the passport document.
+
+```rb
+puts result.document.inference.prediction.file_number.value
+```
+
+## Gender
+**gender** ([ClassificationField](#classification-field)): The gender of the passport holder.
+
+#### Possible values include:
+ - M
+ - F
+
+```rb
+puts result.document.inference.prediction.gender.value
+```
+
+## Given Names
+**given_names** ([StringField](#string-field)): The given names of the passport holder.
+
+```rb
+puts result.document.inference.prediction.given_names.value
+```
+
+## ID Number
+**id_number** ([StringField](#string-field)): The identification number of the passport document.
+
+```rb
+puts result.document.inference.prediction.id_number.value
+```
+
+## Issuance Date
+**issuance_date** ([DateField](#date-field)): The date when the passport was issued, ISO format: YYYY-MM-DD.
+
+```rb
+puts result.document.inference.prediction.issuance_date.value
+```
+
+## Issuance Place
+**issuance_place** ([StringField](#string-field)): The place where the passport was issued.
+
+```rb
+puts result.document.inference.prediction.issuance_place.value
+```
+
+## Legal Guardian
+**legal_guardian** ([StringField](#string-field)): The name of the legal guardian of the passport holder (if applicable).
+
+```rb
+puts result.document.inference.prediction.legal_guardian.value
+```
+
+## MRZ Line 1
+**mrz1** ([StringField](#string-field)): The first line of the machine-readable zone (MRZ) of the passport document.
+
+```rb
+puts result.document.inference.prediction.mrz1.value
+```
+
+## MRZ Line 2
+**mrz2** ([StringField](#string-field)): The second line of the machine-readable zone (MRZ) of the passport document.
+
+```rb
+puts result.document.inference.prediction.mrz2.value
+```
+
+## Name of Mother
+**name_of_mother** ([StringField](#string-field)): The name of the mother of the passport holder.
+
+```rb
+puts result.document.inference.prediction.name_of_mother.value
+```
+
+## Name of Spouse
+**name_of_spouse** ([StringField](#string-field)): The name of the spouse of the passport holder (if applicable).
+
+```rb
+puts result.document.inference.prediction.name_of_spouse.value
+```
+
+## Old Passport Date of Issue
+**old_passport_date_of_issue** ([DateField](#date-field)): The date of issue of the old passport (if applicable), ISO format: YYYY-MM-DD.
+
+```rb
+puts result.document.inference.prediction.old_passport_date_of_issue.value
+```
+
+## Old Passport Number
+**old_passport_number** ([StringField](#string-field)): The number of the old passport (if applicable).
+
+```rb
+puts result.document.inference.prediction.old_passport_number.value
+```
+
+## Old Passport Place of Issue
+**old_passport_place_of_issue** ([StringField](#string-field)): The place of issue of the old passport (if applicable).
+
+```rb
+puts result.document.inference.prediction.old_passport_place_of_issue.value
+```
+
+## Page Number
+**page_number** ([ClassificationField](#classification-field)): The page number of the passport document.
+
+#### Possible values include:
+ - 1
+ - 2
+
+```rb
+puts result.document.inference.prediction.page_number.value
+```
+
+## Surname
+**surname** ([StringField](#string-field)): The surname of the passport holder.
+
+```rb
+puts result.document.inference.prediction.surname.value
+```
+
+# Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/invoices_v4.md

@@ -63,21 +63,23 @@ puts result.document
 ########
 Document
 ########
-:Mindee ID: 372d9d08-59d8-4e1c-9622-06648c1c238b
+:Mindee ID: a67b70ea-4b1e-4eac-ae75-dda47a7064ae
 :Filename: default_sample.jpg
 
 Inference
 #########
-:Product: mindee/invoices v4.7
+:Product: mindee/invoices v4.9
 :Rotation applied: Yes
 
 Prediction
 ==========
-:Locale: en; en; CAD;
+:Locale: en-CA; en; CA; CAD;
 :Invoice Number: 14
+:Purchase Order Number: AD29094
 :Reference Numbers: AD29094
 :Purchase Date: 2018-09-25
-:Due Date:
+:Due Date: 2011-12-01
+:Payment Date: 2011-12-01
 :Total Net: 2145.00
 :Total Amount: 2608.20
 :Total Tax: 193.20
@@ -93,7 +95,7 @@ Prediction
 :Supplier Address: 156 University Ave, Toronto ON, Canada, M5H 2H7
 :Supplier Phone Number: 4165551212
 :Supplier Website:
-:Supplier Email: ldoi@example.com
+:Supplier Email: j_coi@example.com
 :Customer Name: JIRO DOI
 :Customer Company Registrations:
 :Customer Address: 1954 Bloor Street West Toronto, ON, M6P 3K9 Canada
@@ -117,11 +119,13 @@ Page Predictions
 
 Page 0
 ------
-:Locale: en; en; CAD;
+:Locale: en-CA; en; CA; CAD;
 :Invoice Number: 14
+:Purchase Order Number: AD29094
 :Reference Numbers: AD29094
 :Purchase Date: 2018-09-25
-:Due Date:
+:Due Date: 2011-12-01
+:Payment Date: 2011-12-01
 :Total Net: 2145.00
 :Total Amount: 2608.20
 :Total Tax: 193.20
@@ -137,7 +141,7 @@ Page 0
 :Supplier Address: 156 University Ave, Toronto ON, Canada, M5H 2H7
 :Supplier Phone Number: 4165551212
 :Supplier Website:
-:Supplier Email: ldoi@example.com
+:Supplier Email: j_coi@example.com
 :Customer Name: JIRO DOI
 :Customer Company Registrations:
 :Customer Address: 1954 Bloor Street West Toronto, ON, M6P 3K9 Canada

data/docs/resume_v1.md

@@ -38,13 +38,13 @@ puts result.document
 ########
 Document
 ########
-:Mindee ID: bc80bae0-af75-4464-95a9-2419403c75bf
+:Mindee ID: 9daa3085-152c-454e-9245-636f13fc9dc3
 :Filename: default_sample.jpg
 
 Inference
 #########
-:Product: mindee/resume v1.0
-:Rotation applied: No
+:Product: mindee/resume v1.1
+:Rotation applied: Yes
 
 Prediction
 ==========
@@ -54,8 +54,8 @@ Prediction
 :Surnames: Morgan
 :Nationality:
 :Email Address: christoper.m@gmail.com
-:Phone Number: +44 (0) 20 7666 8555
-:Address: 177 Great Portland Street, London W5W 6PQ
+:Phone Number: +44 (0)20 7666 8555
+:Address: 177 Great Portland Street, London, W5W 6PQ
 :Social Networks:
   +----------------------+----------------------------------------------------+
   | Name                 | URL                                                |
@@ -72,38 +72,37 @@ Prediction
   +----------+----------------------+
   | ZHO      | Beginner             |
   +----------+----------------------+
-  | DEU      | Intermediate         |
+  | DEU      | Beginner             |
   +----------+----------------------+
 :Hard Skills: HTML5
               PHP OOP
               JavaScript
               CSS
               MySQL
+              SQL
 :Soft Skills: Project management
+              Creative design
               Strong decision maker
               Innovative
               Complex problem solver
-              Creative design
               Service-focused
 :Education:
   +-----------------+---------------------------+-----------+----------+---------------------------+-------------+------------+
   | Domain          | Degree                    | End Month | End Year | School                    | Start Month | Start Year |
   +=================+===========================+===========+==========+===========================+=============+============+
-  | Computer Inf... | Bachelor                  |           |          | Columbia University, NY   |             | 2014       |
+  | Computer Inf... | Bachelor                  |           | 2014     | Columbia University, NY   |             |            |
   +-----------------+---------------------------+-----------+----------+---------------------------+-------------+------------+
 :Professional Experiences:
-  +-----------------+------------+---------------------------+-----------+----------+----------------------+-------------+------------+
-  | Contract Type   | Department | Employer                  | End Month | End Year | Role                 | Start Month | Start Year |
-  +=================+============+===========================+===========+==========+======================+=============+============+
-  | Full-Time       |            | Luna Web Design, New York | 05        | 2019     | Web Developer        | 09          | 2015       |
-  +-----------------+------------+---------------------------+-----------+----------+----------------------+-------------+------------+
+  +-----------------+------------+--------------------------------------+---------------------------+-----------+----------+----------------------+-------------+------------+
+  | Contract Type   | Department | Description                          | Employer                  | End Month | End Year | Role                 | Start Month | Start Year |
+  +=================+============+======================================+===========================+===========+==========+======================+=============+============+
+  |                 |            | Cooperate with designers to creat... | Luna Web Design, New York | 05        | 2019     | Web Developer        | 09          | 2015       |
+  +-----------------+------------+--------------------------------------+---------------------------+-----------+----------+----------------------+-------------+------------+
 :Certificates:
   +------------+--------------------------------+---------------------------+------+
   | Grade      | Name                           | Provider                  | Year |
   +============+================================+===========================+======+
-  |            | PHP Framework (certificate)... |                           | 2014 |
-  +------------+--------------------------------+---------------------------+------+
-  |            | Programming Languages: Java... |                           |      |
+  |            | PHP Framework (certificate)... |                           |      |
   +------------+--------------------------------+---------------------------+------+
 ```
 
@@ -171,6 +170,7 @@ A `ResumeV1Language` implements the following attributes:
 * `level` (String): The candidate's level for the language.
 
 #### Possible values include:
+ - Native
  - Fluent
  - Proficient
  - Intermediate
@@ -192,6 +192,7 @@ A `ResumeV1ProfessionalExperience` implements the following attributes:
  - Freelance
 
 * `department` (String): The specific department or division within the company.
+* `description` (String): The description of the professional experience as written in the document.
 * `employer` (String): The name of the company or organization.
 * `end_month` (String): The month when the professional experience ended.
 * `end_year` (String): The year when the professional experience ended.

data/lib/mindee/client.rb

@@ -128,6 +128,7 @@ module Mindee
     end
 
     # rubocop:disable Metrics/ParameterLists
+
     # Enqueue a document for async parsing and automatically try to retrieve it
     #
     # @param input_source [Mindee::Input::Source::LocalInputSource, Mindee::Input::Source::UrlInputSource]
@@ -148,8 +149,8 @@ module Mindee
     #  * `:on_min_pages` Apply the operation only if document has at least this many pages.
     # @param cropper [Boolean, nil] Whether to include cropper results for each page.
     #  This performs a cropping operation on the server and will increase response time.
-    # @param initial_delay_sec [Integer, Float] initial delay before polling. Defaults to 4.
-    # @param delay_sec [Integer, Float] delay between polling attempts. Defaults to 2.
+    # @param initial_delay_sec [Integer, Float] initial delay before polling. Defaults to 2.
+    # @param delay_sec [Integer, Float] delay between polling attempts. Defaults to 1.5.
     # @param max_retries [Integer] maximum amount of retries. Defaults to 60.
     # @return [Mindee::Parsing::Common::ApiResponse]
     def enqueue_and_parse(
@@ -161,8 +162,8 @@ module Mindee
       close_file: true,
       page_options: nil,
       cropper: false,
-      initial_delay_sec: 4,
-      delay_sec: 2,
+      initial_delay_sec: 2,
+      delay_sec: 1.5,
       max_retries: 60
     )
       enqueue_res = enqueue(
@@ -271,13 +272,13 @@ module Mindee
     # @param max_retries [Integer, nil] maximum amount of retries.
     def validate_async_params(initial_delay_sec, delay_sec, max_retries)
       min_delay_sec = 1
-      min_initial_delay_sec = 2
+      min_initial_delay_sec = 1
       min_retries = 2
-      raise "Cannot set auto-poll delay to less than #{min_delay_sec} seconds" if delay_sec < min_delay_sec
+      raise "Cannot set auto-poll delay to less than #{min_delay_sec} second(s)" if delay_sec < min_delay_sec
       if initial_delay_sec < min_initial_delay_sec
-        raise "Cannot set initial parsing delay to less than #{min_initial_delay_sec} seconds"
+        raise "Cannot set initial parsing delay to less than #{min_initial_delay_sec} second(s)"
       end
-      raise "Cannot set auto-poll delay to less than #{min_retries} seconds" if max_retries < min_retries
+      raise "Cannot set auto-poll retries to less than #{min_retries}" if max_retries < min_retries
     end
 
     # Creates an endpoint with the given values. Raises an error if the endpoint is invalid.

data/lib/mindee/extraction/common/extracted_image.rb

@@ -54,7 +54,6 @@ module Mindee
         image = MiniMagick::Image.read(@buffer)
         image.format file_format.downcase
         image.write resolved_path.to_s
-        logger.info("File saved successfully to '#{resolved_path}'.")
       rescue TypeError
         raise 'Invalid path/filename provided.'
       rescue StandardError

data/lib/mindee/extraction/common/image_extractor.rb

@@ -11,8 +11,8 @@ module Mindee
   # Image Extraction Module.
   module Extraction
     # Image Extraction wrapper class.
-    class ImageExtractor
-      def self.attach_image_as_new_file(input_buffer)
+    module ImageExtractor
+      def self.attach_image_as_new_file(input_buffer, format: 'jpg')
         # Attaches an image as a new page in a PdfDocument object.
         #
         # @param [StringIO] input_buffer Input buffer. Only supports JPEG.
@@ -21,9 +21,9 @@ module Mindee
         magick_image = MiniMagick::Image.read(input_buffer)
         # NOTE: some jpeg images get rendered as three different versions of themselves per output if the format isn't
         # converted.
-        magick_image.format('jpg')
+        magick_image.format(format)
         original_density = magick_image.resolution
-        scale_factor = original_density[0].to_f / 4.166666 # No clue why bit the resolution needs to be reduced for
+        scale_factor = original_density[0].to_f / 4.166666 # No clue why the resolution needs to be reduced for
         # the pdf otherwise the resulting image shrinks.
         magick_image.format('pdf', 0, { density: scale_factor.to_s })
         Origami::PDF.read(StringIO.new(magick_image.to_blob))
@@ -37,27 +37,12 @@ module Mindee
       # to extract.
       # @return [Array<Mindee::Extraction::ExtractedImage>] Extracted Images.
       def self.extract_multiple_images_from_source(input_source, page_id, polygons)
-        new_stream = load_doc(input_source, page_id)
+        new_stream = load_input_source_pdf_page_as_image(input_source, page_id)
         new_stream.seek(0)
 
         extract_images_from_polygons(input_source, new_stream, page_id, polygons)
       end
 
-      # Retrieves a PDF document's page.
-      #
-      # @param [Origami::PDF] pdf_doc Origami PDF handle.
-      # @param [Integer] page_id Page ID.
-      def self.get_page(pdf_doc, page_id)
-        stream = StringIO.new
-        pdf_doc.save(stream)
-
-        options = {
-          page_indexes: [page_id - 1],
-        }
-
-        Mindee::PDF::PdfProcessor.parse(stream, options)
-      end
-
       # Extracts images from their positions on a file (as polygons).
       #
       # @param [Mindee::Input::Source::LocalInputSource] input_source Local input source.
@@ -179,10 +164,10 @@ module Mindee
       # @param input_file [LocalInputSource] Local input.
       # @param [Integer] page_id Page ID.
       # @return [MiniMagick::Image] A valid PdfDocument handle.
-      def self.load_doc(input_file, page_id)
+      def self.load_input_source_pdf_page_as_image(input_file, page_id)
         input_file.io_stream.rewind
         if input_file.pdf?
-          get_page(Origami::PDF.read(input_file.io_stream), page_id)
+          Mindee::PDF::PdfProcessor.get_page(Origami::PDF.read(input_file.io_stream), page_id)
         else
           input_file.io_stream
         end

data/lib/mindee/extraction/pdf_extractor/pdf_extractor.rb

@@ -65,6 +65,7 @@ module Mindee
 
         # rubocop:disable Metrics/CyclomaticComplexity
         # rubocop:disable Metrics/PerceivedComplexity
+
         # Extracts invoices as complete PDFs from the document.
         # @param page_indexes [Array<Array<Integer>, InvoiceSplitterV1PageGroup>]
         # @param strict [Boolean]
@@ -99,6 +100,7 @@ module Mindee
           end
           extract_sub_documents(correct_page_indexes)
         end
+
         # rubocop:enable Metrics/CyclomaticComplexity
         # rubocop:enable Metrics/PerceivedComplexity
 

data/lib/mindee/extraction/tax_extractor/tax_extractor.rb

@@ -271,6 +271,7 @@ module Mindee
         end
         candidates
       end
+
       # rubocop:enable Metrics/CyclomaticComplexity
       # rubocop:enable Metrics/PerceivedComplexity
 

data/lib/mindee/geometry/point.rb

@@ -10,9 +10,10 @@ module Mindee
       # @return [Float]
       attr_accessor :y
 
+      # rubocop:disable Naming/MethodParameterName
+
       # @param x [Float]
       # @param y [Float]
-      # rubocop:disable Naming/MethodParameterName
       def initialize(x, y)
         @x = x
         @y = y

data/lib/mindee/image/image_compressor.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Mindee
+  # Image processing module.
+  module Image
+    # Image compressor module to handle image compression.
+    module ImageCompressor
+      # Resize and/or compress an SKBitmap. This assumes the ratio was provided before hands.
+      # @param image [MiniMagick::Image, StringIO] Input image.
+      # @param quality [Integer, nil] Quality of the final file.
+      # @param max_width [Integer, nil] 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.
+      # @return [StringIO]
+      def self.compress_image(image, quality: 85, max_width: nil, max_height: nil)
+        processed_image = ImageUtils.to_image(image)
+        processed_image.format 'jpg'
+        final_width, final_height = ImageUtils.calculate_new_dimensions(
+          processed_image,
+          max_width: max_width,
+          max_height: max_height
+        )
+        ImageUtils.resize_image(processed_image, final_width, final_height) if final_width || final_height
+        ImageUtils.compress_image_quality(processed_image, quality)
+
+        ImageUtils.image_to_stringio(processed_image)
+      end
+    end
+  end
+end