mindee 3.4.0 → 3.6.0

data/docs/eu_driver_license_v1.md

@@ -0,0 +1,223 @@
+---
+title: EU Driver License OCR Ruby
+---
+The Ruby OCR SDK supports the [Driver License API](https://platform.mindee.com/mindee/eu_driver_license).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/eu_driver_license/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![Driver License sample](https://github.com/mindee/client-lib-test-data/blob/main/products/eu_driver_license/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::EU::DriverLicense::DriverLicenseV1
+)
+
+# 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: b19cc32e-b3e6-4ff9-bdc7-619199355d54
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/eu_driver_license v1.0
+:Rotation applied: Yes
+
+Prediction
+==========
+:Country Code: FR
+:Document ID: 13AA00002
+:Driver License Category: AM A1 B1 B D BE DE
+:Last Name: MARTIN
+:First Name: PAUL
+:Date Of Birth: 1981-07-14
+:Place Of Birth: Utopiacity
+:Expiry Date: 2018-12-31
+:Issue Date: 2013-01-01
+:Issue Authority: 99999UpiaCity
+:MRZ: D1FRA13AA000026181231MARTIN<<9
+:Address:
+
+Page Predictions
+================
+
+Page 0
+------
+:Photo: Polygon with 4 points.
+:Signature: Polygon with 4 points.
+:Country Code: FR
+:Document ID: 13AA00002
+:Driver License Category: AM A1 B1 B D BE DE
+:Last Name: MARTIN
+:First Name: PAUL
+:Date Of Birth: 1981-07-14
+:Place Of Birth: Utopiacity
+:Expiry Date: 2018-12-31
+:Issue Date: 2013-01-01
+:Issue Authority: 99999UpiaCity
+:MRZ: D1FRA13AA000026181231MARTIN<<9
+:Address:
+```
+
+# 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 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.
+
+
+### 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 Driver License V1:
+
+## Address
+**address** ([StringField](#string-field)): EU driver license holders address
+
+```rb
+puts result.document.inference.prediction.address.value
+```
+
+## Driver License Category
+**category** ([StringField](#string-field)): EU driver license holders categories
+
+```rb
+puts result.document.inference.prediction.category.value
+```
+
+## Country Code
+**country_code** ([StringField](#string-field)): Country code extracted as a string.
+
+```rb
+puts result.document.inference.prediction.country_code.value
+```
+
+## Date Of Birth
+**date_of_birth** ([DateField](#date-field)): The date of birth of the document holder
+
+```rb
+puts result.document.inference.prediction.date_of_birth.value
+```
+
+## Document ID
+**document_id** ([StringField](#string-field)): ID number of the Document.
+
+```rb
+puts result.document.inference.prediction.document_id.value
+```
+
+## Expiry Date
+**expiry_date** ([DateField](#date-field)): Date the document expires
+
+```rb
+puts result.document.inference.prediction.expiry_date.value
+```
+
+## First Name
+**first_name** ([StringField](#string-field)): First name(s) of the driver license holder
+
+```rb
+puts result.document.inference.prediction.first_name.value
+```
+
+## Issue Authority
+**issue_authority** ([StringField](#string-field)): Authority that issued the document
+
+```rb
+puts result.document.inference.prediction.issue_authority.value
+```
+
+## Issue Date
+**issue_date** ([DateField](#date-field)): Date the document was issued
+
+```rb
+puts result.document.inference.prediction.issue_date.value
+```
+
+## Last Name
+**last_name** ([StringField](#string-field)): Last name of the driver license holder.
+
+```rb
+puts result.document.inference.prediction.last_name.value
+```
+
+## MRZ
+**mrz** ([StringField](#string-field)): Machine-readable license number
+
+```rb
+puts result.document.inference.prediction.mrz.value
+```
+
+## Photo
+[📄](#page-level-fields "This field is only present on individual pages.")**photo** ([PositionField](#position-field)): Has a photo of the EU driver license holder
+
+```rb
+for photo_elem in result.document.photo do
+  puts photo_elem.polygon
+end
+```
+
+## Place Of Birth
+**place_of_birth** ([StringField](#string-field)): Place where the driver license holder was born
+
+```rb
+puts result.document.inference.prediction.place_of_birth.value
+```
+
+## Signature
+[📄](#page-level-fields "This field is only present on individual pages.")**signature** ([PositionField](#position-field)): Has a signature of the EU driver license holder
+
+```rb
+for signature_elem in result.document.signature do
+  puts signature_elem.polygon
+end
+```
+
+# Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/expense_receipts_v5.md

@@ -303,4 +303,4 @@ puts result.document.inference.prediction.total_tax.value
 ```
 
 # Questions?
