mindee 3.1.0 → 3.2.0

data/docs/passport_v1.md

@@ -0,0 +1,186 @@
+---
+title: Passport OCR Ruby
+---
+The Ruby OCR SDK supports the [Passport API](https://platform.mindee.com/mindee/passport).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/passport/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![Passport sample](https://github.com/mindee/client-lib-test-data/blob/main/products/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.parse(
+  input_source,
+  Mindee::Product::Passport::PassportV1
+)
+
+# 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: 18e41f6c-16cd-4f8e-8cd2-00ca02a35764
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/passport v1.0
+:Rotation applied: Yes
+
+Prediction
+==========
+:Country Code: GBR
+:ID Number: 707797979
+:Given Name(s): HENERT
+:Surname: PUDARSAN
+:Date of Birth: 1995-05-20
+:Place of Birth: CAMTETH
+:Gender: M
+:Date of Issue: 2012-04-22
+:Expiry Date: 2017-04-22
+:MRZ Line 1: P<GBRPUDARSAN<<HENERT<<<<<<<<<<<<<<<<<<<<<<<
+:MRZ Line 2: 7077979792GBR9505209M1704224<<<<<<<<<<<<<<00
+
+Page Predictions
+================
+
+Page 0
+------
+:Country Code: GBR
+:ID Number: 707797979
+:Given Name(s): HENERT
+:Surname: PUDARSAN
+:Date of Birth: 1995-05-20
+:Place of Birth: CAMTETH
+:Gender: M
+:Date of Issue: 2012-04-22
+:Expiry Date: 2017-04-22
+:MRZ Line 1: P<GBRPUDARSAN<<HENERT<<<<<<<<<<<<<<<<<<<<<<<
+:MRZ Line 2: 7077979792GBR9505209M1704224<<<<<<<<<<<<<<00
+```
+
+# 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 Passport V1:
+
+## Date of Birth
+**birth_date** ([DateField](#date-field)): The date of birth of the passport holder.
+
+```rb
+puts result.document.inference.prediction.birth_date.value
+```
+
+## Place of Birth
+**birth_place** ([StringField](#string-field)): The place of birth of the passport holder.
+
+```rb
+puts result.document.inference.prediction.birth_place.value
+```
+
+## Country Code
+**country** ([StringField](#string-field)): The country's 3 letter code (ISO 3166-1 alpha-3).
+
+```rb
+puts result.document.inference.prediction.country.value
+```
+
+## Expiry Date
+**expiry_date** ([DateField](#date-field)): The expiry date of the passport.
+
+```rb
+puts result.document.inference.prediction.expiry_date.value
+```
+
+## Gender
+**gender** ([StringField](#string-field)): The gender of the passport holder.
+
+```rb
+puts result.document.inference.prediction.gender.value
+```
+
+## Given Name(s)
+**given_names** (Array<[StringField](#string-field)>): The given name(s) of the passport holder.
+
+```rb
+for given_names_elem in result.document.inference.prediction.given_names do
+  puts given_names_elem.value
+end
+```
+
+## ID Number
+**id_number** ([StringField](#string-field)): The passport's identification number.
+
+```rb
+puts result.document.inference.prediction.id_number.value
+```
+
+## Date of Issue
+**issuance_date** ([DateField](#date-field)): The date the passport was issued.
+
+```rb
+puts result.document.inference.prediction.issuance_date.value
+```
+
+## MRZ Line 1
+**mrz1** ([StringField](#string-field)): Machine Readable Zone, first line
+
+```rb
+puts result.document.inference.prediction.mrz1.value
+```
+
+## MRZ Line 2
+**mrz2** ([StringField](#string-field)): Machine Readable Zone, second line
+
+```rb
+puts result.document.inference.prediction.mrz2.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-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)

data/docs/proof_of_address_v1.md

