azure.ai.formrecognizer package¶
-
class
azure.ai.formrecognizer.
FormRecognizerClient
(endpoint: str, credential: Union[AzureKeyCredential, TokenCredential], **kwargs: Any)[source]¶ FormRecognizerClient extracts information from forms and images into structured data. It is the interface to use for analyzing receipts, recognizing content/layout from forms, and analyzing custom forms from trained models. It provides different methods based on inputs from a URL and inputs from a stream.
- Parameters
endpoint (str) – Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).
credential (
AzureKeyCredential
orTokenCredential
) – Credentials needed for the client to connect to Azure. This is an instance of AzureKeyCredential if using an API key or a token credential fromazure.identity
.
Example:
from azure.core.credentials import AzureKeyCredential from azure.ai.formrecognizer import FormRecognizerClient endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"] key = os.environ["AZURE_FORM_RECOGNIZER_KEY"] form_recognizer_client = FormRecognizerClient(endpoint, AzureKeyCredential(key))
"""DefaultAzureCredential will use the values from these environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET """ from azure.ai.formrecognizer import FormRecognizerClient from azure.identity import DefaultAzureCredential endpoint = os.environ["AZURE_FORM_RECOGNIZER_AAD_ENDPOINT"] credential = DefaultAzureCredential() form_recognizer_client = FormRecognizerClient(endpoint, credential)
-
begin_recognize_content
(form: Union[bytes, IO[bytes]], **kwargs: Any) → LROPoller[List[FormPage]][source]¶ Extract text and content/layout information from a given document. The input document must be of one of the supported content types - ‘application/pdf’, ‘image/jpeg’, ‘image/png’ or ‘image/tiff’.
- Parameters
form (bytes or IO[bytes]) – JPEG, PNG, PDF and TIFF type file stream or bytes.
- Keyword Arguments
content_type (str or FormContentType) – Media type of the body sent to the API. Content-type is auto-detected, but can be overridden by passing this keyword argument. For options, see
FormContentType
.polling_interval (int) – Waiting time between two polls for LRO operations if no Retry-After header is present. Defaults to 5 seconds.
continuation_token (str) – A continuation token to restart a poller from a saved state.
- Returns
An instance of an LROPoller. Call result() on the poller object to return a list[
FormPage
].- Return type
- Raises
Example:
from azure.core.credentials import AzureKeyCredential from azure.ai.formrecognizer import FormRecognizerClient endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"] key = os.environ["AZURE_FORM_RECOGNIZER_KEY"] form_recognizer_client = FormRecognizerClient(endpoint=endpoint, credential=AzureKeyCredential(key)) with open(path_to_sample_forms, "rb") as f: poller = form_recognizer_client.begin_recognize_content(form=f) contents = poller.result() for idx, content in enumerate(contents): print("----Recognizing content from page #{}----".format(idx)) print("Has width: {} and height: {}, measured with unit: {}".format( content.width, content.height, content.unit )) for table_idx, table in enumerate(content.tables): print("Table # {} has {} rows and {} columns".format(table_idx, table.row_count, table.column_count)) for cell in table.cells: print("...Cell[{}][{}] has text '{}' within bounding box '{}'".format( cell.row_index, cell.column_index, cell.text, format_bounding_box(cell.bounding_box) ))
-
begin_recognize_content_from_url
(form_url: str, **kwargs: Any) → LROPoller[List[FormPage]][source]¶ Extract text and layout information from a given document. The input document must be the location (URL) of the document to be analyzed.
-
begin_recognize_custom_forms
(model_id: str, form: Union[bytes, IO[bytes]], **kwargs: Any) → LROPoller[List[RecognizedForm]][source]¶ Analyze a custom form with a model trained with or without labels. The form to analyze should be of the same type as the forms that were used to train the model. The input document must be of one of the supported content types - ‘application/pdf’, ‘image/jpeg’, ‘image/png’ or ‘image/tiff’.
- Parameters
- Keyword Arguments
include_field_elements (bool) – Whether or not to include field elements such as lines and words in addition to form fields.
content_type (str or FormContentType) – Media type of the body sent to the API. Content-type is auto-detected, but can be overridden by passing this keyword argument. For options, see
FormContentType
.polling_interval (int) – Waiting time between two polls for LRO operations if no Retry-After header is present. Defaults to 5 seconds.
continuation_token (str) – A continuation token to restart a poller from a saved state.
- Returns
An instance of an LROPoller. Call result() on the poller object to return a list[
RecognizedForm
].- Return type
- Raises
Example:
from azure.core.credentials import AzureKeyCredential from azure.ai.formrecognizer import FormRecognizerClient endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"] key = os.environ["AZURE_FORM_RECOGNIZER_KEY"] model_id = os.environ["CUSTOM_TRAINED_MODEL_ID"] form_recognizer_client = FormRecognizerClient( endpoint=endpoint, credential=AzureKeyCredential(key) ) # Make sure your form's type is included in the list of form types the custom model can recognize with open(path_to_sample_forms, "rb") as f: poller = form_recognizer_client.begin_recognize_custom_forms( model_id=model_id, form=f ) forms = poller.result() for idx, form in enumerate(forms): print("--------Recognizing Form #{}--------".format(idx)) print("Form {} has type {}".format(idx, form.form_type)) for name, field in form.fields.items(): # each field is of type FormField # The value of the field can also be a FormField, or a list of FormFields # In our sample, it is just a FormField. print("...Field '{}' has value '{}' with a confidence score of {}".format( name, field.value, field.confidence )) # label data is populated if you are using a model trained with unlabeled data, since the service needs to make predictions for # labels if not explicitly given to it. if field.label_data: print("...Field '{}' has label '{}' with a confidence score of {}".format( name, field.label_data.text, field.confidence )) print("-----------------------------------")
-
begin_recognize_custom_forms_from_url
(model_id: str, form_url: str, **kwargs: Any) → LROPoller[List[RecognizedForm]][source]¶ Analyze a custom form with a model trained with or without labels. The form to analyze should be of the same type as the forms that were used to train the model. The input document must be the location (URL) of the document to be analyzed.
- Parameters
- Keyword Arguments
include_field_elements (bool) – Whether or not to include field elements such as lines and words in addition to form fields.
polling_interval (int) – Waiting time between two polls for LRO operations if no Retry-After header is present. Defaults to 5 seconds.
continuation_token (str) – A continuation token to restart a poller from a saved state.
- Returns
An instance of an LROPoller. Call result() on the poller object to return a list[
RecognizedForm
].- Return type
- Raises
-
begin_recognize_receipts
(receipt: Union[bytes, IO[bytes]], **kwargs: Any) → LROPoller[List[RecognizedForm]][source]¶ Extract field text and semantic values from a given US sales receipt. The input document must be of one of the supported content types - ‘application/pdf’, ‘image/jpeg’, ‘image/png’ or ‘image/tiff’.
See fields found on a receipt here: https://aka.ms/azsdk/python/formrecognizer/receiptfields
- Parameters
receipt (bytes or IO[bytes]) – JPEG, PNG, PDF and TIFF type file stream or bytes. Currently only supports US sales receipts.
- Keyword Arguments
include_field_elements (bool) – Whether or not to include field elements such as lines and words in addition to form fields.
content_type (str or FormContentType) – Media type of the body sent to the API. Content-type is auto-detected, but can be overridden by passing this keyword argument. For options, see
FormContentType
.polling_interval (int) – Waiting time between two polls for LRO operations if no Retry-After header is present. Defaults to 5 seconds.
continuation_token (str) – A continuation token to restart a poller from a saved state.
- Returns
An instance of an LROPoller. Call result() on the poller object to return a list[
RecognizedForm
].- Return type
- Raises
Example:
from azure.core.credentials import AzureKeyCredential from azure.ai.formrecognizer import FormRecognizerClient endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"] key = os.environ["AZURE_FORM_RECOGNIZER_KEY"] form_recognizer_client = FormRecognizerClient( endpoint=endpoint, credential=AzureKeyCredential(key) ) with open(path_to_sample_forms, "rb") as f: poller = form_recognizer_client.begin_recognize_receipts(receipt=f) receipts = poller.result() for idx, receipt in enumerate(receipts): print("--------Recognizing receipt #{}--------".format(idx)) receipt_type = receipt.fields.get("ReceiptType") if receipt_type: print("Receipt Type: {} has confidence: {}".format(receipt_type.value, receipt_type.confidence)) merchant_name = receipt.fields.get("MerchantName") if merchant_name: print("Merchant Name: {} has confidence: {}".format(merchant_name.value, merchant_name.confidence)) transaction_date = receipt.fields.get("TransactionDate") if transaction_date: print("Transaction Date: {} has confidence: {}".format(transaction_date.value, transaction_date.confidence)) print("Receipt items:") for idx, item in enumerate(receipt.fields.get("Items").value): print("...Item #{}".format(idx)) item_name = item.value.get("Name") if item_name: print("......Item Name: {} has confidence: {}".format(item_name.value, item_name.confidence)) item_quantity = item.value.get("Quantity") if item_quantity: print("......Item Quantity: {} has confidence: {}".format(item_quantity.value, item_quantity.confidence)) item_price = item.value.get("Price") if item_price: print("......Individual Item Price: {} has confidence: {}".format(item_price.value, item_price.confidence)) item_total_price = item.value.get("TotalPrice") if item_total_price: print("......Total Item Price: {} has confidence: {}".format(item_total_price.value, item_total_price.confidence)) subtotal = receipt.fields.get("Subtotal") if subtotal: print("Subtotal: {} has confidence: {}".format(subtotal.value, subtotal.confidence)) tax = receipt.fields.get("Tax") if tax: print("Tax: {} has confidence: {}".format(tax.value, tax.confidence)) tip = receipt.fields.get("Tip") if tip: print("Tip: {} has confidence: {}".format(tip.value, tip.confidence)) total = receipt.fields.get("Total") if total: print("Total: {} has confidence: {}".format(total.value, total.confidence)) print("--------------------------------------")
-
begin_recognize_receipts_from_url
(receipt_url: str, **kwargs: Any) → LROPoller[List[RecognizedForm]][source]¶ Extract field text and semantic values from a given US sales receipt. The input document must be the location (URL) of the receipt to be analyzed.
See fields found on a receipt here: https://aka.ms/azsdk/python/formrecognizer/receiptfields
- Parameters
receipt_url (str) – The URL of the receipt to analyze. The input must be a valid, encoded URL of one of the supported formats: JPEG, PNG, PDF and TIFF. Currently only supports US sales receipts.
- Keyword Arguments
include_field_elements (bool) – Whether or not to include field elements such as lines and words in addition to form fields.
polling_interval (int) – Waiting time between two polls for LRO operations if no Retry-After header is present. Defaults to 5 seconds.
continuation_token (str) – A continuation token to restart a poller from a saved state.
- Returns
An instance of an LROPoller. Call result() on the poller object to return a list[
RecognizedForm
].- Return type
- Raises
Example:
from azure.core.credentials import AzureKeyCredential from azure.ai.formrecognizer import FormRecognizerClient endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"] key = os.environ["AZURE_FORM_RECOGNIZER_KEY"] form_recognizer_client = FormRecognizerClient( endpoint=endpoint, credential=AzureKeyCredential(key) ) url = "https://raw.githubusercontent.com/Azure/azure-sdk-for-python/master/sdk/formrecognizer/azure-ai-formrecognizer/tests/sample_forms/receipt/contoso-receipt.png" poller = form_recognizer_client.begin_recognize_receipts_from_url(receipt_url=url) receipts = poller.result() for idx, receipt in enumerate(receipts): print("--------Recognizing receipt #{}--------".format(idx)) receipt_type = receipt.fields.get("ReceiptType") if receipt_type: print("Receipt Type: {} has confidence: {}".format(receipt_type.value, receipt_type.confidence)) merchant_name = receipt.fields.get("MerchantName") if merchant_name: print("Merchant Name: {} has confidence: {}".format(merchant_name.value, merchant_name.confidence)) transaction_date = receipt.fields.get("TransactionDate") if transaction_date: print("Transaction Date: {} has confidence: {}".format(transaction_date.value, transaction_date.confidence)) print("Receipt items:") for idx, item in enumerate(receipt.fields.get("Items").value): print("...Item #{}".format(idx)) item_name = item.value.get("Name") if item_name: print("......Item Name: {} has confidence: {}".format(item_name.value, item_name.confidence)) item_quantity = item.value.get("Quantity") if item_quantity: print("......Item Quantity: {} has confidence: {}".format(item_quantity.value, item_quantity.confidence)) item_price = item.value.get("Price") if item_price: print("......Individual Item Price: {} has confidence: {}".format(item_price.value, item_price.confidence)) item_total_price = item.value.get("TotalPrice") if item_total_price: print("......Total Item Price: {} has confidence: {}".format(item_total_price.value, item_total_price.confidence)) subtotal = receipt.fields.get("Subtotal") if subtotal: print("Subtotal: {} has confidence: {}".format(subtotal.value, subtotal.confidence)) tax = receipt.fields.get("Tax") if tax: print("Tax: {} has confidence: {}".format(tax.value, tax.confidence)) tip = receipt.fields.get("Tip") if tip: print("Tip: {} has confidence: {}".format(tip.value, tip.confidence)) total = receipt.fields.get("Total") if total: print("Total: {} has confidence: {}".format(total.value, total.confidence)) print("--------------------------------------")
-
close
() → None[source]¶ Close the
FormRecognizerClient
session.
-
class
azure.ai.formrecognizer.
FormTrainingClient
(endpoint: str, credential: Union[AzureKeyCredential, TokenCredential], **kwargs: Any)[source]¶ FormTrainingClient is the Form Recognizer interface to use for creating, and managing custom models. It provides methods for training models on the forms you provide, as well as methods for viewing and deleting models, accessing account properties, and copying a model to another Form Recognizer resource.
- Parameters
endpoint (str) – Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).
credential (
AzureKeyCredential
orTokenCredential
) – Credentials needed for the client to connect to Azure. This is an instance of AzureKeyCredential if using an API key or a token credential fromazure.identity
.
Example:
from azure.core.credentials import AzureKeyCredential from azure.ai.formrecognizer import FormTrainingClient endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"] key = os.environ["AZURE_FORM_RECOGNIZER_KEY"] form_training_client = FormTrainingClient(endpoint, AzureKeyCredential(key))
"""DefaultAzureCredential will use the values from these environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET """ from azure.ai.formrecognizer import FormTrainingClient from azure.identity import DefaultAzureCredential endpoint = os.environ["AZURE_FORM_RECOGNIZER_AAD_ENDPOINT"] credential = DefaultAzureCredential() form_training_client = FormTrainingClient(endpoint, credential)
-
begin_copy_model
(model_id: str, target: Dict, **kwargs: Any) → azure.core.polling._poller.LROPoller[azure.ai.formrecognizer._models.CustomFormModelInfo][source]¶ Copy a custom model stored in this resource (the source) to the user specified target Form Recognizer resource. This should be called with the source Form Recognizer resource (with the model that is intended to be copied). The target parameter should be supplied from the target resource’s output from calling the
get_copy_authorization()
method.- Parameters
model_id (str) – Model identifier of the model to copy to target resource.
target (dict) – The copy authorization generated from the target resource’s call to
get_copy_authorization()
.
- Keyword Arguments
- Returns
An instance of an LROPoller. Call result() on the poller object to return a
CustomFormModelInfo
.- Return type
- Raises
Example:
source_client = FormTrainingClient(endpoint=source_endpoint, credential=AzureKeyCredential(source_key)) poller = source_client.begin_copy_model( model_id=source_model_id, target=target # output from target client's call to get_copy_authorization() ) copied_over_model = poller.result() print("Model ID: {}".format(copied_over_model.model_id)) print("Status: {}".format(copied_over_model.status))
-
begin_training
(training_files_url: str, use_training_labels: bool, **kwargs: Any) → azure.core.polling._poller.LROPoller[azure.ai.formrecognizer._models.CustomFormModel][source]¶ Create and train a custom model. The request must include a training_files_url parameter that is an externally accessible Azure storage blob container URI (preferably a Shared Access Signature URI). Note that a container URI is accepted only when the container is public. Models are trained using documents that are of the following content type - ‘application/pdf’, ‘image/jpeg’, ‘image/png’, ‘image/tiff’. Other type of content in the container is ignored.
- Parameters
- Keyword Arguments
prefix (str) – A case-sensitive prefix string to filter documents in the source path for training. For example, when using a Azure storage blob URI, use the prefix to restrict sub folders for training.
include_sub_folders (bool) – A flag to indicate if sub folders within the set of prefix folders will also need to be included when searching for content to be preprocessed. Not supported if training with labels.
polling_interval (int) – Waiting time between two polls for LRO operations if no Retry-After header is present. Defaults to 5 seconds.
continuation_token (str) – A continuation token to restart a poller from a saved state.
- Returns
An instance of an LROPoller. Call result() on the poller object to return a
CustomFormModel
.- Return type
- Raises
HttpResponseError – Note that if the training fails, the exception is raised, but a model with an “invalid” status is still created. You can delete this model by calling
delete_model()
Example:
from azure.ai.formrecognizer import FormTrainingClient from azure.core.credentials import AzureKeyCredential endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"] key = os.environ["AZURE_FORM_RECOGNIZER_KEY"] container_sas_url = os.environ["CONTAINER_SAS_URL"] form_training_client = FormTrainingClient(endpoint, AzureKeyCredential(key)) poller = form_training_client.begin_training(container_sas_url, use_training_labels=False) model = poller.result() # Custom model information print("Model ID: {}".format(model.model_id)) print("Status: {}".format(model.status)) print("Training started on: {}".format(model.training_started_on)) print("Training completed on: {}".format(model.training_completed_on)) print("Recognized fields:") # Looping through the submodels, which contains the fields they were trained on for submodel in model.submodels: print("...The submodel has form type '{}'".format(submodel.form_type)) for name, field in submodel.fields.items(): print("...The model found field '{}' to have label '{}'".format( name, field.label ))
-
close
() → None[source]¶ Close the
FormTrainingClient
session.
-
delete_model
(model_id: str, **kwargs: Any) → None[source]¶ Mark model for deletion. Model artifacts will be permanently removed within a predetermined period.
- Parameters
model_id (str) – Model identifier.
- Return type
- Raises
Example:
form_training_client.delete_model(model_id=custom_model.model_id) try: form_training_client.get_custom_model(model_id=custom_model.model_id) except ResourceNotFoundError: print("Successfully deleted model with id {}".format(custom_model.model_id))
-
get_account_properties
(**kwargs: Any) → azure.ai.formrecognizer._models.AccountProperties[source]¶ Get information about the models on the form recognizer account.
- Returns
Summary of models on account - custom model count, custom model limit.
- Return type
- Raises
Example:
from azure.core.credentials import AzureKeyCredential from azure.core.exceptions import ResourceNotFoundError from azure.ai.formrecognizer import FormTrainingClient endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"] key = os.environ["AZURE_FORM_RECOGNIZER_KEY"] form_training_client = FormTrainingClient(endpoint=endpoint, credential=AzureKeyCredential(key)) # First, we see how many custom models we have, and what our limit is account_properties = form_training_client.get_account_properties() print("Our account has {} custom models, and we can have at most {} custom models".format( account_properties.custom_model_count, account_properties.custom_model_limit ))
Generate authorization for copying a custom model into the target Form Recognizer resource. This should be called by the target resource (where the model will be copied to) and the output can be passed as the target parameter into
begin_copy_model()
.- Parameters
resource_id (str) – Azure Resource Id of the target Form Recognizer resource where the model will be copied to.
resource_region (str) – Location of the target Form Recognizer resource. A valid Azure region name supported by Cognitive Services. For example, ‘westus’, ‘eastus’ etc. See https://azure.microsoft.com/global-infrastructure/services/?products=cognitive-services for the regional availability of Cognitive Services
- Returns
A dictionary with values for the copy authorization - “modelId”, “accessToken”, “resourceId”, “resourceRegion”, and “expirationDateTimeTicks”.
- Return type
- Raises
Example:
target_client = FormTrainingClient(endpoint=target_endpoint, credential=AzureKeyCredential(target_key)) target = target_client.get_copy_authorization( resource_region=target_region, resource_id=target_resource_id ) # model ID that target client will use to access the model once copy is complete print("Model ID: {}".format(target["modelId"]))
-
get_custom_model
(model_id: str, **kwargs: Any) → azure.ai.formrecognizer._models.CustomFormModel[source]¶ Get a description of a custom model, including the types of forms it can recognize, and the fields it will extract for each form type.
- Parameters
model_id (str) – Model identifier.
- Returns
CustomFormModel
- Return type
- Raises
Example:
custom_model = form_training_client.get_custom_model(model_id=first_model.model_id) print("Model ID: {}".format(custom_model.model_id)) print("Status: {}".format(custom_model.status)) print("Training started on: {}".format(custom_model.training_started_on)) print("Training completed on: {}".format(custom_model.training_completed_on))
-
get_form_recognizer_client
(**kwargs: Any) → azure.ai.formrecognizer._form_recognizer_client.FormRecognizerClient[source]¶ Get an instance of a FormRecognizerClient from FormTrainingClient.
- Return type
- Returns
A FormRecognizerClient
-
list_custom_models
(**kwargs: Any) → ItemPaged[CustomFormModelInfo][source]¶ List information for each model, including model id, model status, and when it was created and last modified.
- Returns
ItemPaged[
CustomFormModelInfo
]- Return type
- Raises
Example:
custom_models = form_training_client.list_custom_models() print("We have models with the following ids:") # Let's pull out the first model first_model = next(custom_models) print(first_model.model_id) for model in custom_models: print(model.model_id)
-
class
azure.ai.formrecognizer.
LengthUnit
[source]¶ The unit used by the width, height and bounding box properties. For images, the unit is “pixel”. For PDF, the unit is “inch”.
-
inch
= 'inch'¶
-
pixel
= 'pixel'¶
-
-
class
azure.ai.formrecognizer.
TrainingStatus
[source]¶ Status of the training operation.
-
failed
= 'failed'¶
-
partially_succeeded
= 'partiallySucceeded'¶
-
succeeded
= 'succeeded'¶
-
-
class
azure.ai.formrecognizer.
CustomFormModelStatus
[source]¶ Status indicating the model’s readiness for use.
-
creating
= 'creating'¶
-
invalid
= 'invalid'¶
-
ready
= 'ready'¶
-
-
class
azure.ai.formrecognizer.
FormContentType
[source]¶ Content type for upload
-
application_pdf
= 'application/pdf'¶ Content Type ‘application/pdf’.
-
image_jpeg
= 'image/jpeg'¶ Content Type ‘image/jpeg’.
-
image_png
= 'image/png'¶ Content Type ‘image/png’.
-
image_tiff
= 'image/tiff'¶ Content Type ‘image/tiff’.
-
-
class
azure.ai.formrecognizer.
FormElement
(**kwargs)[source]¶ Base type which includes properties for a form element.
- Variables
text (str) – The text content of the line.
bounding_box (list[Point]) – A list of 4 points representing the quadrilateral bounding box that outlines the text. The points are listed in clockwise order: top-left, top-right, bottom-right, bottom-left. Units are in pixels for images and inches for PDF.
page_number (int) – The 1-based number of the page in which this content is present.
-
class
azure.ai.formrecognizer.
FormTable
(**kwargs)[source]¶ Information about the extracted table contained on a page.
- Variables
page_number (int) – The 1-based number of the page in which this table is present.
cells (list[FormTableCell]) – List of cells contained in the table.
row_count (int) – Number of rows in table.
column_count (int) – Number of columns in table.
-
class
azure.ai.formrecognizer.
FormTableCell
(**kwargs)[source]¶ Represents a cell contained in a table recognized from the input document.
- Variables
text (str) – Text content of the cell.
row_index (int) – Row index of the cell.
column_index (int) – Column index of the cell.
row_span (int) – Number of rows spanned by this cell.
column_span (int) – Number of columns spanned by this cell.
bounding_box (list[Point]) – A list of 4 points representing the quadrilateral bounding box that outlines the text. The points are listed in clockwise order: top-left, top-right, bottom-right, bottom-left. Units are in pixels for images and inches for PDF.
confidence (float) – Measures the degree of certainty of the recognition result. Value is between [0.0, 1.0].
is_header (bool) – Whether the current cell is a header cell.
is_footer (bool) – Whether the current cell is a footer cell.
page_number (int) – The 1-based number of the page in which this content is present.
field_elements (list[FormWord, FormLine]) – When include_field_elements is set to true, a list of elements constituting this cell is returned. The list constitutes of elements such as lines and words. For calls to begin_recognize_content(), this list is always populated.
-
class
azure.ai.formrecognizer.
TrainingDocumentInfo
(**kwargs)[source]¶ Report for an individual document used for training a custom model.
- Variables
document_name (str) – The name of the document.
status (str) – The
TrainingStatus
of the training operation. Possible values include: ‘succeeded’, ‘partiallySucceeded’, ‘failed’.page_count (int) – Total number of pages trained.
errors (list[FormRecognizerError]) – List of any errors for document.
-
class
azure.ai.formrecognizer.
FormRecognizerError
(**kwargs)[source]¶ Represents an error that occurred while training.
-
class
azure.ai.formrecognizer.
CustomFormModelInfo
(**kwargs)[source]¶ Custom model information.
- Variables
model_id (str) – The unique identifier of the model.
status (str) – The status of the model,
CustomFormModelStatus
. Possible values include: ‘creating’, ‘ready’, ‘invalid’.training_started_on (datetime) – Date and time (UTC) when model training was started.
training_completed_on (datetime) – Date and time (UTC) when model training completed.
-
class
azure.ai.formrecognizer.
AccountProperties
(**kwargs)[source]¶ Summary of all the custom models on the account.
-
class
azure.ai.formrecognizer.
Point
[source]¶ The x, y coordinate of a point on a bounding box.
Create new instance of Point(x, y)
-
count
(value) → integer – return number of occurrences of value¶
-
index
(value[, start[, stop]]) → integer – return first index of value.¶ Raises ValueError if the value is not present.
-
property
x
¶ Alias for field number 0
-
property
y
¶ Alias for field number 1
-
-
class
azure.ai.formrecognizer.
FormPageRange
[source]¶ The 1-based page range of the form.
- Variables
first_page_number (int) – The first page number of the form.
last_page_number (int) – The last page number of the form.
Create new instance of FormPageRange(first_page_number, last_page_number)
-
count
(value) → integer – return number of occurrences of value¶
-
index
(value[, start[, stop]]) → integer – return first index of value.¶ Raises ValueError if the value is not present.
-
property
first_page_number
¶ Alias for field number 0
-
property
last_page_number
¶ Alias for field number 1
-
class
azure.ai.formrecognizer.
RecognizedForm
(**kwargs)[source]¶ Represents a form that has been recognized by a trained model.
- Variables
form_type (str) – The type of form the model identified the submitted form to be.
fields (dict[str, FormField]) – A dictionary of the fields found on the form. The fields dictionary keys are the name of the field. For models trained with labels, this is the training-time label of the field. For models trained without labels, a unique name is generated for each field.
page_range (FormPageRange) – The first and last page number of the input form.
pages (list[FormPage]) – A list of pages recognized from the input document. Contains lines, words, tables and page metadata.
-
class
azure.ai.formrecognizer.
FormField
(**kwargs)[source]¶ Represents a field recognized in an input form.
- Variables
label_data (FieldData) – Contains the text, bounding box, and field elements for the field label.
value_data (FieldData) – Contains the text, bounding box, and field elements for the field value.
name (str) – The unique name of the field or label.
value (str, int, float,
date
,time
,FormField
, or list[FormField
]) – The value for the recognized field. Possible types include: ‘string’, ‘date’, ‘time’, ‘phoneNumber’, ‘number’, ‘integer’, ‘object’, or ‘array’.confidence (float) – Measures the degree of certainty of the recognition result. Value is between [0.0, 1.0].
-
class
azure.ai.formrecognizer.
FieldData
(**kwargs)[source]¶ Represents the text that is part of a form field. This includes the location of the text in the form and a collection of the elements that make up the text.
- Variables
page_number (int) – The 1-based number of the page in which this content is present.
text (str) – The string representation of the field or value.
bounding_box (list[Point]) – A list of 4 points representing the quadrilateral bounding box that outlines the text. The points are listed in clockwise order: top-left, top-right, bottom-right, bottom-left. Units are in pixels for images and inches for PDF.
field_elements (list[FormWord, FormLine]) – When include_field_elements is set to true, a list of elements constituting this field or value is returned. The list constitutes of elements such as lines and words.
-
class
azure.ai.formrecognizer.
FormPage
(**kwargs)[source]¶ Represents a page recognized from the input document. Contains lines, words, tables and page metadata.
- Variables
page_number (int) – The 1-based number of the page in which this content is present.
text_angle (float) – The general orientation of the text in clockwise direction, measured in degrees between (-180, 180].
width (float) – The width of the image/PDF in pixels/inches, respectively.
height (float) – The height of the image/PDF in pixels/inches, respectively.
unit (str) – The
LengthUnit
used by the width, height, and bounding box properties. For images, the unit is “pixel”. For PDF, the unit is “inch”.tables (list[FormTable]) – A list of extracted tables contained in a page.
lines (list[FormLine]) – When include_field_elements is set to true, a list of recognized text lines is returned. For calls to recognize content, this list is always populated. The maximum number of lines returned is 300 per page. The lines are sorted top to bottom, left to right, although in certain cases proximity is treated with higher priority. As the sorting order depends on the detected text, it may change across images and OCR version updates. Thus, business logic should be built upon the actual line location instead of order.
-
class
azure.ai.formrecognizer.
FormLine
(**kwargs)[source]¶ An object representing an extracted line of text.
- Variables
text (str) – The text content of the line.
bounding_box (list[Point]) – A list of 4 points representing the quadrilateral bounding box that outlines the text. The points are listed in clockwise order: top-left, top-right, bottom-right, bottom-left. Units are in pixels for images and inches for PDF.
words (list[FormWord]) – A list of the words that make up the line.
page_number (int) – The 1-based number of the page in which this content is present.
-
class
azure.ai.formrecognizer.
FormWord
(**kwargs)[source]¶ Represents a word recognized from the input document.
- Variables
text (str) – The text content of the word.
bounding_box (list[Point]) – A list of 4 points representing the quadrilateral bounding box that outlines the text. The points are listed in clockwise order: top-left, top-right, bottom-right, bottom-left. Units are in pixels for images and inches for PDF.
confidence (float) – Measures the degree of certainty of the recognition result. Value is between [0.0, 1.0].
page_number (int) – The 1-based number of the page in which this content is present.
-
class
azure.ai.formrecognizer.
CustomFormModel
(**kwargs)[source]¶ Represents a model trained from custom forms.
- Variables
model_id (str) – The unique identifier of this model.
status (str) – Status indicating the model’s readiness for use,
CustomFormModelStatus
. Possible values include: ‘creating’, ‘ready’, ‘invalid’.training_started_on (datetime) – The date and time (UTC) when model training was started.
training_completed_on (datetime) – Date and time (UTC) when model training completed.
submodels (list[CustomFormSubmodel]) – A list of submodels that are part of this model, each of which can recognize and extract fields from a different type of form.
errors (list[FormRecognizerError]) – List of any training errors.
training_documents (TrainingDocumentInfo) – Metadata about each of the documents used to train the model.
-
class
azure.ai.formrecognizer.
CustomFormSubmodel
(**kwargs)[source]¶ Represents a submodel that extracts fields from a specific type of form.
- Variables
accuracy (float) – The mean of the model’s field accuracies.
fields (dict[str, CustomFormModelField]) – A dictionary of the fields that this submodel will recognize from the input document. The fields dictionary keys are the name of the field. For models trained with labels, this is the training-time label of the field. For models trained without labels, a unique name is generated for each field.
form_type (str) – Type of form this submodel recognizes.
-
class
azure.ai.formrecognizer.
CustomFormModelField
(**kwargs)[source]¶ A field that the model will extract from forms it analyzes.