Skip to content

[formrecognizer] Use get_words and get_lines in samples #21533

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
catalinaperalta merged 10 commits into from
Nov 3, 2021
Merged

[formrecognizer] Use get_words and get_lines in samples #21533

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
4ed5f4d
use get_words and get_lines in samples
catalinaperalta Nov 2, 2021
d4385ec
Merge branch 'main' of https://github.com/Azure/azure-sdk-for-python …
catalinaperalta Nov 2, 2021
0b7def2
fix comment and add info on README
catalinaperalta Nov 2, 2021
9c7b17e
fix wording in sample
catalinaperalta Nov 2, 2021
5e408af
update readme
catalinaperalta Nov 2, 2021
5c0b8ce
revert additions to README
catalinaperalta Nov 3, 2021
ae00f6f
add get_words() example to README
catalinaperalta Nov 3, 2021
29858b8
add get children samples
catalinaperalta Nov 3, 2021
b7368c9
remove get_lines from entities
catalinaperalta Nov 3, 2021
f5adfe9
update comment
catalinaperalta Nov 3, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 100 additions & 0 deletions sdk/formrecognizer/azure-ai-formrecognizer/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -540,6 +540,106 @@ except ResourceNotFoundError:
print("Successfully deleted model with id {}".format(custom_model.model_id))
```

### Convenience methods to get items from a specific model (**Beta feature**)

@kristapratico kristapratico Nov 2, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah I thought when you said README you meant add get_lines() and get_words() to the existing examples. Do you think adding a dedicated sample with this info could work? which we could link to from the readme? We've gotten feedback to keep READMEs brief / focused on the big features so I'm not sure this is the right place for it.
Adding @maririos @kinelski @samvaity @witemple-msft for more perspectives on how they plan to show the feature.

@catalinaperalta catalinaperalta Nov 2, 2021

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah that sounds better, will update.

@catalinaperalta catalinaperalta Nov 3, 2021

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done, removed from the readme but added a get words in one of the examples.


In version `azure-ai-formrecognizer (3.2.0b2)`, the following models have a `get_words()` convenience method:
- `AnalyzedDocument`
- `DocumentEntity`
- `DocumentField`
- `DocumentLine`
- `DocumentKeyValueElement`
- `DocumentTable`
- `DocumentTableCell`

The `get_words()` method can be used to obtain the words that are found within the same area of the document element that the call is made on.

For instance, in the example below `get_words()` is called on every document line that is processed:
```python
from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import DocumentAnalysisClient

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

document_analysis_client = DocumentAnalysisClient(
endpoint=endpoint, credential=AzureKeyCredential(key)
)
with open(path_to_sample_documents, "rb") as f:
poller = document_analysis_client.begin_analyze_document(
"prebuilt-document", document=f
)
result = poller.result()

for page in result.pages:
print("----Analyzing document from page #{}----".format(page.page_number))

for line_idx, line in enumerate(page.lines):
words = line.get_words()

print(
"...Line # {} has word count {} and text '{}' within bounding box '{}'".format(
line_idx,
len(words),
line.content,
format_bounding_box(line.bounding_box),
)
)

# print every word found for this line
for word in words:
print(
"......Word '{}' has a confidence of {}".format(
word.content, word.confidence
)
)
```


Likewise, in version `azure-ai-formrecognizer (3.2.0b2)`, the following models have a `get_lines()` convenience method:
- `AnalyzedDocument`
- `DocumentEntity`
- `DocumentField`
- `DocumentKeyValueElement`
- `DocumentTable`
- `DocumentTableCell`

The `get_lines()` method can be used to obtain the lines that are found within the same area of the document element that the call is made on.

For instance, in the example below `get_lines()` is called on every document entity that is processed:
```python
from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import DocumentAnalysisClient

endpoint = os.environ["AZURE_FORM_RECOGNIZER_ENDPOINT"]
key = os.environ["AZURE_FORM_RECOGNIZER_KEY"]

document_analysis_client = DocumentAnalysisClient(
endpoint=endpoint, credential=AzureKeyCredential(key)
)
with open(path_to_sample_documents, "rb") as f:
poller = document_analysis_client.begin_analyze_document(
"prebuilt-document", document=f
)
result = poller.result()

print("----Entities found in document----")
for entity in result.entities:
print("Entity of category '{}' with sub-category '{}'".format(entity.category, entity.sub_category))
# NOTE: Calling get_lines() here will return a list of the DocumentLines that make up the entity.
# These lines can be processed just like any other DocumentLine instance.
lines = entity.get_lines()