@@ -0,0 +1,207 @@
+---
+title: Proof of Address OCR Ruby
+---
+The Ruby OCR SDK supports the [Proof of Address API](https://platform.mindee.com/mindee/proof_of_address).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/proof_of_address/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK.
+![Proof of Address sample](https://github.com/mindee/client-lib-test-data/blob/main/products/proof_of_address/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::ProofOfAddress::ProofOfAddressV1
+)
+
+# 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: 3a7e1da6-d4d0-4704-af91-051fe5484c2e
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/proof_of_address v1.0
+:Rotation applied: Yes
+
+Prediction
+==========
+:Locale: en; en; USD;
+:Issuer Name: PPL ELECTRIC UTILITIES
+:Issuer Company Registrations:
+:Issuer Address: 2 NORTH 9TH STREET CPC-GENN1 ALLENTOWN,PA 18101-1175
+:Recipient Name:
+:Recipient Company Registrations:
+:Recipient Address: 123 MAIN ST ANYTOWN,PA 18062
+:Dates: 2011-07-27
+        2011-07-06
+        2011-08-03
+        2011-07-27
+        2011-06-01
+        2011-07-01
+        2010-07-01
+        2010-08-01
+        2011-07-01
+        2009-08-01
+        2010-07-01
+        2011-07-27
+:Date of Issue: 2011-07-27
+
+Page Predictions
+================
+
+Page 0
+------
+:Locale: en; en; USD;
+:Issuer Name: PPL ELECTRIC UTILITIES
+:Issuer Company Registrations:
+:Issuer Address: 2 NORTH 9TH STREET CPC-GENN1 ALLENTOWN,PA 18101-1175
+:Recipient Name:
+:Recipient Company Registrations:
+:Recipient Address: 123 MAIN ST ANYTOWN,PA 18062
+:Dates: 2011-07-27
+        2011-07-06
+        2011-08-03
+        2011-07-27
+        2011-06-01
+        2011-07-01
+        2010-07-01
+        2010-08-01
+        2011-07-01
+        2009-08-01
+        2010-07-01
+        2011-07-27
+:Date of Issue: 2011-07-27
+```
+
+# 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.
+
+
+### Company Registration Field
+Aside from the basic `Field` attributes, the company registration field `CompanyRegistrationField` also implements the following:
+
+* **type** (`String`): the type of company.
+
+### 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.
+
+### Locale Field
+The locale field `LocaleField` only implements the **value**, **confidence** and **page_id** base `Field` attributes, but it comes with its own:
+
+* **language** (`String`): ISO 639-1 language code (e.g.: `en` for English). Can be `nil`.
+* **country** (`String`): ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code for countries (e.g.: `GRB` or `GB` for "Great Britain"). Can be `nil`.
+* **currency** (`String`): ISO 4217 code for currencies (e.g.: `USD` for "US Dollars"). Can be `nil`.
+
+### 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 Proof of Address V1:
+
+## Date of Issue
+**date** ([DateField](#date-field)): The date the document was issued.
+
+```rb
+puts result.document.inference.prediction.date.value
+```
+
+## Dates
+**dates** (Array<[DateField](#date-field)>): List of dates found on the document.
+
+```rb
+for dates_elem in result.document.inference.prediction.dates do
+  puts dates_elem.value
+end
+```
+
+## Issuer Address
+**issuer_address** ([StringField](#string-field)): The address of the document's issuer.
+
+```rb
+puts result.document.inference.prediction.issuer_address.value
+```
+
+## Issuer Company Registrations
+**issuer_company_registration** (Array<[CompanyRegistrationField](#company-registration-field)>): List of company registrations found for the issuer.
+
+```rb
+for issuer_company_registration_elem in result.document.inference.prediction.issuer_company_registration do
+  puts issuer_company_registration_elem.value
+end
+```
+
+## Issuer Name
+**issuer_name** ([StringField](#string-field)): The name of the person or company issuing the document.
+
+```rb
+puts result.document.inference.prediction.issuer_name.value
+```
+
+## Locale
+**locale** ([LocaleField](#locale-field)): The locale detected on the document.
+
+```rb
+puts result.document.inference.prediction.locale.value
+```
+
+## Recipient Address
+**recipient_address** ([StringField](#string-field)): The address of the recipient.
+
+```rb
+puts result.document.inference.prediction.recipient_address.value
+```
+
+## Recipient Company Registrations
+**recipient_company_registration** (Array<[CompanyRegistrationField](#company-registration-field)>): List of company registrations found for the recipient.
+
+```rb
+for recipient_company_registration_elem in result.document.inference.prediction.recipient_company_registration do
+  puts recipient_company_registration_elem.value
+end
+```
+
+## Recipient Name
+**recipient_name** ([StringField](#string-field)): The name of the person or company receiving the document.
+
+```rb
+puts result.document.inference.prediction.recipient_name.value
+```
+
+# Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)

data/docs/us_driver_license_v1.md

@@ -0,0 +1,268 @@
+---
+title: US Driver License OCR Ruby
+---
+The Ruby OCR SDK supports the [Driver License API](https://platform.mindee.com/mindee/us_driver_license).
+
+Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/us_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/us_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::US::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: bf70068d-d3d6-49dc-b93a-b4b7d156fc3d
+:Filename: default_sample.jpg
+
+Inference
+#########
+:Product: mindee/us_driver_license v1.0
+:Rotation applied: Yes
+
+Prediction
+==========
+:State: AZ
+:Driver License ID: D12345678
+:Expiry Date: 2018-02-01
+:Date Of Issue: 2013-01-10
+:Last Name: SAMPLE
+:First Name: JELANI
+:Address: 123 MAIN STREET PHOENIX AZ 85007
+:Date Of Birth: 1957-02-01
+:Restrictions: NONE
+:Endorsements: NONE
+:Class:
+:Sex: M
+:Height: 5-08
+:Weight: 185
+:Hair Color: BRO
+:Eye Color: BRO
+:Document Discriminator: 1234567890123456
+
+Page Predictions
+================
+
+Page 0
+------
+:Photo: Polygon with 4 points.
+:Signature: Polygon with 4 points.
+:State: AZ
+:Driver License ID: D12345678
+:Expiry Date: 2018-02-01
+:Date Of Issue: 2013-01-10
+:Last Name: SAMPLE
+:First Name: JELANI
+:Address: 123 MAIN STREET PHOENIX AZ 85007
+:Date Of Birth: 1957-02-01
+:Restrictions: NONE
+:Endorsements: NONE
+:Class:
+:Sex: M
+:Height: 5-08
+:Weight: 185
+:Hair Color: BRO
+:Eye Color: BRO
+:Document Discriminator: 1234567890123456
+```
+
+# 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.
+
+
+### 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)): US driver license holders address
+
+```rb
+puts result.document.inference.prediction.address.value
+```
+
+## Date Of Birth
+**date_of_birth** ([DateField](#date-field)): US driver license holders date of birth
+
+```rb
+puts result.document.inference.prediction.date_of_birth.value
+```
+
+## Document Discriminator
+**dd_number** ([StringField](#string-field)): Document Discriminator Number of the US Driver License
+
+```rb
+puts result.document.inference.prediction.dd_number.value
+```
+
+## Driver License Class
+**dl_class** ([StringField](#string-field)): US driver license holders class
+
+```rb
+puts result.document.inference.prediction.dl_class.value
+```
+
+## Driver License ID
+**driver_license_id** ([StringField](#string-field)): ID number of the US Driver License.
+
+```rb
+puts result.document.inference.prediction.driver_license_id.value
+```
+
+## Endorsements
+**endorsements** ([StringField](#string-field)): US driver license holders endorsements
+
+```rb
+puts result.document.inference.prediction.endorsements.value
+```
+
+## Expiry Date
+**expiry_date** ([DateField](#date-field)): Date on which the documents expires.
+
+```rb
+puts result.document.inference.prediction.expiry_date.value
+```
+
+## Eye Color
+**eye_color** ([StringField](#string-field)): US driver license holders eye colour
+
+```rb
+puts result.document.inference.prediction.eye_color.value
+```
+
+## First Name
+**first_name** ([StringField](#string-field)): US driver license holders first name(s)
+
+```rb
+puts result.document.inference.prediction.first_name.value
+```
+
+## Hair Color
+**hair_color** ([StringField](#string-field)): US driver license holders hair colour
+
+```rb
+puts result.document.inference.prediction.hair_color.value
+```
+
+## Height
+**height** ([StringField](#string-field)): US driver license holders hight
+
+```rb
+puts result.document.inference.prediction.height.value
+```
+
+## Date Of Issue
+**issued_date** ([DateField](#date-field)): Date on which the documents was issued.
+
+```rb
+puts result.document.inference.prediction.issued_date.value
+```
+
+## Last Name
+**last_name** ([StringField](#string-field)): US driver license holders last name
+
+```rb
+puts result.document.inference.prediction.last_name.value
+```
+
+## Photo
+[📄](#page-level-fields "This field is only present on individual pages.")**photo** ([PositionField](#position-field)): Has a photo of the US driver license holder
+
+```rb
+for photo_elem in result.document.photo do
+  puts photo_elem.polygon
+end
+```
+
+## Restrictions
+**restrictions** ([StringField](#string-field)): US driver license holders restrictions
+
+```rb
+puts result.document.inference.prediction.restrictions.value
+```
+
+## Sex
+**sex** ([StringField](#string-field)): US driver license holders gender
+
+```rb
+puts result.document.inference.prediction.sex.value
+```
+
+## Signature
+[📄](#page-level-fields "This field is only present on individual pages.")**signature** ([PositionField](#position-field)): Has a signature of the US driver license holder
+
+```rb
+for signature_elem in result.document.signature do
+  puts signature_elem.polygon
+end
+```
+
+## State
+**state** ([StringField](#string-field)): US State
+
+```rb
+puts result.document.inference.prediction.state.value
+```
+
+## Weight
+**weight** ([StringField](#string-field)): US driver license holders weight
+
+```rb
+puts result.document.inference.prediction.weight.value
+```
+
+# Questions?
+[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)