From e1841913dae4068afb04c4d4db0a33534468a720 Mon Sep 17 00:00:00 2001 From: sebastianMindee Date: Fri, 13 Oct 2023 17:42:17 +0200 Subject: [PATCH] exported md doc --- docs/extras/guide/bank_account_details_v2.md | 138 +++++++ docs/extras/guide/bank_check_v1.md | 176 ++++++++ docs/extras/guide/barcode_reader_v1.md | 103 +++++ docs/extras/guide/carte_vitale_v1.md | 123 ++++++ docs/extras/guide/cropper_v1.md | 99 +++++ docs/extras/guide/expense_receipts_v5.md | 304 ++++++++++++++ docs/extras/guide/financial_document_v1.md | 379 ++++++++++++++++++ docs/extras/guide/idcard_fr_v2.md | 251 ++++++++++++ docs/extras/guide/invoices_v4.md | 335 ++++++++++++++++ docs/extras/guide/license_plates_v1.md | 91 +++++ .../guide/multi_receipts_detector_v1.md | 105 +++++ docs/extras/guide/passport_v1.md | 186 +++++++++ docs/extras/guide/proof_of_address_v1.md | 205 ++++++++++ docs/extras/guide/us_driver_license_v1.md | 267 ++++++++++++ docs/extras/guide/us_w9_v1.md | 199 +++++++++ 15 files changed, 2961 insertions(+) create mode 100644 docs/extras/guide/bank_account_details_v2.md create mode 100644 docs/extras/guide/bank_check_v1.md create mode 100644 docs/extras/guide/barcode_reader_v1.md create mode 100644 docs/extras/guide/carte_vitale_v1.md create mode 100644 docs/extras/guide/cropper_v1.md create mode 100644 docs/extras/guide/expense_receipts_v5.md create mode 100644 docs/extras/guide/financial_document_v1.md create mode 100644 docs/extras/guide/idcard_fr_v2.md create mode 100644 docs/extras/guide/invoices_v4.md create mode 100644 docs/extras/guide/license_plates_v1.md create mode 100644 docs/extras/guide/multi_receipts_detector_v1.md create mode 100644 docs/extras/guide/passport_v1.md create mode 100644 docs/extras/guide/proof_of_address_v1.md create mode 100644 docs/extras/guide/us_driver_license_v1.md create mode 100644 docs/extras/guide/us_w9_v1.md diff --git a/docs/extras/guide/bank_account_details_v2.md b/docs/extras/guide/bank_account_details_v2.md new file mode 100644 index 00000000..c2db17f9 --- /dev/null +++ b/docs/extras/guide/bank_account_details_v2.md @@ -0,0 +1,138 @@ +--- +title: FR Bank Account Details OCR Python +--- +The Python OCR SDK supports the [Bank Account Details API](https://platform.mindee.com/mindee/bank_account_details). + +Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/bank_account_details/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK. +![Bank Account Details sample](https://github.com/mindee/client-lib-test-data/blob/main/products/bank_account_details/default_sample.jpg?raw=true) + +# Quick-Start +```py +from mindee import Client, PredictResponse, product + +# Init a new client +mindee_client = Client(api_key="my-api-key") + +# Load a file from disk +input_doc = mindee_client.source_from_path("/path/to/the/file.ext") + +# Load a file from disk and parse it. +# The endpoint name must be specified since it cannot be determined from the class. +result: PredictResponse = mindee_client.parse(product.fr.BankAccountDetailsV2, input_doc) + +# Print a brief summary of the parsed data +print(result.document) + +# # Iterate over all the fields in the document +# for field_name, field_values in result.document.inference.prediction.fields.items(): +# print(field_name, "=", field_values) +``` + +**Output (RST):** +```rst +######## +Document +######## +:Mindee ID: bc8f7265-8dab-49fe-810c-d50049605578 +:Filename: default_sample.jpg + +Inference +######### +:Product: mindee/bank_account_details v2.0 +:Rotation applied: Yes + +Prediction +========== +:Account Holder's Names: MME HEGALALDIA L ENVOL +:Basic Bank Account Number: + :Bank Code: 13335 + :Branch Code: 00040 + :Key: 06 + :Account Number: 08932891361 +:IBAN: FR7613335000400893289136106 +:SWIFT Code: CEPAFRPP333 + +Page Predictions +================ + +Page 0 +------ +:Account Holder's Names: MME HEGALALDIA L ENVOL +:Basic Bank Account Number: + :Bank Code: 13335 + :Branch Code: 00040 + :Key: 06 + :Account Number: 08932891361 +:IBAN: FR7613335000400893289136106 +:SWIFT Code: CEPAFRPP333 +``` + +# 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 `BaseField` class. +A typical `BaseField` object will have the following attributes: + +* **value** (`Union[float, str]`): corresponds to the field value. Can be `None` if no value was extracted. +* **confidence** (`float`): the confidence score of the field prediction. +* **bounding_box** (`[Point, Point, Point, Point]`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document. +* **polygon** (`List[Point]`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image. +* **page_id** (`int`): the ID of the page, is `None` when at document-level. +* **reconstructed** (`bool`): indicates whether or not an object was reconstructed (not extracted as the API gave it). + +> **Note:** A `Point` simply refers to a List of two numbers (`[float, float]`). + + +Aside from the previous attributes, all basic fields have access to a custom `__str__` method that can be used to print their value as a string. + +### String Field +The text field `StringField` only has one constraint: its **value** is an `Optional[str]`. + +## Specific Fields +Fields which are specific to this product; they are not used in any other product. + +### Basic Bank Account Number Field +Full extraction of BBAN, including: branch code, bank code, account and key. + +A `BankAccountDetailsV2Bban` implements the following attributes: + +* **bban_bank_code** (`str`): The BBAN bank code outputted as a string. +* **bban_branch_code** (`str`): The BBAN branch code outputted as a string. +* **bban_key** (`str`): The BBAN key outputted as a string. +* **bban_number** (`str`): The BBAN Account number outputted as a string. + +# Attributes +The following fields are extracted for Bank Account Details V2: + +## Account Holder's Names +**account_holders_names** : Full extraction of the account holders names. + +```py +print(result.document.inference.prediction.account_holders_names.value) +``` + +## Basic Bank Account Number +**bban** ([BankAccountDetailsV2Bban](#basic-bank-account-number-field)): Full extraction of BBAN, including: branch code, bank code, account and key. + +```py +print(result.document.inference.prediction.bban.value) +``` + +## IBAN +**iban** : Full extraction of the IBAN number. + +```py +print(result.document.inference.prediction.iban.value) +``` + +## SWIFT Code +**swift_code** : Full extraction of the SWIFT code. + +```py +print(result.document.inference.prediction.swift_code.value) +``` + +# Questions? +[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw) diff --git a/docs/extras/guide/bank_check_v1.md b/docs/extras/guide/bank_check_v1.md new file mode 100644 index 00000000..7b00915b --- /dev/null +++ b/docs/extras/guide/bank_check_v1.md @@ -0,0 +1,176 @@ +--- +title: US Bank Check OCR Python +--- +The Python 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 +```py +from mindee import Client, PredictResponse, product + +# Init a new client +mindee_client = Client(api_key="my-api-key") + +# Load a file from disk +input_doc = mindee_client.source_from_path("/path/to/the/file.ext") + +# Load a file from disk and parse it. +# The endpoint name must be specified since it cannot be determined from the class. +result: PredictResponse = mindee_client.parse(product.us.BankCheckV1, input_doc) + +# Print a brief summary of the parsed data +print(result.document) + +# # Iterate over all the fields in the document +# for field_name, field_values in result.document.inference.prediction.fields.items(): +# print(field_name, "=", field_values) +``` + +**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 `BaseField` class. +A typical `BaseField` object will have the following attributes: + +* **value** (`Union[float, str]`): corresponds to the field value. Can be `None` if no value was extracted. +* **confidence** (`float`): the confidence score of the field prediction. +* **bounding_box** (`[Point, Point, Point, Point]`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document. +* **polygon** (`List[Point]`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image. +* **page_id** (`int`): the ID of the page, is `None` when at document-level. +* **reconstructed** (`bool`): indicates whether or not an object was reconstructed (not extracted as the API gave it). + +> **Note:** A `Point` simply refers to a List of two numbers (`[float, float]`). + + +Aside from the previous attributes, all basic fields have access to a custom `__str__` 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 an `Optional[float]`. + +### Date Field +Aside from the basic `BaseField` attributes, the date field `DateField` also implements the following: + +* **date_object** (`Date`): an accessible representation of the value as a python object. Can be `None`. + + +### Position Field +The position field `PositionField` does not implement all the basic `BaseField` attributes, only **bounding_box**, **polygon** and **page_id**. On top of these, it has access to: + +* **rectangle** (`[Point, Point, Point, Point]`): a Polygon with four points that may be oriented (even beyond canvas). +* **quadrangle** (`[Point, Point, Point, Point]`): a free polygon made up of four points. + +### String Field +The text field `StringField` only has one constraint: its **value** is an `Optional[str]`. + +## 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** : The check payer's account number. + +```py +print(result.document.inference.prediction.account_number.value) +``` + +## Amount +**amount** : The amount of the check. + +```py +print(result.document.inference.prediction.amount.value) +``` + +## Check Number +**check_number** : The issuer's check number. + +```py +print(result.document.inference.prediction.check_number.value) +``` + +## Check Position +[๐Ÿ“„](#page-level-fields "This field is only present on individual pages.")**check_position** : The position of the check on the document. + +```py +for check_position_elem of result.document.check_position: + print(check_position_elem.polygon) +``` + +## Check Issue Date +**date** : The date the check was issued. + +```py +print(result.document.inference.prediction.date.value) +``` + +## Payees +**payees** : List of the check's payees (recipients). + +```py +for payees_elem in result.document.inference.prediction.payees: + print(payees_elem.value) +``` + +## Routing Number +**routing_number** : The check issuer's routing number. + +```py +print(result.document.inference.prediction.routing_number.value) +``` + +## Signature Positions +[๐Ÿ“„](#page-level-fields "This field is only present on individual pages.")**signatures_positions** : List of signature positions + +```py +for page in result.document.inference.pages: + for signatures_positions_elem of page.prediction.signatures_positions): + print(signatures_positions_elem.polygon) +``` + +# Questions? +[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw) diff --git a/docs/extras/guide/barcode_reader_v1.md b/docs/extras/guide/barcode_reader_v1.md new file mode 100644 index 00000000..df871fe7 --- /dev/null +++ b/docs/extras/guide/barcode_reader_v1.md @@ -0,0 +1,103 @@ +--- +title: Barcode Reader OCR Python +--- +The Python 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 +```py +from mindee import Client, PredictResponse, product + +# Init a new client +mindee_client = Client(api_key="my-api-key") + +# Load a file from disk +input_doc = mindee_client.source_from_path("/path/to/the/file.ext") + +# Load a file from disk and parse it. +# The endpoint name must be specified since it cannot be determined from the class. +result: PredictResponse = mindee_client.parse(product.BarcodeReaderV1, input_doc) + +# Print a brief summary of the parsed data +print(result.document) + +# # Iterate over all the fields in the document +# for field_name, field_values in result.document.inference.prediction.fields.items(): +# print(field_name, "=", field_values) +``` + +**Output (RST):** +```rst +######## +Document +######## +:Mindee ID: f9c48da1-a306-4805-8da8-f7231fda2d88 +: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 `BaseField` class. +A typical `BaseField` object will have the following attributes: + +* **value** (`Union[float, str]`): corresponds to the field value. Can be `None` if no value was extracted. +* **confidence** (`float`): the confidence score of the field prediction. +* **bounding_box** (`[Point, Point, Point, Point]`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document. +* **polygon** (`List[Point]`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image. +* **page_id** (`int`): the ID of the page, is `None` when at document-level. +* **reconstructed** (`bool`): indicates whether or not an object was reconstructed (not extracted as the API gave it). + +> **Note:** A `Point` simply refers to a List of two numbers (`[float, float]`). + + +Aside from the previous attributes, all basic fields have access to a custom `__str__` method that can be used to print their value as a string. + +### String Field +The text field `StringField` only has one constraint: its **value** is an `Optional[str]`. + +# Attributes +The following fields are extracted for Barcode Reader V1: + +## Barcodes 1D +**codes_1d** : List of decoded 1D barcodes. + +```py +for codes_1d_elem in result.document.inference.prediction.codes_1d: + print(codes_1d_elem.value) +``` + +## Barcodes 2D +**codes_2d** : List of decoded 2D barcodes. + +```py +for codes_2d_elem in result.document.inference.prediction.codes_2d: + print(codes_2d_elem.value) +``` + +# Questions? +[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw) diff --git a/docs/extras/guide/carte_vitale_v1.md b/docs/extras/guide/carte_vitale_v1.md new file mode 100644 index 00000000..5d6f7498 --- /dev/null +++ b/docs/extras/guide/carte_vitale_v1.md @@ -0,0 +1,123 @@ +--- +title: FR Carte Vitale OCR Python +--- +The Python 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 +```py +from mindee import Client, PredictResponse, product + +# Init a new client +mindee_client = Client(api_key="my-api-key") + +# Load a file from disk +input_doc = mindee_client.source_from_path("/path/to/the/file.ext") + +# Load a file from disk and parse it. +# The endpoint name must be specified since it cannot be determined from the class. +result: PredictResponse = mindee_client.parse(product.fr.CarteVitaleV1, input_doc) + +# Print a brief summary of the parsed data +print(result.document) + +# # Iterate over all the fields in the document +# for field_name, field_values in result.document.inference.prediction.fields.items(): +# print(field_name, "=", field_values) +``` + +**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 `BaseField` class. +A typical `BaseField` object will have the following attributes: + +* **value** (`Union[float, str]`): corresponds to the field value. Can be `None` if no value was extracted. +* **confidence** (`float`): the confidence score of the field prediction. +* **bounding_box** (`[Point, Point, Point, Point]`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document. +* **polygon** (`List[Point]`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image. +* **page_id** (`int`): the ID of the page, is `None` when at document-level. +* **reconstructed** (`bool`): indicates whether or not an object was reconstructed (not extracted as the API gave it). + +> **Note:** A `Point` simply refers to a List of two numbers (`[float, float]`). + + +Aside from the previous attributes, all basic fields have access to a custom `__str__` method that can be used to print their value as a string. + +### Date Field +Aside from the basic `BaseField` attributes, the date field `DateField` also implements the following: + +* **date_object** (`Date`): an accessible representation of the value as a python object. Can be `None`. + +### String Field +The text field `StringField` only has one constraint: its **value** is an `Optional[str]`. + +# Attributes +The following fields are extracted for Carte Vitale V1: + +## Given Name(s) +**given_names** : The given name(s) of the card holder. + +```py +for given_names_elem in result.document.inference.prediction.given_names: + print(given_names_elem.value) +``` + +## Issuance Date +**issuance_date** : The date the card was issued. + +```py +print(result.document.inference.prediction.issuance_date.value) +``` + +## Social Security Number +**social_security** : The Social Security Number (Numรฉro de Sรฉcuritรฉ Sociale) of the card holder + +```py +print(result.document.inference.prediction.social_security.value) +``` + +## Surname +**surname** : The surname of the card holder. + +```py +print(result.document.inference.prediction.surname.value) +``` + +# Questions? +[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw) diff --git a/docs/extras/guide/cropper_v1.md b/docs/extras/guide/cropper_v1.md new file mode 100644 index 00000000..cb428e36 --- /dev/null +++ b/docs/extras/guide/cropper_v1.md @@ -0,0 +1,99 @@ +--- +title: Cropper OCR Python +--- +The Python 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 +```py +from mindee import Client, PredictResponse, product + +# Init a new client +mindee_client = Client(api_key="my-api-key") + +# Load a file from disk +input_doc = mindee_client.source_from_path("/path/to/the/file.ext") + +# Load a file from disk and parse it. +# The endpoint name must be specified since it cannot be determined from the class. +result: PredictResponse = mindee_client.parse(product.CropperV1, input_doc) + +# Print a brief summary of the parsed data +print(result.document) + +# # Iterate over all the fields in the document +# for field_name, field_values in result.document.inference.prediction.fields.items(): +# print(field_name, "=", field_values) +``` + +**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 `BaseField` class. +A typical `BaseField` object will have the following attributes: + +* **value** (`Union[float, str]`): corresponds to the field value. Can be `None` if no value was extracted. +* **confidence** (`float`): the confidence score of the field prediction. +* **bounding_box** (`[Point, Point, Point, Point]`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document. +* **polygon** (`List[Point]`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image. +* **page_id** (`int`): the ID of the page, is `None` when at document-level. +* **reconstructed** (`bool`): indicates whether or not an object was reconstructed (not extracted as the API gave it). + +> **Note:** A `Point` simply refers to a List of two numbers (`[float, float]`). + + +Aside from the previous attributes, all basic fields have access to a custom `__str__` method that can be used to print their value as a string. + + +### Position Field +The position field `PositionField` does not implement all the basic `BaseField` attributes, only **bounding_box**, **polygon** and **page_id**. On top of these, it has access to: + +* **rectangle** (`[Point, Point, Point, Point]`): a Polygon with four points that may be oriented (even beyond canvas). +* **quadrangle** (`[Point, Point, Point, Point]`): 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** : List of documents found in the image. + +```py +for page in result.document.inference.pages: + for cropping_elem of page.prediction.cropping): + print(cropping_elem.polygon) +``` + +# Questions? +[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw) diff --git a/docs/extras/guide/expense_receipts_v5.md b/docs/extras/guide/expense_receipts_v5.md new file mode 100644 index 00000000..f9a15573 --- /dev/null +++ b/docs/extras/guide/expense_receipts_v5.md @@ -0,0 +1,304 @@ +--- +title: Receipt OCR Python +--- +The Python OCR SDK supports the [Receipt API](https://platform.mindee.com/mindee/expense_receipts). + +Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/expense_receipts/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK. +![Receipt sample](https://github.com/mindee/client-lib-test-data/blob/main/products/expense_receipts/default_sample.jpg?raw=true) + +# Quick-Start +```py +from mindee import Client, PredictResponse, product + +# Init a new client +mindee_client = Client(api_key="my-api-key") + +# Load a file from disk +input_doc = mindee_client.source_from_path("/path/to/the/file.ext") + +# Load a file from disk and parse it. +# The endpoint name must be specified since it cannot be determined from the class. +result: PredictResponse = mindee_client.parse(product.ReceiptV5, input_doc) + +# Print a brief summary of the parsed data +print(result.document) + +# # Iterate over all the fields in the document +# for field_name, field_values in result.document.inference.prediction.fields.items(): +# print(field_name, "=", field_values) +``` + +**Output (RST):** +```rst +######## +Document +######## +:Mindee ID: ce41e37a-65d8-4de1-b34b-1c92ab04b1ae +:Filename: default_sample.jpg + +Inference +######### +:Product: mindee/expense_receipts v5.0 +:Rotation applied: Yes + +Prediction +========== +:Expense Locale: en-GB; en; GB; GBP; +:Purchase Category: food +:Purchase Subcategory: restaurant +:Document Type: EXPENSE RECEIPT +:Purchase Date: 2016-02-26 +:Purchase Time: 15:20 +:Total Amount: 10.20 +:Total Net: 8.50 +:Total Tax: 1.70 +:Tip and Gratuity: +:Taxes: + +---------------+--------+----------+---------------+ + | Base | Code | Rate (%) | Amount | + +===============+========+==========+===============+ + | 8.50 | VAT | 20.00 | 1.70 | + +---------------+--------+----------+---------------+ +:Supplier Name: CLACHAN +:Supplier Company Registrations: 232153895 + 232153895 +:Supplier Address: 34 kingley street w1b 5qh +:Supplier Phone Number: 02074940834 +:Line Items: + +--------------------------------------+----------+--------------+------------+ + | Description | Quantity | Total Amount | Unit Price | + +======================================+==========+==============+============+ + | Meantime Pale | 2.00 | 10.20 | | + +--------------------------------------+----------+--------------+------------+ + +Page Predictions +================ + +Page 0 +------ +:Expense Locale: en-GB; en; GB; GBP; +:Purchase Category: food +:Purchase Subcategory: restaurant +:Document Type: EXPENSE RECEIPT +:Purchase Date: 2016-02-26 +:Purchase Time: 15:20 +:Total Amount: 10.20 +:Total Net: 8.50 +:Total Tax: 1.70 +:Tip and Gratuity: +:Taxes: + +---------------+--------+----------+---------------+ + | Base | Code | Rate (%) | Amount | + +===============+========+==========+===============+ + | 8.50 | VAT | 20.00 | 1.70 | + +---------------+--------+----------+---------------+ +:Supplier Name: CLACHAN +:Supplier Company Registrations: 232153895 + 232153895 +:Supplier Address: 34 kingley street w1b 5qh +:Supplier Phone Number: 02074940834 +:Line Items: + +--------------------------------------+----------+--------------+------------+ + | Description | Quantity | Total Amount | Unit Price | + +======================================+==========+==============+============+ + | Meantime Pale | 2.00 | 10.20 | | + +--------------------------------------+----------+--------------+------------+ +``` + +# 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 `BaseField` class. +A typical `BaseField` object will have the following attributes: + +* **value** (`Union[float, str]`): corresponds to the field value. Can be `None` if no value was extracted. +* **confidence** (`float`): the confidence score of the field prediction. +* **bounding_box** (`[Point, Point, Point, Point]`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document. +* **polygon** (`List[Point]`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image. +* **page_id** (`int`): the ID of the page, is `None` when at document-level. +* **reconstructed** (`bool`): indicates whether or not an object was reconstructed (not extracted as the API gave it). + +> **Note:** A `Point` simply refers to a List of two numbers (`[float, float]`). + + +Aside from the previous attributes, all basic fields have access to a custom `__str__` 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 an `Optional[float]`. + + +### Classification Field +The classification field `ClassificationField` does not implement all the basic `BaseField` attributes. It only implements **value**, **confidence** and **page_id**. + +> Note: a classification field's `value is always a `str`. + + +### Company Registration Field +Aside from the basic `BaseField` attributes, the company registration field `CompanyRegistrationField` also implements the following: + +* **type** (`str`): the type of company. + +### Date Field +Aside from the basic `BaseField` attributes, the date field `DateField` also implements the following: + +* **date_object** (`Date`): an accessible representation of the value as a python object. Can be `None`. + +### Locale Field +The locale field `LocaleField` only implements the **value**, **confidence** and **page_id** base `BaseField` attributes, but it comes with its own: + +* **language** (`str`): ISO 639-1 language code (e.g.: `en` for English). Can be `None`. +* **country** (`str`): ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code for countries (e.g.: `GRB` or `GB` for "Great Britain"). Can be `None`. +* **currency** (`str`): ISO 4217 code for currencies (e.g.: `USD` for "US Dollars"). Can be `None`. + +### String Field +The text field `StringField` only has one constraint: its **value** is an `Optional[str]`. + +### Taxes Field +#### Tax +Aside from the basic `BaseField` attributes, the tax field `TaxField` also implements the following: + +* **rate** (`float`): the tax rate applied to an item expressed as a percentage. Can be `None`. +* **code** (`str`): tax code (or equivalent, depending on the origin of the document). Can be `None`. +* **base** (`float`): base amount used for the tax. Can be `None`. + +> Note: currently `TaxField` is not used on its own, and is accessed through a parent `Taxes` object, a list-like structure. + +#### Taxes (Array) +The `Taxes` field represents a list-like collection of `TaxField` objects. As it is the representation of several objects, it has access to a custom `__str__` method that can render a `TaxField` object as a table line. + +## Specific Fields +Fields which are specific to this product; they are not used in any other product. + +### Line Items Field +List of line item details. + +A `ReceiptV5LineItem` implements the following attributes: + +* **description** (`str`): The item description. +* **quantity** (`float`): The item quantity. +* **total_amount** (`float`): The item total amount. +* **unit_price** (`float`): The item unit price. + +# Attributes +The following fields are extracted for Receipt V5: + +## Purchase Category +**category** : The purchase category among predefined classes. + +```py +print(result.document.inference.prediction.category.value) +``` + +## Purchase Date +**date** : The date the purchase was made. + +```py +print(result.document.inference.prediction.date.value) +``` + +## Document Type +**document_type** : One of: 'CREDIT CARD RECEIPT', 'EXPENSE RECEIPT'. + +```py +print(result.document.inference.prediction.document_type.value) +``` + +## Line Items +**line_items** ([ReceiptV5LineItem]List[(#line-items-field)]): List of line item details. + +```py +for line_items_elem in result.document.inference.prediction.line_items: + print(line_items_elem.value) +``` + +## Expense Locale +**locale** : The locale detected on the document. + +```py +print(result.document.inference.prediction.locale.value) +``` + +## Purchase Subcategory +**subcategory** : The purchase subcategory among predefined classes for transport and food. + +```py +print(result.document.inference.prediction.subcategory.value) +``` + +## Supplier Address +**supplier_address** : The address of the supplier or merchant. + +```py +print(result.document.inference.prediction.supplier_address.value) +``` + +## Supplier Company Registrations +**supplier_company_registrations** : List of company registrations associated to the supplier. + +```py +for supplier_company_registrations_elem in result.document.inference.prediction.supplier_company_registrations: + print(supplier_company_registrations_elem.value) +``` + +## Supplier Name +**supplier_name** : The name of the supplier or merchant. + +```py +print(result.document.inference.prediction.supplier_name.value) +``` + +## Supplier Phone Number +**supplier_phone_number** : The phone number of the supplier or merchant. + +```py +print(result.document.inference.prediction.supplier_phone_number.value) +``` + +## Taxes +**taxes** : List of tax lines information. + +```py +for taxes_elem in result.document.inference.prediction.taxes: + print(taxes_elem.polygon) +``` + +## Purchase Time +**time** : The time the purchase was made. + +```py +print(result.document.inference.prediction.time.value) +``` + +## Tip and Gratuity +**tip** : The total amount of tip and gratuity. + +```py +print(result.document.inference.prediction.tip.value) +``` + +## Total Amount +**total_amount** : The total amount paid: includes taxes, discounts, fees, tips, and gratuity. + +```py +print(result.document.inference.prediction.total_amount.value) +``` + +## Total Net +**total_net** : The net amount paid: does not include taxes, fees, and discounts. + +```py +print(result.document.inference.prediction.total_net.value) +``` + +## Total Tax +**total_tax** : The total amount of taxes. + +```py +print(result.document.inference.prediction.total_tax.value) +``` + +# Questions? +[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw) diff --git a/docs/extras/guide/financial_document_v1.md b/docs/extras/guide/financial_document_v1.md new file mode 100644 index 00000000..a874e1cc --- /dev/null +++ b/docs/extras/guide/financial_document_v1.md @@ -0,0 +1,379 @@ +--- +title: Financial Document OCR Python +--- +The Python OCR SDK supports the [Financial Document API](https://platform.mindee.com/mindee/financial_document). + +Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/financial_document/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK. +![Financial Document sample](https://github.com/mindee/client-lib-test-data/blob/main/products/financial_document/default_sample.jpg?raw=true) + +# Quick-Start +```py +from mindee import Client, PredictResponse, product + +# Init a new client +mindee_client = Client(api_key="my-api-key") + +# Load a file from disk +input_doc = mindee_client.source_from_path("/path/to/the/file.ext") + +# Load a file from disk and parse it. +# The endpoint name must be specified since it cannot be determined from the class. +result: PredictResponse = mindee_client.parse(product.FinancialDocumentV1, input_doc) + +# Print a brief summary of the parsed data +print(result.document) + +# # Iterate over all the fields in the document +# for field_name, field_values in result.document.inference.prediction.fields.items(): +# print(field_name, "=", field_values) +``` + +**Output (RST):** +```rst +######## +Document +######## +:Mindee ID: 81c1d637-3a84-41d9-b40a-f72ca2a58826 +:Filename: default_sample.jpg + +Inference +######### +:Product: mindee/financial_document v1.1 +: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 +:Taxes: + +---------------+--------+----------+---------------+ + | Base | Code | Rate (%) | Amount | + +===============+========+==========+===============+ + | | TAX | | 3.34 | + +---------------+--------+----------+---------------+ +:Supplier Payment Details: +:Supplier Name: LOGANS +:Supplier Company Registrations: +:Supplier Address: 2513 s stemmons freeway lewisville tx 75067 +:Supplier Phone Number: 9724596042 +:Customer Name: +: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 +:Line Items: + +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+ + | Description | Product Code | Quantity | Tax Amount | Tax Rate (%) | Total Amount | Unit Price | + +======================================+==============+==========+============+==============+==============+============+ + | TAX | | | | | 3.34 | | + +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+ + +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 +:Taxes: + +---------------+--------+----------+---------------+ + | Base | Code | Rate (%) | Amount | + +===============+========+==========+===============+ + | | TAX | | 3.34 | + +---------------+--------+----------+---------------+ +:Supplier Payment Details: +:Supplier Name: LOGANS +:Supplier Company Registrations: +:Supplier Address: 2513 s stemmons freeway lewisville tx 75067 +:Supplier Phone Number: 9724596042 +:Customer Name: +: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 +:Line Items: + +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+ + | Description | Product Code | Quantity | Tax Amount | Tax Rate (%) | Total Amount | Unit Price | + +======================================+==============+==========+============+==============+==============+============+ + | TAX | | | | | 3.34 | | + +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+ +``` + +# 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 `BaseField` class. +A typical `BaseField` object will have the following attributes: + +* **value** (`Union[float, str]`): corresponds to the field value. Can be `None` if no value was extracted. +* **confidence** (`float`): the confidence score of the field prediction. +* **bounding_box** (`[Point, Point, Point, Point]`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document. +* **polygon** (`List[Point]`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image. +* **page_id** (`int`): the ID of the page, is `None` when at document-level. +* **reconstructed** (`bool`): indicates whether or not an object was reconstructed (not extracted as the API gave it). + +> **Note:** A `Point` simply refers to a List of two numbers (`[float, float]`). + + +Aside from the previous attributes, all basic fields have access to a custom `__str__` 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 an `Optional[float]`. + + +### Classification Field +The classification field `ClassificationField` does not implement all the basic `BaseField` attributes. It only implements **value**, **confidence** and **page_id**. + +> Note: a classification field's `value is always a `str`. + + +### Company Registration Field +Aside from the basic `BaseField` attributes, the company registration field `CompanyRegistrationField` also implements the following: + +* **type** (`str`): the type of company. + +### Date Field +Aside from the basic `BaseField` attributes, the date field `DateField` also implements the following: + +* **date_object** (`Date`): an accessible representation of the value as a python object. Can be `None`. + +### Locale Field +The locale field `LocaleField` only implements the **value**, **confidence** and **page_id** base `BaseField` attributes, but it comes with its own: + +* **language** (`str`): ISO 639-1 language code (e.g.: `en` for English). Can be `None`. +* **country** (`str`): ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code for countries (e.g.: `GRB` or `GB` for "Great Britain"). Can be `None`. +* **currency** (`str`): ISO 4217 code for currencies (e.g.: `USD` for "US Dollars"). Can be `None`. + +### Payment Details Field +Aside from the basic `BaseField` attributes, the payment details field `PaymentDetailsField` also implements the following: + +* **account_number** (`str`): number of an account, expressed as a string. Can be `None`. +* **iban** (`str`): International Bank Account Number. Can be `None`. +* **routing_number** (`str`): routing number of an account. Can be `None`. +* **swift** (`str`): the account holder's bank's SWIFT Business Identifier Code (BIC). Can be `None`. + +### String Field +The text field `StringField` only has one constraint: its **value** is an `Optional[str]`. + +### Taxes Field +#### Tax +Aside from the basic `BaseField` attributes, the tax field `TaxField` also implements the following: + +* **rate** (`float`): the tax rate applied to an item expressed as a percentage. Can be `None`. +* **code** (`str`): tax code (or equivalent, depending on the origin of the document). Can be `None`. +* **base** (`float`): base amount used for the tax. Can be `None`. + +> Note: currently `TaxField` is not used on its own, and is accessed through a parent `Taxes` object, a list-like structure. + +#### Taxes (Array) +The `Taxes` field represents a list-like collection of `TaxField` objects. As it is the representation of several objects, it has access to a custom `__str__` method that can render a `TaxField` object as a table line. + +## Specific Fields +Fields which are specific to this product; they are not used in any other product. + +### Line Items Field +List of line item details. + +A `FinancialDocumentV1LineItem` implements the following attributes: + +* **description** (`str`): The item description. +* **product_code** (`str`): The product code referring to the item. +* **quantity** (`float`): The item quantity +* **tax_amount** (`float`): The item tax amount. +* **tax_rate** (`float`): The item tax rate in percentage. +* **total_amount** (`float`): The item total amount. +* **unit_price** (`float`): The item unit price. + +# Attributes +The following fields are extracted for Financial Document V1: + +## Purchase Category +**category** : The purchase category among predefined classes. + +```py +print(result.document.inference.prediction.category.value) +``` + +## Customer Address +**customer_address** : The address of the customer. + +```py +print(result.document.inference.prediction.customer_address.value) +``` + +## Customer Company Registrations +**customer_company_registrations** : List of company registrations associated to the customer. + +```py +for customer_company_registrations_elem in result.document.inference.prediction.customer_company_registrations: + print(customer_company_registrations_elem.value) +``` + +## Customer Name +**customer_name** : The name of the customer. + +```py +print(result.document.inference.prediction.customer_name.value) +``` + +## Purchase Date +**date** : The date the purchase was made. + +```py +print(result.document.inference.prediction.date.value) +``` + +## Document Type +**document_type** : One of: 'INVOICE', 'CREDIT NOTE', 'CREDIT CARD RECEIPT', 'EXPENSE RECEIPT'. + +```py +print(result.document.inference.prediction.document_type.value) +``` + +## Due Date +**due_date** : The date on which the payment is due. + +```py +print(result.document.inference.prediction.due_date.value) +``` + +## Invoice Number +**invoice_number** : The invoice number or identifier. + +```py +print(result.document.inference.prediction.invoice_number.value) +``` + +## Line Items +**line_items** ([FinancialDocumentV1LineItem]List[(#line-items-field)]): List of line item details. + +```py +for line_items_elem in result.document.inference.prediction.line_items: + print(line_items_elem.value) +``` + +## Locale +**locale** : The locale detected on the document. + +```py +print(result.document.inference.prediction.locale.value) +``` + +## Reference Numbers +**reference_numbers** : List of Reference numbers, including PO number. + +```py +for reference_numbers_elem in result.document.inference.prediction.reference_numbers: + print(reference_numbers_elem.value) +``` + +## Purchase Subcategory +**subcategory** : The purchase subcategory among predefined classes for transport and food. + +```py +print(result.document.inference.prediction.subcategory.value) +``` + +## Supplier Address +**supplier_address** : The address of the supplier or merchant. + +```py +print(result.document.inference.prediction.supplier_address.value) +``` + +## Supplier Company Registrations +**supplier_company_registrations** : List of company registrations associated to the supplier. + +```py +for supplier_company_registrations_elem in result.document.inference.prediction.supplier_company_registrations: + print(supplier_company_registrations_elem.value) +``` + +## Supplier Name +**supplier_name** : The name of the supplier or merchant. + +```py +print(result.document.inference.prediction.supplier_name.value) +``` + +## Supplier Payment Details +**supplier_payment_details** : List of payment details associated to the supplier. + +```py +for supplier_payment_details_elem in result.document.inference.prediction.supplier_payment_details: + print(supplier_payment_details_elem.value) +``` + +## Supplier Phone Number +**supplier_phone_number** : The phone number of the supplier or merchant. + +```py +print(result.document.inference.prediction.supplier_phone_number.value) +``` + +## Taxes +**taxes** : List of tax lines information. + +```py +for taxes_elem in result.document.inference.prediction.taxes: + print(taxes_elem.polygon) +``` + +## Purchase Time +**time** : The time the purchase was made. + +```py +print(result.document.inference.prediction.time.value) +``` + +## Tip and Gratuity +**tip** : The total amount of tip and gratuity + +```py +print(result.document.inference.prediction.tip.value) +``` + +## Total Amount +**total_amount** : The total amount paid: includes taxes, tips, fees, and other charges. + +```py +print(result.document.inference.prediction.total_amount.value) +``` + +## Total Net +**total_net** : The net amount paid: does not include taxes, fees, and discounts. + +```py +print(result.document.inference.prediction.total_net.value) +``` + +## Total Tax +**total_tax** : The total amount of taxes. + +```py +print(result.document.inference.prediction.total_tax.value) +``` + +# Questions? +[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw) diff --git a/docs/extras/guide/idcard_fr_v2.md b/docs/extras/guide/idcard_fr_v2.md new file mode 100644 index 00000000..bc6d1e3d --- /dev/null +++ b/docs/extras/guide/idcard_fr_v2.md @@ -0,0 +1,251 @@ +--- +title: FR Carte Nationale d'Identitรฉ OCR Python +--- +The Python OCR SDK supports the [Carte Nationale d'Identitรฉ API](https://platform.mindee.com/mindee/idcard_fr). + +Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/idcard_fr/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK. +![Carte Nationale d'Identitรฉ sample](https://github.com/mindee/client-lib-test-data/blob/main/products/idcard_fr/default_sample.jpg?raw=true) + +# Quick-Start +```py +from mindee import Client, PredictResponse, product + +# Init a new client +mindee_client = Client(api_key="my-api-key") + +# Load a file from disk +input_doc = mindee_client.source_from_path("/path/to/the/file.ext") + +# Load a file from disk and parse it. +# The endpoint name must be specified since it cannot be determined from the class. +result: PredictResponse = mindee_client.parse(product.fr.IdCardV2, input_doc) + +# Print a brief summary of the parsed data +print(result.document) + +# # Iterate over all the fields in the document +# for field_name, field_values in result.document.inference.prediction.fields.items(): +# print(field_name, "=", field_values) +``` + +**Output (RST):** +```rst +######## +Document +######## +:Mindee ID: d33828f1-ef7e-4984-b9df-a2bfaa38a78d +:Filename: default_sample.jpg + +Inference +######### +:Product: mindee/idcard_fr v2.0 +:Rotation applied: Yes + +Prediction +========== +:Nationality: +:Card Access Number: 175775H55790 +:Document Number: +:Given Name(s): Victor + Marie +:Surname: DAMBARD +:Alternate Name: +:Date of Birth: 1994-04-24 +:Place of Birth: LYON 4E ARRONDISSEM +:Gender: M +:Expiry Date: 2030-04-02 +:Mrz Line 1: IDFRADAMBARD<<<<<<<<<<<<<<<<<<075025 +:Mrz Line 2: 170775H557903VICTOR< **Note:** A `Point` simply refers to a List of two numbers (`[float, float]`). + + +Aside from the previous attributes, all basic fields have access to a custom `__str__` method that can be used to print their value as a string. + + +### Classification Field +The classification field `ClassificationField` does not implement all the basic `BaseField` attributes. It only implements **value**, **confidence** and **page_id**. + +> Note: a classification field's `value is always a `str`. + +### Date Field +Aside from the basic `BaseField` attributes, the date field `DateField` also implements the following: + +* **date_object** (`Date`): an accessible representation of the value as a python object. Can be `None`. + +### String Field +The text field `StringField` only has one constraint: its **value** is an `Optional[str]`. + +## 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 Carte Nationale d'Identitรฉ V2: + +## Alternate Name +**alternate_name** : The alternate name of the card holder. + +```py +print(result.document.inference.prediction.alternate_name.value) +``` + +## Issuing Authority +**authority** : The name of the issuing authority. + +```py +print(result.document.inference.prediction.authority.value) +``` + +## Date of Birth +**birth_date** : The date of birth of the card holder. + +```py +print(result.document.inference.prediction.birth_date.value) +``` + +## Place of Birth +**birth_place** : The place of birth of the card holder. + +```py +print(result.document.inference.prediction.birth_place.value) +``` + +## Card Access Number +**card_access_number** : The card access number (CAN). + +```py +print(result.document.inference.prediction.card_access_number.value) +``` + +## Document Number +**document_number** : The document number. + +```py +print(result.document.inference.prediction.document_number.value) +``` + +## Document Sides +[๐Ÿ“„](#page-level-fields "This field is only present on individual pages.")**document_side** : The sides of the document which are visible. + +```py +for document_side_elem of result.document.document_side: + print(document_side_elem.value) +``` + +## Document Type +[๐Ÿ“„](#page-level-fields "This field is only present on individual pages.")**document_type** : The document type or format. + +```py +for document_type_elem of result.document.document_type: + print(document_type_elem.value) +``` + +## Expiry Date +**expiry_date** : The expiry date of the identification card. + +```py +print(result.document.inference.prediction.expiry_date.value) +``` + +## Gender +**gender** : The gender of the card holder. + +```py +print(result.document.inference.prediction.gender.value) +``` + +## Given Name(s) +**given_names** : The given name(s) of the card holder. + +```py +for given_names_elem in result.document.inference.prediction.given_names: + print(given_names_elem.value) +``` + +## Date of Issue +**issue_date** : The date of issue of the identification card. + +```py +print(result.document.inference.prediction.issue_date.value) +``` + +## Mrz Line 1 +**mrz1** : The Machine Readable Zone, first line. + +```py +print(result.document.inference.prediction.mrz1.value) +``` + +## Mrz Line 2 +**mrz2** : The Machine Readable Zone, second line. + +```py +print(result.document.inference.prediction.mrz2.value) +``` + +## Mrz Line 3 +**mrz3** : The Machine Readable Zone, third line. + +```py +print(result.document.inference.prediction.mrz3.value) +``` + +## Nationality +**nationality** : The nationality of the card holder. + +```py +print(result.document.inference.prediction.nationality.value) +``` + +## Surname +**surname** : The surname of the card holder. + +```py +print(result.document.inference.prediction.surname.value) +``` + +# Questions? +[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw) diff --git a/docs/extras/guide/invoices_v4.md b/docs/extras/guide/invoices_v4.md new file mode 100644 index 00000000..da4703b4 --- /dev/null +++ b/docs/extras/guide/invoices_v4.md @@ -0,0 +1,335 @@ +--- +title: Invoice OCR Python +--- +The Python OCR SDK supports the [Invoice API](https://platform.mindee.com/mindee/invoices). + +Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/invoices/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK. +![Invoice sample](https://github.com/mindee/client-lib-test-data/blob/main/products/invoices/default_sample.jpg?raw=true) + +# Quick-Start +```py +from mindee import Client, PredictResponse, product + +# Init a new client +mindee_client = Client(api_key="my-api-key") + +# Load a file from disk +input_doc = mindee_client.source_from_path("/path/to/the/file.ext") + +# Load a file from disk and parse it. +# The endpoint name must be specified since it cannot be determined from the class. +result: PredictResponse = mindee_client.parse(product.InvoiceV4, input_doc) + +# Print a brief summary of the parsed data +print(result.document) + +# # Iterate over all the fields in the document +# for field_name, field_values in result.document.inference.prediction.fields.items(): +# print(field_name, "=", field_values) +``` + +**Output (RST):** +```rst +######## +Document +######## +:Mindee ID: a8718ec1-aaa9-410d-b2fc-15ab1d092c9a +:Filename: default_sample.jpg + +Inference +######### +:Product: mindee/invoices v4.2 +:Rotation applied: Yes + +Prediction +========== +:Locale: en; en; CAD; +:Document Type: INVOICE +:Invoice Number: 14 +:Reference Numbers: AD29094 +:Invoice Date: 2018-09-25 +:Invoice Due Date: 2018-09-25 +:Supplier Name: TURNPIKE DESIGNS CO. +:Supplier Address: 156 University Ave, Toronto ON, Canada M5H 2H7 +:Supplier Company Registrations: +:Supplier Payment Details: +:Customer Name: JIRO DOI +:Customer Address: 1954 Bloor Street West Toronto, ON, M6P 3K9 Canada +:Customer Company Registrations: +:Taxes: + +---------------+--------+----------+---------------+ + | Base | Code | Rate (%) | Amount | + +===============+========+==========+===============+ + | | | 8.00 | 193.20 | + +---------------+--------+----------+---------------+ +:Total Net: +:Total Tax: 193.20 +:Total Amount: 2608.20 +:Line Items: + +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+ + | Description | Product Code | Quantity | Tax Amount | Tax Rate (%) | Total Amount | Unit Price | + +======================================+==============+==========+============+==============+==============+============+ + | Platinum web hosting package Down... | | 1.00 | | | 65.00 | 65.00 | + +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+ + | 2 page website design Includes ba... | | 3.00 | | | 2100.00 | 2100.00 | + +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+ + | Mobile designs Includes responsiv... | | 1.00 | | | 250.00 | 250.00 | + +--------------------------------------+--------------+----------+---------------------------+--------------+------------+ + +Page Predictions +================ + +Page 0 +------ +:Locale: en; en; CAD; +:Document Type: INVOICE +:Invoice Number: 14 +:Reference Numbers: AD29094 +:Invoice Date: 2018-09-25 +:Invoice Due Date: 2018-09-25 +:Supplier Name: TURNPIKE DESIGNS CO. +:Supplier Address: 156 University Ave, Toronto ON, Canada M5H 2H7 +:Supplier Company Registrations: +:Supplier Payment Details: +:Customer Name: JIRO DOI +:Customer Address: 1954 Bloor Street West Toronto, ON, M6P 3K9 Canada +:Customer Company Registrations: +:Taxes: + +---------------+--------+----------+---------------+ + | Base | Code | Rate (%) | Amount | + +===============+========+==========+===============+ + | | | 8.00 | 193.20 | + +---------------+--------+----------+---------------+ +:Total Net: +:Total Tax: 193.20 +:Total Amount: 2608.20 +:Line Items: + +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+ + | Description | Product Code | Quantity | Tax Amount | Tax Rate (%) | Total Amount | Unit Price | + +======================================+==============+==========+============+==============+==============+============+ + | Platinum web hosting package Down... | | 1.00 | | | 65.00 | 65.00 | + +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+ + | 2 page website design Includes ba... | | 3.00 | | | 2100.00 | 2100.00 | + +--------------------------------------+--------------+----------+------------+--------------+--------------+------------+ + | Mobile designs Includes responsiv... | | 1.00 | | | 250.00 | 250.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 `BaseField` class. +A typical `BaseField` object will have the following attributes: + +* **value** (`Union[float, str]`): corresponds to the field value. Can be `None` if no value was extracted. +* **confidence** (`float`): the confidence score of the field prediction. +* **bounding_box** (`[Point, Point, Point, Point]`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document. +* **polygon** (`List[Point]`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image. +* **page_id** (`int`): the ID of the page, is `None` when at document-level. +* **reconstructed** (`bool`): indicates whether or not an object was reconstructed (not extracted as the API gave it). + +> **Note:** A `Point` simply refers to a List of two numbers (`[float, float]`). + + +Aside from the previous attributes, all basic fields have access to a custom `__str__` 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 an `Optional[float]`. + + +### Classification Field +The classification field `ClassificationField` does not implement all the basic `BaseField` attributes. It only implements **value**, **confidence** and **page_id**. + +> Note: a classification field's `value is always a `str`. + + +### Company Registration Field +Aside from the basic `BaseField` attributes, the company registration field `CompanyRegistrationField` also implements the following: + +* **type** (`str`): the type of company. + +### Date Field +Aside from the basic `BaseField` attributes, the date field `DateField` also implements the following: + +* **date_object** (`Date`): an accessible representation of the value as a python object. Can be `None`. + +### Locale Field +The locale field `LocaleField` only implements the **value**, **confidence** and **page_id** base `BaseField` attributes, but it comes with its own: + +* **language** (`str`): ISO 639-1 language code (e.g.: `en` for English). Can be `None`. +* **country** (`str`): ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code for countries (e.g.: `GRB` or `GB` for "Great Britain"). Can be `None`. +* **currency** (`str`): ISO 4217 code for currencies (e.g.: `USD` for "US Dollars"). Can be `None`. + +### Payment Details Field +Aside from the basic `BaseField` attributes, the payment details field `PaymentDetailsField` also implements the following: + +* **account_number** (`str`): number of an account, expressed as a string. Can be `None`. +* **iban** (`str`): International Bank Account Number. Can be `None`. +* **routing_number** (`str`): routing number of an account. Can be `None`. +* **swift** (`str`): the account holder's bank's SWIFT Business Identifier Code (BIC). Can be `None`. + +### String Field +The text field `StringField` only has one constraint: its **value** is an `Optional[str]`. + +### Taxes Field +#### Tax +Aside from the basic `BaseField` attributes, the tax field `TaxField` also implements the following: + +* **rate** (`float`): the tax rate applied to an item expressed as a percentage. Can be `None`. +* **code** (`str`): tax code (or equivalent, depending on the origin of the document). Can be `None`. +* **base** (`float`): base amount used for the tax. Can be `None`. + +> Note: currently `TaxField` is not used on its own, and is accessed through a parent `Taxes` object, a list-like structure. + +#### Taxes (Array) +The `Taxes` field represents a list-like collection of `TaxField` objects. As it is the representation of several objects, it has access to a custom `__str__` method that can render a `TaxField` object as a table line. + +## Specific Fields +Fields which are specific to this product; they are not used in any other product. + +### Line Items Field +List of line item details. + +A `InvoiceV4LineItem` implements the following attributes: + +* **description** (`str`): The item description. +* **product_code** (`str`): The product code referring to the item. +* **quantity** (`float`): The item quantity +* **tax_amount** (`float`): The item tax amount. +* **tax_rate** (`float`): The item tax rate in percentage. +* **total_amount** (`float`): The item total amount. +* **unit_price** (`float`): The item unit price. + +# Attributes +The following fields are extracted for Invoice V4: + +## Customer Address +**customer_address** : The address of the customer. + +```py +print(result.document.inference.prediction.customer_address.value) +``` + +## Customer Company Registrations +**customer_company_registrations** : List of company registrations associated to the customer. + +```py +for customer_company_registrations_elem in result.document.inference.prediction.customer_company_registrations: + print(customer_company_registrations_elem.value) +``` + +## Customer Name +**customer_name** : The name of the customer or client. + +```py +print(result.document.inference.prediction.customer_name.value) +``` + +## Purchase Date +**date** : The date the purchase was made. + +```py +print(result.document.inference.prediction.date.value) +``` + +## Document Type +**document_type** : One of: 'INVOICE', 'CREDIT NOTE'. + +```py +print(result.document.inference.prediction.document_type.value) +``` + +## Due Date +**due_date** : The date on which the payment is due. + +```py +print(result.document.inference.prediction.due_date.value) +``` + +## Invoice Number +**invoice_number** : The invoice number or identifier. + +```py +print(result.document.inference.prediction.invoice_number.value) +``` + +## Line Items +**line_items** ([InvoiceV4LineItem]List[(#line-items-field)]): List of line item details. + +```py +for line_items_elem in result.document.inference.prediction.line_items: + print(line_items_elem.value) +``` + +## Locale +**locale** : The locale detected on the document. + +```py +print(result.document.inference.prediction.locale.value) +``` + +## Reference Numbers +**reference_numbers** : List of Reference numbers, including PO number. + +```py +for reference_numbers_elem in result.document.inference.prediction.reference_numbers: + print(reference_numbers_elem.value) +``` + +## Supplier Address +**supplier_address** : The address of the supplier or merchant. + +```py +print(result.document.inference.prediction.supplier_address.value) +``` + +## Supplier Company Registrations +**supplier_company_registrations** : List of company registrations associated to the supplier. + +```py +for supplier_company_registrations_elem in result.document.inference.prediction.supplier_company_registrations: + print(supplier_company_registrations_elem.value) +``` + +## Supplier Name +**supplier_name** : The name of the supplier or merchant. + +```py +print(result.document.inference.prediction.supplier_name.value) +``` + +## Supplier Payment Details +**supplier_payment_details** : List of payment details associated to the supplier. + +```py +for supplier_payment_details_elem in result.document.inference.prediction.supplier_payment_details: + print(supplier_payment_details_elem.value) +``` + +## Taxes +**taxes** : List of tax line details. + +```py +for taxes_elem in result.document.inference.prediction.taxes: + print(taxes_elem.polygon) +``` + +## Total Amount +**total_amount** : The total amount paid: includes taxes, tips, fees, and other charges. + +```py +print(result.document.inference.prediction.total_amount.value) +``` + +## Total Net +**total_net** : The net amount paid: does not include taxes, fees, and discounts. + +```py +print(result.document.inference.prediction.total_net.value) +``` + +# Questions? +[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw) diff --git a/docs/extras/guide/license_plates_v1.md b/docs/extras/guide/license_plates_v1.md new file mode 100644 index 00000000..b32d512b --- /dev/null +++ b/docs/extras/guide/license_plates_v1.md @@ -0,0 +1,91 @@ +--- +title: EU License Plate OCR Python +--- +The Python OCR SDK supports the [License Plate API](https://platform.mindee.com/mindee/license_plates). + +Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/license_plates/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK. +![License Plate sample](https://github.com/mindee/client-lib-test-data/blob/main/products/license_plates/default_sample.jpg?raw=true) + +# Quick-Start +```py +from mindee import Client, PredictResponse, product + +# Init a new client +mindee_client = Client(api_key="my-api-key") + +# Load a file from disk +input_doc = mindee_client.source_from_path("/path/to/the/file.ext") + +# Load a file from disk and parse it. +# The endpoint name must be specified since it cannot be determined from the class. +result: PredictResponse = mindee_client.parse(product.eu.LicensePlateV1, input_doc) + +# Print a brief summary of the parsed data +print(result.document) + +# # Iterate over all the fields in the document +# for field_name, field_values in result.document.inference.prediction.fields.items(): +# print(field_name, "=", field_values) +``` + +**Output (RST):** +```rst +######## +Document +######## +:Mindee ID: f0f48232-2c80-4473-9c6f-88a09111b84d +:Filename: default_sample.jpg + +Inference +######### +:Product: mindee/license_plates v1.0 +:Rotation applied: No + +Prediction +========== +:License Plates: BY-323-YB + +Page Predictions +================ + +Page 0 +------ +:License Plates: BY-323-YB +``` + +# 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 `BaseField` class. +A typical `BaseField` object will have the following attributes: + +* **value** (`Union[float, str]`): corresponds to the field value. Can be `None` if no value was extracted. +* **confidence** (`float`): the confidence score of the field prediction. +* **bounding_box** (`[Point, Point, Point, Point]`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document. +* **polygon** (`List[Point]`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image. +* **page_id** (`int`): the ID of the page, is `None` when at document-level. +* **reconstructed** (`bool`): indicates whether or not an object was reconstructed (not extracted as the API gave it). + +> **Note:** A `Point` simply refers to a List of two numbers (`[float, float]`). + + +Aside from the previous attributes, all basic fields have access to a custom `__str__` method that can be used to print their value as a string. + +### String Field +The text field `StringField` only has one constraint: its **value** is an `Optional[str]`. + +# Attributes +The following fields are extracted for License Plate V1: + +## License Plates +**license_plates** : List of all license plates found in the image. + +```py +for license_plates_elem in result.document.inference.prediction.license_plates: + print(license_plates_elem.value) +``` + +# Questions? +[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw) diff --git a/docs/extras/guide/multi_receipts_detector_v1.md b/docs/extras/guide/multi_receipts_detector_v1.md new file mode 100644 index 00000000..bd3d71f0 --- /dev/null +++ b/docs/extras/guide/multi_receipts_detector_v1.md @@ -0,0 +1,105 @@ +--- +title: Multi Receipts Detector OCR Python +--- +The Python OCR SDK supports the [Multi Receipts Detector API](https://platform.mindee.com/mindee/multi_receipts_detector). + +Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/multi_receipts_detector/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK. +![Multi Receipts Detector sample](https://github.com/mindee/client-lib-test-data/blob/main/products/multi_receipts_detector/default_sample.jpg?raw=true) + +# Quick-Start +```py +from mindee import Client, PredictResponse, product + +# Init a new client +mindee_client = Client(api_key="my-api-key") + +# Load a file from disk +input_doc = mindee_client.source_from_path("/path/to/the/file.ext") + +# Load a file from disk and parse it. +# The endpoint name must be specified since it cannot be determined from the class. +result: PredictResponse = mindee_client.parse(product.MultiReceiptsDetectorV1, input_doc) + +# Print a brief summary of the parsed data +print(result.document) + +# # Iterate over all the fields in the document +# for field_name, field_values in result.document.inference.prediction.fields.items(): +# print(field_name, "=", field_values) +``` + +**Output (RST):** +```rst +######## +Document +######## +:Mindee ID: d7c5b25f-e0d3-4491-af54-6183afa1aaab +:Filename: default_sample.jpg + +Inference +######### +:Product: mindee/multi_receipts_detector v1.0 +:Rotation applied: Yes + +Prediction +========== +:List of Receipts: Polygon with 4 points. + Polygon with 4 points. + Polygon with 4 points. + Polygon with 4 points. + Polygon with 4 points. + Polygon with 4 points. + +Page Predictions +================ + +Page 0 +------ +:List of Receipts: Polygon with 4 points. + Polygon with 4 points. + Polygon with 4 points. + Polygon with 4 points. + Polygon with 4 points. + Polygon with 4 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 `BaseField` class. +A typical `BaseField` object will have the following attributes: + +* **value** (`Union[float, str]`): corresponds to the field value. Can be `None` if no value was extracted. +* **confidence** (`float`): the confidence score of the field prediction. +* **bounding_box** (`[Point, Point, Point, Point]`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document. +* **polygon** (`List[Point]`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image. +* **page_id** (`int`): the ID of the page, is `None` when at document-level. +* **reconstructed** (`bool`): indicates whether or not an object was reconstructed (not extracted as the API gave it). + +> **Note:** A `Point` simply refers to a List of two numbers (`[float, float]`). + + +Aside from the previous attributes, all basic fields have access to a custom `__str__` method that can be used to print their value as a string. + + +### Position Field +The position field `PositionField` does not implement all the basic `BaseField` attributes, only **bounding_box**, **polygon** and **page_id**. On top of these, it has access to: + +* **rectangle** (`[Point, Point, Point, Point]`): a Polygon with four points that may be oriented (even beyond canvas). +* **quadrangle** (`[Point, Point, Point, Point]`): a free polygon made up of four points. + +# Attributes +The following fields are extracted for Multi Receipts Detector V1: + +## List of Receipts +**receipts** : Positions of the receipts on the document. + +```py +for receipts_elem in result.document.inference.prediction.receipts: + print(receipts_elem.polygon) +``` + +# Questions? +[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw) diff --git a/docs/extras/guide/passport_v1.md b/docs/extras/guide/passport_v1.md new file mode 100644 index 00000000..cc8da11a --- /dev/null +++ b/docs/extras/guide/passport_v1.md @@ -0,0 +1,186 @@ +--- +title: Passport OCR Python +--- +The Python 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 +```py +from mindee import Client, PredictResponse, product + +# Init a new client +mindee_client = Client(api_key="my-api-key") + +# Load a file from disk +input_doc = mindee_client.source_from_path("/path/to/the/file.ext") + +# Load a file from disk and parse it. +# The endpoint name must be specified since it cannot be determined from the class. +result: PredictResponse = mindee_client.parse(product.PassportV1, input_doc) + +# Print a brief summary of the parsed data +print(result.document) + +# # Iterate over all the fields in the document +# for field_name, field_values in result.document.inference.prediction.fields.items(): +# print(field_name, "=", field_values) +``` + +**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 **Note:** A `Point` simply refers to a List of two numbers (`[float, float]`). + + +Aside from the previous attributes, all basic fields have access to a custom `__str__` method that can be used to print their value as a string. + +### Date Field +Aside from the basic `BaseField` attributes, the date field `DateField` also implements the following: + +* **date_object** (`Date`): an accessible representation of the value as a python object. Can be `None`. + +### String Field +The text field `StringField` only has one constraint: its **value** is an `Optional[str]`. + +# Attributes +The following fields are extracted for Passport V1: + +## Date of Birth +**birth_date** : The date of birth of the passport holder. + +```py +print(result.document.inference.prediction.birth_date.value) +``` + +## Place of Birth +**birth_place** : The place of birth of the passport holder. + +```py +print(result.document.inference.prediction.birth_place.value) +``` + +## Country Code +**country** : The country's 3 letter code (ISO 3166-1 alpha-3). + +```py +print(result.document.inference.prediction.country.value) +``` + +## Expiry Date +**expiry_date** : The expiry date of the passport. + +```py +print(result.document.inference.prediction.expiry_date.value) +``` + +## Gender +**gender** : The gender of the passport holder. + +```py +print(result.document.inference.prediction.gender.value) +``` + +## Given Name(s) +**given_names** : The given name(s) of the passport holder. + +```py +for given_names_elem in result.document.inference.prediction.given_names: + print(given_names_elem.value) +``` + +## ID Number +**id_number** : The passport's identification number. + +```py +print(result.document.inference.prediction.id_number.value) +``` + +## Date of Issue +**issuance_date** : The date the passport was issued. + +```py +print(result.document.inference.prediction.issuance_date.value) +``` + +## MRZ Line 1 +**mrz1** : Machine Readable Zone, first line + +```py +print(result.document.inference.prediction.mrz1.value) +``` + +## MRZ Line 2 +**mrz2** : Machine Readable Zone, second line + +```py +print(result.document.inference.prediction.mrz2.value) +``` + +## Surname +**surname** : The surname of the passport holder. + +```py +print(result.document.inference.prediction.surname.value) +``` + +# Questions? +[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw) diff --git a/docs/extras/guide/proof_of_address_v1.md b/docs/extras/guide/proof_of_address_v1.md new file mode 100644 index 00000000..94606e95 --- /dev/null +++ b/docs/extras/guide/proof_of_address_v1.md @@ -0,0 +1,205 @@ +--- +title: Proof of Address OCR Python +--- +The Python 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 +```py +from mindee import Client, PredictResponse, product + +# Init a new client +mindee_client = Client(api_key="my-api-key") + +# Load a file from disk +input_doc = mindee_client.source_from_path("/path/to/the/file.ext") + +# Load a file from disk and parse it. +# The endpoint name must be specified since it cannot be determined from the class. +result: PredictResponse = mindee_client.parse(product.ProofOfAddressV1, input_doc) + +# Print a brief summary of the parsed data +print(result.document) + +# # Iterate over all the fields in the document +# for field_name, field_values in result.document.inference.prediction.fields.items(): +# print(field_name, "=", field_values) +``` + +**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 `BaseField` class. +A typical `BaseField` object will have the following attributes: + +* **value** (`Union[float, str]`): corresponds to the field value. Can be `None` if no value was extracted. +* **confidence** (`float`): the confidence score of the field prediction. +* **bounding_box** (`[Point, Point, Point, Point]`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document. +* **polygon** (`List[Point]`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image. +* **page_id** (`int`): the ID of the page, is `None` when at document-level. +* **reconstructed** (`bool`): indicates whether or not an object was reconstructed (not extracted as the API gave it). + +> **Note:** A `Point` simply refers to a List of two numbers (`[float, float]`). + + +Aside from the previous attributes, all basic fields have access to a custom `__str__` method that can be used to print their value as a string. + + +### Company Registration Field +Aside from the basic `BaseField` attributes, the company registration field `CompanyRegistrationField` also implements the following: + +* **type** (`str`): the type of company. + +### Date Field +Aside from the basic `BaseField` attributes, the date field `DateField` also implements the following: + +* **date_object** (`Date`): an accessible representation of the value as a python object. Can be `None`. + +### Locale Field +The locale field `LocaleField` only implements the **value**, **confidence** and **page_id** base `BaseField` attributes, but it comes with its own: + +* **language** (`str`): ISO 639-1 language code (e.g.: `en` for English). Can be `None`. +* **country** (`str`): ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code for countries (e.g.: `GRB` or `GB` for "Great Britain"). Can be `None`. +* **currency** (`str`): ISO 4217 code for currencies (e.g.: `USD` for "US Dollars"). Can be `None`. + +### String Field +The text field `StringField` only has one constraint: its **value** is an `Optional[str]`. + +# Attributes +The following fields are extracted for Proof of Address V1: + +## Date of Issue +**date** : The date the document was issued. + +```py +print(result.document.inference.prediction.date.value) +``` + +## Dates +**dates** : List of dates found on the document. + +```py +for dates_elem in result.document.inference.prediction.dates: + print(dates_elem.value) +``` + +## Issuer Address +**issuer_address** : The address of the document's issuer. + +```py +print(result.document.inference.prediction.issuer_address.value) +``` + +## Issuer Company Registrations +**issuer_company_registration** : List of company registrations found for the issuer. + +```py +for issuer_company_registration_elem in result.document.inference.prediction.issuer_company_registration: + print(issuer_company_registration_elem.value) +``` + +## Issuer Name +**issuer_name** : The name of the person or company issuing the document. + +```py +print(result.document.inference.prediction.issuer_name.value) +``` + +## Locale +**locale** : The locale detected on the document. + +```py +print(result.document.inference.prediction.locale.value) +``` + +## Recipient Address +**recipient_address** : The address of the recipient. + +```py +print(result.document.inference.prediction.recipient_address.value) +``` + +## Recipient Company Registrations +**recipient_company_registration** : List of company registrations found for the recipient. + +```py +for recipient_company_registration_elem in result.document.inference.prediction.recipient_company_registration: + print(recipient_company_registration_elem.value) +``` + +## Recipient Name +**recipient_name** : The name of the person or company receiving the document. + +```py +print(result.document.inference.prediction.recipient_name.value) +``` + +# Questions? +[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw) diff --git a/docs/extras/guide/us_driver_license_v1.md b/docs/extras/guide/us_driver_license_v1.md new file mode 100644 index 00000000..f6373184 --- /dev/null +++ b/docs/extras/guide/us_driver_license_v1.md @@ -0,0 +1,267 @@ +--- +title: US Driver License OCR Python +--- +The Python 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 +```py +from mindee import Client, PredictResponse, product + +# Init a new client +mindee_client = Client(api_key="my-api-key") + +# Load a file from disk +input_doc = mindee_client.source_from_path("/path/to/the/file.ext") + +# Load a file from disk and parse it. +# The endpoint name must be specified since it cannot be determined from the class. +result: PredictResponse = mindee_client.parse(product.us.DriverLicenseV1, input_doc) + +# Print a brief summary of the parsed data +print(result.document) + +# # Iterate over all the fields in the document +# for field_name, field_values in result.document.inference.prediction.fields.items(): +# print(field_name, "=", field_values) +``` + +**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 `BaseField` class. +A typical `BaseField` object will have the following attributes: + +* **value** (`Union[float, str]`): corresponds to the field value. Can be `None` if no value was extracted. +* **confidence** (`float`): the confidence score of the field prediction. +* **bounding_box** (`[Point, Point, Point, Point]`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document. +* **polygon** (`List[Point]`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image. +* **page_id** (`int`): the ID of the page, is `None` when at document-level. +* **reconstructed** (`bool`): indicates whether or not an object was reconstructed (not extracted as the API gave it). + +> **Note:** A `Point` simply refers to a List of two numbers (`[float, float]`). + + +Aside from the previous attributes, all basic fields have access to a custom `__str__` method that can be used to print their value as a string. + +### Date Field +Aside from the basic `BaseField` attributes, the date field `DateField` also implements the following: + +* **date_object** (`Date`): an accessible representation of the value as a python object. Can be `None`. + + +### Position Field +The position field `PositionField` does not implement all the basic `BaseField` attributes, only **bounding_box**, **polygon** and **page_id**. On top of these, it has access to: + +* **rectangle** (`[Point, Point, Point, Point]`): a Polygon with four points that may be oriented (even beyond canvas). +* **quadrangle** (`[Point, Point, Point, Point]`): a free polygon made up of four points. + +### String Field +The text field `StringField` only has one constraint: its **value** is an `Optional[str]`. + +## 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** : US driver license holders address + +```py +print(result.document.inference.prediction.address.value) +``` + +## Date Of Birth +**date_of_birth** : US driver license holders date of birth + +```py +print(result.document.inference.prediction.date_of_birth.value) +``` + +## Document Discriminator +**dd_number** : Document Discriminator Number of the US Driver License + +```py +print(result.document.inference.prediction.dd_number.value) +``` + +## Driver License Class +**dl_class** : US driver license holders class + +```py +print(result.document.inference.prediction.dl_class.value) +``` + +## Driver License ID +**driver_license_id** : ID number of the US Driver License. + +```py +print(result.document.inference.prediction.driver_license_id.value) +``` + +## Endorsements +**endorsements** : US driver license holders endorsements + +```py +print(result.document.inference.prediction.endorsements.value) +``` + +## Expiry Date +**expiry_date** : Date on which the documents expires. + +```py +print(result.document.inference.prediction.expiry_date.value) +``` + +## Eye Color +**eye_color** : US driver license holders eye colour + +```py +print(result.document.inference.prediction.eye_color.value) +``` + +## First Name +**first_name** : US driver license holders first name(s) + +```py +print(result.document.inference.prediction.first_name.value) +``` + +## Hair Color +**hair_color** : US driver license holders hair colour + +```py +print(result.document.inference.prediction.hair_color.value) +``` + +## Height +**height** : US driver license holders hight + +```py +print(result.document.inference.prediction.height.value) +``` + +## Date Of Issue +**issued_date** : Date on which the documents was issued. + +```py +print(result.document.inference.prediction.issued_date.value) +``` + +## Last Name +**last_name** : US driver license holders last name + +```py +print(result.document.inference.prediction.last_name.value) +``` + +## Photo +[๐Ÿ“„](#page-level-fields "This field is only present on individual pages.")**photo** : Has a photo of the US driver license holder + +```py +for photo_elem of result.document.photo: + print(photo_elem.polygon) +``` + +## Restrictions +**restrictions** : US driver license holders restrictions + +```py +print(result.document.inference.prediction.restrictions.value) +``` + +## Sex +**sex** : US driver license holders gender + +```py +print(result.document.inference.prediction.sex.value) +``` + +## Signature +[๐Ÿ“„](#page-level-fields "This field is only present on individual pages.")**signature** : Has a signature of the US driver license holder + +```py +for signature_elem of result.document.signature: + print(signature_elem.polygon) +``` + +## State +**state** : US State + +```py +print(result.document.inference.prediction.state.value) +``` + +## Weight +**weight** : US driver license holders weight + +```py +print(result.document.inference.prediction.weight.value) +``` + +# Questions? +[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw) diff --git a/docs/extras/guide/us_w9_v1.md b/docs/extras/guide/us_w9_v1.md new file mode 100644 index 00000000..3c85ddc8 --- /dev/null +++ b/docs/extras/guide/us_w9_v1.md @@ -0,0 +1,199 @@ +--- +title: US W9 OCR Python +--- +The Python OCR SDK supports the [W9 API](https://platform.mindee.com/mindee/us_w9). + +Using the [sample below](https://github.com/mindee/client-lib-test-data/blob/main/products/us_w9/default_sample.jpg), we are going to illustrate how to extract the data that we want using the OCR SDK. +![W9 sample](https://github.com/mindee/client-lib-test-data/blob/main/products/us_w9/default_sample.jpg?raw=true) + +# Quick-Start +```py +from mindee import Client, PredictResponse, product + +# Init a new client +mindee_client = Client(api_key="my-api-key") + +# Load a file from disk +input_doc = mindee_client.source_from_path("/path/to/the/file.ext") + +# Load a file from disk and parse it. +# The endpoint name must be specified since it cannot be determined from the class. +result: PredictResponse = mindee_client.parse(product.us.W9V1, input_doc) + +# Print a brief summary of the parsed data +print(result.document) + +# # Iterate over all the fields in the document +# for field_name, field_values in result.document.inference.prediction.fields.items(): +# print(field_name, "=", field_values) +``` + +**Output (RST):** +```rst +######## +Document +######## +:Mindee ID: d7c5b25f-e0d3-4491-af54-6183afa1aaab +:Filename: default_sample.jpg + +Inference +######### +:Product: mindee/us_w9 v1.0 +:Rotation applied: Yes + +Prediction +========== + +Page Predictions +================ + +Page 0 +------ +:Name: Stephen W Hawking +:SSN: 560758145 +:Address: Somewhere In Milky Way +:City State Zip: Probably Still At Cambridge P O Box CB1 +:Business Name: +:EIN: 942203664 +:Tax Classification: individual +:Tax Classification Other Details: +:W9 Revision Date: august 2013 +:Signature Position: Polygon with 4 points. +:Signature Date Position: +:Tax Classification LLC: +``` + +# 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 `BaseField` class. +A typical `BaseField` object will have the following attributes: + +* **value** (`Union[float, str]`): corresponds to the field value. Can be `None` if no value was extracted. +* **confidence** (`float`): the confidence score of the field prediction. +* **bounding_box** (`[Point, Point, Point, Point]`): contains exactly 4 relative vertices (points) coordinates of a right rectangle containing the field in the document. +* **polygon** (`List[Point]`): contains the relative vertices coordinates (`Point`) of a polygon containing the field in the image. +* **page_id** (`int`): the ID of the page, is `None` when at document-level. +* **reconstructed** (`bool`): indicates whether or not an object was reconstructed (not extracted as the API gave it). + +> **Note:** A `Point` simply refers to a List of two numbers (`[float, float]`). + + +Aside from the previous attributes, all basic fields have access to a custom `__str__` method that can be used to print their value as a string. + + +### Position Field +The position field `PositionField` does not implement all the basic `BaseField` attributes, only **bounding_box**, **polygon** and **page_id**. On top of these, it has access to: + +* **rectangle** (`[Point, Point, Point, Point]`): a Polygon with four points that may be oriented (even beyond canvas). +* **quadrangle** (`[Point, Point, Point, Point]`): a free polygon made up of four points. + +### String Field +The text field `StringField` only has one constraint: its **value** is an `Optional[str]`. + +## 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 W9 V1: + +## Address +[๐Ÿ“„](#page-level-fields "This field is only present on individual pages.")**address** : The street address (number, street, and apt. or suite no.) of the applicant. + +```py +for address_elem of result.document.address: + print(address_elem.value) +``` + +## Business Name +[๐Ÿ“„](#page-level-fields "This field is only present on individual pages.")**business_name** : The business name or disregarded entity name, if different from Name. + +```py +for business_name_elem of result.document.business_name: + print(business_name_elem.value) +``` + +## City State Zip +[๐Ÿ“„](#page-level-fields "This field is only present on individual pages.")**city_state_zip** : The city, state, and ZIP code of the applicant. + +```py +for city_state_zip_elem of result.document.city_state_zip: + print(city_state_zip_elem.value) +``` + +## EIN +[๐Ÿ“„](#page-level-fields "This field is only present on individual pages.")**ein** : The employer identification number. + +```py +for ein_elem of result.document.ein: + print(ein_elem.value) +``` + +## Name +[๐Ÿ“„](#page-level-fields "This field is only present on individual pages.")**name** : Name as shown on the applicant's income tax return. + +```py +for name_elem of result.document.name: + print(name_elem.value) +``` + +## Signature Date Position +[๐Ÿ“„](#page-level-fields "This field is only present on individual pages.")**signature_date_position** : Position of the signature date on the document. + +```py +for signature_date_position_elem of result.document.signature_date_position: + print(signature_date_position_elem.polygon) +``` + +## Signature Position +[๐Ÿ“„](#page-level-fields "This field is only present on individual pages.")**signature_position** : Position of the signature on the document. + +```py +for signature_position_elem of result.document.signature_position: + print(signature_position_elem.polygon) +``` + +## SSN +[๐Ÿ“„](#page-level-fields "This field is only present on individual pages.")**ssn** : The applicant's social security number. + +```py +for ssn_elem of result.document.ssn: + print(ssn_elem.value) +``` + +## Tax Classification +[๐Ÿ“„](#page-level-fields "This field is only present on individual pages.")**tax_classification** : The federal tax classification, which can vary depending on the revision date. + +```py +for tax_classification_elem of result.document.tax_classification: + print(tax_classification_elem.value) +``` + +## Tax Classification LLC +[๐Ÿ“„](#page-level-fields "This field is only present on individual pages.")**tax_classification_llc** : Depending on revision year, among S, C, P or D for Limited Liability Company Classification. + +```py +for tax_classification_llc_elem of result.document.tax_classification_llc: + print(tax_classification_llc_elem.value) +``` + +## Tax Classification Other Details +[๐Ÿ“„](#page-level-fields "This field is only present on individual pages.")**tax_classification_other_details** : Tax Classification Other Details. + +```py +for tax_classification_other_details_elem of result.document.tax_classification_other_details: + print(tax_classification_other_details_elem.value) +``` + +## W9 Revision Date +[๐Ÿ“„](#page-level-fields "This field is only present on individual pages.")**w9_revision_date** : The Revision month and year of the W9 form. + +```py +for w9_revision_date_elem of result.document.w9_revision_date: + print(w9_revision_date_elem.value) +``` + +# Questions? +[Join our Slack](https://join.slack.com/t/mindee-community/shared_invite/zt-1jv6nawjq-FDgFcF2T5CmMmRpl9LLptw)