mindee 3.1.0 → 3.2.0

data/docs/bank_check_v1.md

@@ -0,0 +1,179 @@
+---
+title: US Bank Check OCR Ruby
+---
+The Ruby OCR SDK supports the [Bank Check API](https://platform.mindee.com/mindee/bank_check).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/bank_check/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![Bank Check sample](https://github.com/mindee/client-lib-test-data/blob/main/products/bank_check/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.parse(
+  input_source,
+  Mindee::Product::US::BankCheck::BankCheckV1
+)
+
+# 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: b9809586-57ae-4f84-a35d-a85b2be1f2a2
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/bank_check v1.0
+:Rotation applied: Yes
+
+Prediction
+==========
+:Check Issue Date: 2022-03-29
+:Amount: 15332.90
+:Payees: JOHN DOE
+         JANE DOE
+:Routing Number:
+:Account Number: 7789778136
+:Check Number: 0003401
+
+Page Predictions
+================
+
+Page 0
+------
+:Check Position: Polygon with 21 points.
+:Signature Positions: Polygon with 6 points.
+:Check Issue Date: 2022-03-29
+:Amount: 15332.90
+:Payees: JOHN DOE
+         JANE DOE
+:Routing Number:
+:Account Number: 7789778136
+:Check Number: 0003401
+```
+
+# 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, is `nil` when at document-level.
+* **reconstructed** (`Boolean`): indicates whether or not 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.
+
+
+### Amount Field
+The amount field `AmountField` only has one constraint: its **value** is a `Float` (or `nil`).
+
+### 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.
+
+
+### Position Field
+The position field `PositionField` does not implement all the basic `Field` attributes, only **bounding_box**, **polygon** and **page_id**. On top of these, it has access to:
+
+* **rectangle** (`Mindee::Geometry::Quadrilateral`): a Polygon with four points that may be oriented (even beyond canvas).
+* **quadrangle** (`Mindee::Geometry::Quadrilateral`): a free polygon made up of four points.
+
+### String Field
+The text field `StringField` only has one constraint: it's **value** is a `String` (or `nil`).
+
+## Page-Level Fields
+Some fields are constrained to the page level, and so will not be retrievable to through the document.
+
+# Attributes
+The following fields are extracted for Bank Check V1:
+
+## Account Number
+**account_number** ([StringField](#string-field)): The check payer's account number.
+
+```rb
+puts result.document.inference.prediction.account_number.value
+```
+
+## Amount
+**amount** ([AmountField](#amount-field)): The amount of the check.
+
+```rb
+puts result.document.inference.prediction.amount.value
+```
+
+## Check Number
+**check_number** ([StringField](#string-field)): The issuer's check number.
+
+```rb
+puts result.document.inference.prediction.check_number.value
+```
+
+## Check Position
+[📄](#page-level-fields "This field is only present on individual pages.")**check_position** ([PositionField](#position-field)): The position of the check on the document.
+
+```rb
+for check_position_elem in result.document.check_position do
+  puts check_position_elem.polygon
+end
+```
+
+## Check Issue Date
+**date** ([DateField](#date-field)): The date the check was issued.
+
+```rb
+puts result.document.inference.prediction.date.value
+```
+
+## Payees
+**payees** (Array<[StringField](#string-field)>): List of the check's payees (recipients).
+
+```rb
+for payees_elem in result.document.inference.prediction.payees do
+  puts payees_elem.value
+end
+```
+
+## Routing Number
+**routing_number** ([StringField](#string-field)): The check issuer's routing number.
+
+```rb
+puts result.document.inference.prediction.routing_number.value
+```
+
+## Signature Positions
+[📄](#page-level-fields "This field is only present on individual pages.")**signatures_positions** (Array<[PositionField](#position-field)>): List of signature positions
+
+```rb
+for page in result.document.inference.pages do
+  for signatures_positions_elem in page.prediction.signatures_positions do
+    puts signatures_positions_elem.polygon
+  end
+end
+```
+
+# Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)

data/docs/barcode_reader_v1.md

@@ -0,0 +1,104 @@
+---
+title: Barcode Reader API Ruby
+---
+The Ruby OCR SDK supports the [Barcode Reader API](https://platform.mindee.com/mindee/barcode_reader).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/barcode_reader/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![Barcode Reader sample](https://github.com/mindee/client-lib-test-data/blob/main/products/barcode_reader/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.parse(
+  input_source,
+  Mindee::Product::BarcodeReader::BarcodeReaderV1
+)
+
+# 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: 0f54c154-5030-41ac-939e-046b7f6aca71
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/barcode_reader v1.0
+:Rotation applied: Yes
+
+Prediction
+==========
+:Barcodes 1D: Mindee
+:Barcodes 2D: https://developers.mindee.com/docs/barcode-reader-ocr
+              I love paperwork! - Said no one ever
+
+Page Predictions
+================
+
+Page 0
+------
+:Barcodes 1D: Mindee
+:Barcodes 2D: https://developers.mindee.com/docs/barcode-reader-ocr
+              I love paperwork! - Said no one ever
+```
+
+# 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, is `nil` when at document-level.
+* **reconstructed** (`Boolean`): indicates whether or not 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.
+
+### 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 Barcode Reader V1:
+
+## Barcodes 1D
+**codes_1d** (Array<[StringField](#string-field)>): List of decoded 1D barcodes.
+
+```rb
+for codes_1d_elem in result.document.inference.prediction.codes_1d do
+  puts codes_1d_elem.value
+end
+```
+
+## Barcodes 2D
+**codes_2d** (Array<[StringField](#string-field)>): List of decoded 2D barcodes.
+
+```rb
+for codes_2d_elem in result.document.inference.prediction.codes_2d do
+  puts codes_2d_elem.value
+end
+```
+
+# Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)

data/docs/carte_vitale_v1.md

@@ -0,0 +1,123 @@
+---
+title: FR Carte Vitale OCR Ruby
+---
+The Ruby OCR SDK supports the [Carte Vitale API](https://platform.mindee.com/mindee/carte_vitale).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/carte_vitale/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![Carte Vitale sample](https://github.com/mindee/client-lib-test-data/blob/main/products/carte_vitale/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.parse(
+  input_source,
+  Mindee::Product::FR::CarteVitale::CarteVitaleV1
+)
+
+# 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: 8c25cc63-212b-4537-9c9b-3fbd3bd0ee20
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/carte_vitale v1.0
+:Rotation applied: Yes
+
+Prediction
+==========
+:Given Name(s): NATHALIE
+:Surname: DURAND
+:Social Security Number: 269054958815780
+:Issuance Date: 2007-01-01
+
+Page Predictions
+================
+
+Page 0
+------
+:Given Name(s): NATHALIE
+:Surname: DURAND
+:Social Security Number: 269054958815780
+:Issuance Date: 2007-01-01
+```
+
+# 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, is `nil` when at document-level.
+* **reconstructed** (`Boolean`): indicates whether or not 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.
+
+### 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 Carte Vitale V1:
+
+## Given Name(s)
+**given_names** (Array<[StringField](#string-field)>): The given name(s) of the card holder.
+
+```rb
+for given_names_elem in result.document.inference.prediction.given_names do
+  puts given_names_elem.value
+end
+```
+
+## Issuance Date
+**issuance_date** ([DateField](#date-field)): The date the card was issued.
+
+```rb
+puts result.document.inference.prediction.issuance_date.value
+```
+
+## Social Security Number
+**social_security** ([StringField](#string-field)): The Social Security Number (Numéro de Sécurité Sociale) of the card holder
+
+```rb
+puts result.document.inference.prediction.social_security.value
+```
+
+## Surname
+**surname** ([StringField](#string-field)): The surname of the card holder.
+
+```rb
+puts result.document.inference.prediction.surname.value
+```
+
+# Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)

data/docs/code_samples/barcode_reader_v1.txt

@@ -0,0 +1,19 @@
+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.parse(
+  input_source,
+  Mindee::Product::BarcodeReader::BarcodeReaderV1
+)
+
+# 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

data/docs/code_samples/cropper_v1.txt

@@ -0,0 +1,16 @@
+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.parse(
+  input_source,
+  Mindee::Product::Cropper::CropperV1
+)
+
+# Print a full summary of the parsed data in RST format
+puts result.document

data/docs/code_samples/idcard_fr_v2.txt

@@ -0,0 +1,19 @@
+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.parse(
+  input_source,
+  Mindee::Product::FR::IdCard::IdCardV2
+)
+
+# 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

data/docs/code_samples/invoice_splitter_v1_async.txt

@@ -6,61 +6,13 @@ 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')
 
-# Put the document class in a local variable to keep the code DRY
-doc_class = Mindee::Product::InvoiceSplitter::InvoiceSplitterV1
-
-# Limit the amount of API calls to retrieve your document
-MAX_RETRIES = 10
-
-# How many seconds to wait in-between tries
-INTERVAL_SECS = 6
-
-# Counter to keep track of how many times we try to retrieve the document
-times_tried = 1
-
-queue_result = mindee_client.enqueue(
+result = mindee_client.enqueue_and_parse(
   input_source,
-  doc_class
+  Mindee::Product::InvoiceSplitter::InvoiceSplitterV1
 )
 
-# Get the id of the queue (job)
-queue_id = queue_result.job.id
-
-# Recursive function that tries to retrieve the completed document.
-# If the document is not "complete", try again
-def get_doc_from_async_queue(
-    queue_id,
-    mindee_client,
-    doc_class,
-    times_tried=0,
-    interval_secs=INTERVAL_SECS,
-    max_retries=MAX_RETRIES
-  )
-    # Have we exceeded our retry count?
-    if times_tried >= max_retries
-      raise "Maximum retries reached #{times_tried}"
-    end
-
-    # Wait for a few seconds before fetching
-    sleep interval_secs
-
-    # Fetch and parse the result, using the same type
-    parsed_result = mindee_client.parse_queued(queue_id, doc_class)
-
-    # Check whether the result is ready
-    if parsed_result.job.status == Mindee::Parsing::Common::JobStatus::COMPLETED
-        # Print a brief summary of the parsed data
-        puts parsed_result.document
-        return
-    # Otherwise, try again...
-    else
-      get_doc_from_async_queue(
-        queue_id, mindee_client,
-        doc_class,
-        times_tried+1
-      )
-    end
-end
+# Print a full summary of the parsed data in RST format
+puts result.document
 
-# Start the recursion...
-get_doc_from_async_queue(queue_id, mindee_client, doc_class)
+# Print the document-level parsed data
+# puts result.document.inference.prediction

data/docs/code_samples/multi_receipts_detector_v1.txt

@@ -0,0 +1,19 @@
+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.parse(
+  input_source,
+  Mindee::Product::MultiReceiptsDetector::MultiReceiptsDetectorV1
+)
+
+# 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

data/docs/code_samples/us_w9_v1.txt

@@ -0,0 +1,16 @@
+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.parse(
+  input_source,
+  Mindee::Product::US::W9::W9V1
+)
+
+# Print a full summary of the parsed data in RST format
+puts result.document

data/docs/cropper_v1.md

@@ -0,0 +1,97 @@
+---
+title: Cropper API Ruby
+---
+The Ruby OCR SDK supports the [Cropper API](https://platform.mindee.com/mindee/cropper).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/cropper/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![Cropper sample](https://github.com/mindee/client-lib-test-data/blob/main/products/cropper/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.parse(
+  input_source,
+  Mindee::Product::Cropper::CropperV1
+)
+
+# Print a full summary of the parsed data in RST format
+puts result.document
+```
+
+**Output (RST):**
+```rst
+########
+Document
+########
+:Mindee ID: 149ce775-8302-4798-8649-7eda9fb84a1a
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/cropper v1.0
+:Rotation applied: No
+
+Prediction
+==========
+
+Page Predictions
+================
+
+Page 0
+------
+:Document Cropper: Polygon with 26 points.
+                   Polygon with 25 points.
+```
+
+# 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, is `nil` when at document-level.
+* **reconstructed** (`Boolean`): indicates whether or not 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.
+
+
+### Position Field
+The position field `PositionField` does not implement all the basic `Field` attributes, only **bounding_box**, **polygon** and **page_id**. On top of these, it has access to:
+
+* **rectangle** (`Mindee::Geometry::Quadrilateral`): a Polygon with four points that may be oriented (even beyond canvas).
+* **quadrangle** (`Mindee::Geometry::Quadrilateral`): a free polygon made up of four points.
+
+## Page-Level Fields
+Some fields are constrained to the page level, and so will not be retrievable to through the document.
+
+# Attributes
+The following fields are extracted for Cropper V1:
+
+## Document Cropper
+[📄](#page-level-fields "This field is only present on individual pages.")**cropping** (Array<[PositionField](#position-field)>): List of documents found in the image.
+
+```rb
+for page in result.document.inference.pages do
+  for cropping_elem in page.prediction.cropping do
+    puts cropping_elem.polygon
+  end
+end
+```
+
+# Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)