# print every line found for this document entity
for line in lines:
print(
"...Line has '{}' text and is within bounding box '{}'".format(
line.content,
line.bounding_box,
)
)
```


## Troubleshooting

### General
Expand Down
24 changes: 18 additions & 6 deletions ...-formrecognizer/samples/v3.2-beta/async_samples/sample_analyze_general_documents_async.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,11 @@ async def analyze_general_documents():
print("----Entities found in document----")
for entity in result.entities:
print("Entity of category '{}' with sub-category '{}'".format(entity.category, entity.sub_category))
# NOTE: Calling get_lines() here will return a list of the DocumentLines that make up the entity.
# These lines can be processed just like any other DocumentLine instance.
line_length = len(entity.get_lines())
if line_length > 0:
print("...has {} line(s)".format(line_length))
Comment thread
catalinaperalta marked this conversation as resolved.
Outdated
print("...has content '{}'".format(entity.content))
print("...within '{}' bounding regions".format(format_bounding_region(entity.bounding_regions)))
print("...with confidence {}\n".format(entity.confidence))
Expand All @@ -101,20 +106,22 @@ async def analyze_general_documents():
)

for line_idx, line in enumerate(page.lines):
words = line.get_words()
print(
"Line # {} has text content '{}' within bounding box '{}'".format(
"...Line # {} has {} words and text '{}' within bounding box '{}'".format(
line_idx,
len(words),
line.content,
format_bounding_box(line.bounding_box),
)
)

for word in page.words:
print(
"...Word '{}' has a confidence of {}".format(
word.content, word.confidence
for word in words:
print(
"......Word '{}' has a confidence of {}".format(
word.content, word.confidence
)
)
)

for selection_mark in page.selection_marks:
print(
Expand All @@ -131,6 +138,11 @@ async def analyze_general_documents():
table_idx, table.row_count, table.column_count
)
)
print(
"Table # {} has {} lines and {} words".format(
table_idx, len(table.get_lines()), len(table.get_words())
)
)
for region in table.bounding_regions:
print(
"Table # {} location on page: {} is {}".format(
Expand Down
14 changes: 8 additions & 6 deletions ...er/azure-ai-formrecognizer/samples/v3.2-beta/async_samples/sample_analyze_layout_async.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,20 +78,22 @@ async def analyze_layout_async():
)

for line_idx, line in enumerate(page.lines):
words = line.get_words()
print(
"Line # {} has text content '{}' within bounding box '{}'".format(
"...Line # {} has word count {} and text '{}' within bounding box '{}'".format(
line_idx,
len(words),
line.content,
format_bounding_box(line.bounding_box),
)
)

for word in page.words:
print(
"...Word '{}' has a confidence of {}".format(
word.content, word.confidence
for word in words:
print(
"......Word '{}' has a confidence of {}".format(
word.content, word.confidence
)
)
)

for selection_mark in page.selection_marks:
print(
Expand Down
24 changes: 18 additions & 6 deletions ...mrecognizer/azure-ai-formrecognizer/samples/v3.2-beta/sample_analyze_general_documents.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,11 @@ def analyze_general_documents():
print("----Entities found in document----")
for entity in result.entities:
print("Entity of category '{}' with sub-category '{}'".format(entity.category, entity.sub_category))
# NOTE: Calling get_lines() here will return a list of the DocumentLines that make up the entity.
# These lines can be processed just like any other DocumentLine instance.
line_length = len(entity.get_lines())
if line_length > 0:
print("...has {} line(s)".format(line_length))
print("...has content '{}'".format(entity.content))
print("...within '{}' bounding regions".format(format_bounding_region(entity.bounding_regions)))
print("...with confidence {}\n".format(entity.confidence))
Expand All @@ -97,20 +102,22 @@ def analyze_general_documents():
)

for line_idx, line in enumerate(page.lines):
words = line.get_words()
print(
"...Line # {} has text content '{}' within bounding box '{}'".format(
"...Line # {} has {} words and text '{}' within bounding box '{}'".format(
line_idx,
len(words),
line.content,
format_bounding_box(line.bounding_box),
)
)

for word in page.words:
print(
"...Word '{}' has a confidence of {}".format(
word.content, word.confidence
for word in words:
print(
"......Word '{}' has a confidence of {}".format(
word.content, word.confidence
)
)
)

for selection_mark in page.selection_marks:
print(
Expand All @@ -127,6 +134,11 @@ def analyze_general_documents():
table_idx, table.row_count, table.column_count
)
)
print(
"Table # {} has {} lines and {} words".format(
table_idx, len(table.get_lines()), len(table.get_words())
)
)
for region in table.bounding_regions:
print(
"Table # {} location on page: {} is {}".format(
Expand Down
14 changes: 8 additions & 6 deletions sdk/formrecognizer/azure-ai-formrecognizer/samples/v3.2-beta/sample_analyze_layout.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,20 +75,22 @@ def analyze_layout():
)

for line_idx, line in enumerate(page.lines):
words = line.get_words()
print(
"...Line # {} has text content '{}' within bounding box '{}'".format(
"...Line # {} has word count {} and text '{}' within bounding box '{}'".format(
line_idx,
len(words),
line.content,
format_bounding_box(line.bounding_box),
)
)

for word in page.words:
print(
"...Word '{}' has a confidence of {}".format(
word.content, word.confidence
for word in words:
print(
"......Word '{}' has a confidence of {}".format(
word.content, word.confidence
)
)
)

for selection_mark in page.selection_marks:
print(
Expand Down