-[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/financial_document_v1.md

@@ -34,48 +34,52 @@ puts result.document
 ########
 Document
 ########
-:Mindee ID: 81c1d637-3a84-41d9-b40a-f72ca2a58826
+:Mindee ID: a6b54e2d-a7fa-4e08-8de6-6cd296f50f3d
 :Filename: default_sample.jpg
 
 Inference
 #########
-:Product: mindee/financial_document v1.1
+:Product: mindee/financial_document v1.2
 :Rotation applied: Yes
 
 Prediction
 ==========
 :Locale: en; en; USD;
-:Invoice Number:
-:Reference Numbers:
-:Purchase Date: 2014-07-07
-:Due Date: 2014-07-07
-:Total Net: 40.48
-:Total Amount: 53.82
+:Invoice Number: INT-001
+:Reference Numbers: 2412/2019
+:Purchase Date: 2019-02-11
+:Due Date: 2019-02-26
+:Total Net: 195.00
+:Total Amount: 204.75
 :Taxes:
   +---------------+--------+----------+---------------+
   | Base          | Code   | Rate (%) | Amount        |
   +===============+========+==========+===============+
-  |               | TAX    |          | 3.34          |
+  |               |        | 5.00     | 9.75          |
   +---------------+--------+----------+---------------+
 :Supplier Payment Details:
-:Supplier Name: LOGANS
+:Supplier Name: JOHN SMITH
 :Supplier Company Registrations:
-:Supplier Address: 2513 s stemmons freeway lewisville tx 75067
-:Supplier Phone Number: 9724596042
-:Customer Name:
+:Supplier Address: 4490 Oak Drive Albany, NY 12210
+:Supplier Phone Number:
+:Customer Name: JESSIE M HORNE
 :Customer Company Registrations:
-:Customer Address:
-:Document Type: EXPENSE RECEIPT
-:Purchase Subcategory: restaurant
-:Purchase Category: food
-:Total Tax: 3.34
-:Tip and Gratuity: 10.00
-:Purchase Time: 20:20
+:Customer Address: 2019 Redbud Drive New York, NY 10011
+:Document Type: INVOICE
+:Purchase Subcategory:
+:Purchase Category: miscellaneous
+:Total Tax: 9.75
+:Tip and Gratuity:
+:Purchase Time:
 :Line Items:
   +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
   | Description                          | Product code | Quantity | Tax Amount | Tax Rate (%) | Total Amount | Unit Price |
   +======================================+==============+==========+============+==============+==============+============+
-  | TAX                                  |              |          |            |              | 3.34         |            |
+  | Front and rear brake cables          |              | 1.00     |            |              | 100.00       | 100.00     |
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
+  | New set of pedal arms                |              | 2.00     |            |              | 50.00        | 25.00      |
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
+  | Labon 3hrs                           |              | 3.00     |            |              | 45.00        | 15.00      |
   +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
 
 Page Predictions
@@ -84,37 +88,41 @@ Page Predictions
 Page 0
 ------
 :Locale: en; en; USD;
-:Invoice Number:
-:Reference Numbers:
-:Purchase Date: 2014-07-07
-:Due Date: 2014-07-07
-:Total Net: 40.48
-:Total Amount: 53.82
+:Invoice Number: INT-001
+:Reference Numbers: 2412/2019
+:Purchase Date: 2019-02-11
+:Due Date: 2019-02-26
+:Total Net: 195.00
+:Total Amount: 204.75
 :Taxes:
   +---------------+--------+----------+---------------+
   | Base          | Code   | Rate (%) | Amount        |
   +===============+========+==========+===============+
-  |               | TAX    |          | 3.34          |
+  |               |        | 5.00     | 9.75          |
   +---------------+--------+----------+---------------+
 :Supplier Payment Details:
-:Supplier Name: LOGANS
+:Supplier Name: JOHN SMITH
 :Supplier Company Registrations:
-:Supplier Address: 2513 s stemmons freeway lewisville tx 75067
-:Supplier Phone Number: 9724596042
-:Customer Name:
+:Supplier Address: 4490 Oak Drive Albany, NY 12210
+:Supplier Phone Number:
+:Customer Name: JESSIE M HORNE
 :Customer Company Registrations:
-:Customer Address:
-:Document Type: EXPENSE RECEIPT
-:Purchase Subcategory: restaurant
-:Purchase Category: food
-:Total Tax: 3.34
-:Tip and Gratuity: 10.00
-:Purchase Time: 20:20
+:Customer Address: 2019 Redbud Drive New York, NY 10011
+:Document Type: INVOICE
+:Purchase Subcategory:
+:Purchase Category: miscellaneous
+:Total Tax: 9.75
+:Tip and Gratuity:
+:Purchase Time:
 :Line Items:
   +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
   | Description                          | Product code | Quantity | Tax Amount | Tax Rate (%) | Total Amount | Unit Price |
   +======================================+==============+==========+============+==============+==============+============+
-  | TAX                                  |              |          |            |              | 3.34         |            |
+  | Front and rear brake cables          |              | 1.00     |            |              | 100.00       | 100.00     |
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
+  | New set of pedal arms                |              | 2.00     |            |              | 50.00        | 25.00      |
+  +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
+  | Labon 3hrs                           |              | 3.00     |            |              | 45.00        | 15.00      |
   +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+
 ```
 
@@ -384,4 +392,4 @@ puts result.document.inference.prediction.total_tax.value
 ```
 
 # Questions?
-[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/generated_v1.md

@@ -0,0 +1,90 @@
+---
+title: Generated API Ruby
+---
+The Ruby OCR SDK supports generated APIs.
+Generated APIs can theoretically support all APIs in a catch-all generic format.
+
+# Quick-Start
+
+```ruby
+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')
+
+# Initialize a custom endpoint for this product
+custom_endpoint = mindee_client.create_endpoint(
+  account_name: 'my-account',
+  endpoint_name: 'my-endpoint',
+  version: 'my-version'
+)
+
+# Parse the file
+result = mindee_client.enqueue_and_parse(
+  input_source,
+  Mindee::Product::Generated::GeneratedV1,
+  endpoint: custom_endpoint
+)
+
+# Print a full summary of the parsed data in RST format
+puts result.document
+```
+
+# Generated Endpoints
+
+You may have noticed in the previous step that in order to access a custom build, you will need to provide an account and an endpoint name at the very least.
+
+Although it is optional, the version number should match the latest version of your build in most use-cases.
+If it is not set, it will default to "1".
+
+# Field Types
+
+## Generated Fields
+
+### Generated List Field
+
+A `GeneratedListField` is a special type of custom list that implements the following:
+
+- **values** (`Array<StringField`[GeneratedObjectField](#Generated-object-field)`>`): the confidence score of the field prediction.
+- **page_id** (`Integer`): only available for some documents ATM.
+
+Since the inner contents can vary, the value isn't accessed through a property, but rather through the following functions:
+
+- **contents_list()** (`-> Array<String, Float>>`): returns a list of values for each element.
+- **contents_string(separator=" ")** (`-> String`): returns a list of concatenated values, with an optional **separator** `String` between them.
+> **Note:** the `to_s` method returns a string representation of all values of this object, with an empty space between each of them.
+
+### Generated Object Field
+
+Unrecognized structures and sometimes values of `ListField`s are stored in a `GeneratedObjectField` structure, which is implemented dynamically depending on the object's structure.
+
+- **page_id** (`[Integer, nil]`): the ID of the page, is `nil` when at document-level.
+- **raw_value** (`[String, nil]`): an optional field for when some post-processing has been done on fields (e.g. amounts). `nil` in most instances.
+- **confidence** (`[Float, nil]`): the confidence score of the field prediction. Warning: support isn't guaranteed on all APIs.
+
+
+> **Other fields**:No matter what, other fields will be stored in a dictionary-like structure with a `key: value` pair where `key` is a string and `value` is a nullable string. They can be accessed like any other regular value, but won't be suggested by your IDE.
+
+
+### StringField
+The text field `StringField` only has one constraint: its **value** is an `Optional[str]`.
+
+
+# Attributes
+
+Generated builds always have access to at least two attributes:
+
+## Fields
+
+**fields** (`Hash<String, Array<`[GeneratedListField](#generated-list-field),[GeneratedObjectField](#generated-object-field), `(#stringfield)[StringField]>>`):
+
+```ruby
+puts result.document.inference.prediction.fields["my-field"].to_s
+```
+
+# Questions?
+
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/getting_started.md

@@ -319,4 +319,4 @@ input_source = mindee_client.source_from_file(input_file, "name-of-my-file.ext",
 Note: This only works for local files, files sent by URL will not be processed.
 
 ## Questions?
-[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/idcard_fr_v2.md

@@ -250,4 +250,4 @@ puts result.document.inference.prediction.surname.value
 ```
 
 # Questions?
-[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/international_id_v2.md

@@ -0,0 +1,195 @@
+---
+title: International ID OCR Ruby
+---
+The Ruby OCR SDK supports the [International ID API](https://platform.mindee.com/mindee/international_id).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/international_id/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![International ID sample](https://github.com/mindee/client-lib-test-data/blob/main/products/international_id/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::InternationalId::InternationalIdV2
+)
+
+# 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
+```
+
+# 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 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 International ID V2:
+
+## Address
+**address** ([StringField](#string-field)): The physical address of the document holder.
+
+```rb
+puts result.document.inference.prediction.address.value
+```
+
+## Birth Date
+**birth_date** ([DateField](#date-field)): The date of birth of the document holder.
+
+```rb
+puts result.document.inference.prediction.birth_date.value
+```
+
+## Birth Place
+**birth_place** ([StringField](#string-field)): The place of birth of the document holder.
+
+```rb
+puts result.document.inference.prediction.birth_place.value
+```
+
+## Country of Issue
+**country_of_issue** ([StringField](#string-field)): The country where the document was issued.
+
+```rb
+puts result.document.inference.prediction.country_of_issue.value
+```
+
+## Document Number
+**document_number** ([StringField](#string-field)): The unique identifier assigned to the document.
+
+```rb
+puts result.document.inference.prediction.document_number.value
+```
+
+## Document Type
+**document_type** ([ClassificationField](#classification-field)): The type of personal identification document.
+
+```rb
+puts result.document.inference.prediction.document_type.value
+```
+
+## Expiration Date
+**expiry_date** ([DateField](#date-field)): The date when the document becomes invalid.
+
+```rb
+puts result.document.inference.prediction.expiry_date.value
+```
+
+## Given Names
+**given_names** (Array<[StringField](#string-field)>): The list of the document holder's given names.
+
+```rb
+for given_names_elem in result.document.inference.prediction.given_names do
+  puts given_names_elem.value
+end
+```
+
+## Issue Date
+**issue_date** ([DateField](#date-field)): The date when the document was issued.
+
+```rb
+puts result.document.inference.prediction.issue_date.value
+```
+
+## MRZ Line 1
+**mrz_line1** ([StringField](#string-field)): The Machine Readable Zone, first line.
+
+```rb
+puts result.document.inference.prediction.mrz_line1.value
+```
+
+## MRZ Line 2
+**mrz_line2** ([StringField](#string-field)): The Machine Readable Zone, second line.
+
+```rb
+puts result.document.inference.prediction.mrz_line2.value
+```
+
+## MRZ Line 3
+**mrz_line3** ([StringField](#string-field)): The Machine Readable Zone, third line.
+
+```rb
+puts result.document.inference.prediction.mrz_line3.value
+```
+
+## Nationality
+**nationality** ([StringField](#string-field)): The country of citizenship of the document holder.
+
+```rb
+puts result.document.inference.prediction.nationality.value
+```
+
+## Personal Number
+**personal_number** ([StringField](#string-field)): The unique identifier assigned to the document holder.
+
+```rb
+puts result.document.inference.prediction.personal_number.value
+```
+
+## Sex
+**sex** ([StringField](#string-field)): The biological sex of the document holder.
+
+```rb
+puts result.document.inference.prediction.sex.value
+```
+
+## State of Issue
+**state_of_issue** ([StringField](#string-field)): The state or territory where the document was issued.
+
+```rb
+puts result.document.inference.prediction.state_of_issue.value
+```
+
+## Surnames
+**surnames** (Array<[StringField](#string-field)>): The list of the document holder's family names.
+
+```rb
+for surnames_elem in result.document.inference.prediction.surnames do
+  puts surnames_elem.value
+end
+```
+
+# Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)

data/docs/invoice_splitter_v1.md

@@ -82,4 +82,4 @@ end
 ```
 
 # Questions?
-[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-2d0ds7dtz-DPAF81ZqTy20chsYpQBW5g)