Samples for labeled tables (#20840)

* Samples for labeled tables

* too excited renaming

* Update sdk/formrecognizer/Azure.AI.FormRecognizer/README.md

Co-authored-by: Krista Pratico <krpratic@microsoft.com>

* selection mark

Co-authored-by: Krista Pratico <krpratic@microsoft.com>

sdk/formrecognizer/Azure.AI.FormRecognizer/README.md

@@ -246,8 +246,9 @@ Recognize and extract form fields and other content from your custom forms, usin
 ```C# Snippet:FormRecognizerSampleRecognizeCustomFormsFromUri
 string modelId = "<modelId>";
 Uri formUri = <formUri>;
+var options = new RecognizeCustomFormsOptions() { IncludeFieldElements = true };
 
-RecognizeCustomFormsOperation operation = await client.StartRecognizeCustomFormsFromUriAsync(modelId, formUri);
+RecognizeCustomFormsOperation operation = await client.StartRecognizeCustomFormsFromUriAsync(modelId, formUri, options);
 Response<RecognizedFormCollection> operationResponse = await operation.WaitForCompletionAsync();
 RecognizedFormCollection forms = operationResponse.Value;
 
@@ -269,6 +270,33 @@ foreach (RecognizedForm form in forms)
         Console.WriteLine($"  Value: '{field.ValueData.Text}'");
         Console.WriteLine($"  Confidence: '{field.Confidence}'");
     }
+
+    // Iterate over tables, lines, and selection marks on each page
+    foreach (var page in form.Pages)
+    {
+        for (int i = 0; i < page.Tables.Count; i++)
+        {
+            Console.WriteLine($"Table {i + 1} on page {page.Tables[i].PageNumber}");
+            foreach (var cell in page.Tables[i].Cells)
+            {
+                Console.WriteLine($"  Cell[{cell.RowIndex}][{cell.ColumnIndex}] has text '{cell.Text}' with confidence {cell.Confidence}");
+            }
+        }
+        Console.WriteLine($"Lines found on page {page.PageNumber}");
+        foreach (var line in page.Lines)
+        {
+            Console.WriteLine($"  Line {line.Text}");
+        }
+
+        if (page.SelectionMarks.Count != 0)
+        {
+            Console.WriteLine($"Selection marks found on page {page.PageNumber}");
+            foreach (var selectionMark in page.SelectionMarks)
+            {
+                Console.WriteLine($"  Selection mark is '{selectionMark.State}' with confidence {selectionMark.Confidence}");
+            }
+        }
+    }
 }
 ```
 For more information and samples see [here][recognize_custom_forms].

sdk/formrecognizer/Azure.AI.FormRecognizer/samples/README.md

@@ -35,6 +35,7 @@ Azure Cognitive Services Form Recognizer is a cloud service that uses machine le
 - [Strongly-typing a recognized form](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/formrecognizer/Azure.AI.FormRecognizer/samples/Sample4_StronglyTypingARecognizedForm.md)
 - [Create a composed model](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/formrecognizer/Azure.AI.FormRecognizer/samples/Sample8_ModelCompose.md)
 - [Differentiate output models trained with and without labels](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/formrecognizer/Azure.AI.FormRecognizer/tests/samples/Sample10_DifferentiateOutputModelsTrainedWithAndWithoutLabels.cs)
+- [Differentiate output labeled tables](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/formrecognizer/Azure.AI.FormRecognizer/tests/samples/Sample15_DifferentiateOutputLabeledTables.cs)
 - [Copy a custom model between Form Recognizer resources](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/formrecognizer/Azure.AI.FormRecognizer/samples/Sample7_CopyCustomModel.md)
 - [Create composed model from a collection of models trained with labels](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/formrecognizer/Azure.AI.FormRecognizer/samples/Sample8_ModelCompose.md)
 - [Field Bounding Box](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/formrecognizer/Azure.AI.FormRecognizer/tests/samples/Sample9_FieldBoundingBox.cs)

sdk/formrecognizer/Azure.AI.FormRecognizer/samples/Sample2_RecognizeCustomForms.md

@@ -24,8 +24,9 @@ To recognize form fields and other content from your custom forms from a given f
 ```C# Snippet:FormRecognizerSampleRecognizeCustomFormsFromUri
 string modelId = "<modelId>";
 Uri formUri = <formUri>;
+var options = new RecognizeCustomFormsOptions() { IncludeFieldElements = true };
 
-RecognizeCustomFormsOperation operation = await client.StartRecognizeCustomFormsFromUriAsync(modelId, formUri);
+RecognizeCustomFormsOperation operation = await client.StartRecognizeCustomFormsFromUriAsync(modelId, formUri, options);
 Response<RecognizedFormCollection> operationResponse = await operation.WaitForCompletionAsync();
 RecognizedFormCollection forms = operationResponse.Value;
 
@@ -47,6 +48,33 @@ foreach (RecognizedForm form in forms)
         Console.WriteLine($"  Value: '{field.ValueData.Text}'");
         Console.WriteLine($"  Confidence: '{field.Confidence}'");
     }
+
+    // Iterate over tables, lines, and selection marks on each page
+    foreach (var page in form.Pages)
+    {
+        for (int i = 0; i < page.Tables.Count; i++)
+        {
+            Console.WriteLine($"Table {i + 1} on page {page.Tables[i].PageNumber}");
+            foreach (var cell in page.Tables[i].Cells)
+            {
+                Console.WriteLine($"  Cell[{cell.RowIndex}][{cell.ColumnIndex}] has text '{cell.Text}' with confidence {cell.Confidence}");
+            }
+        }
+        Console.WriteLine($"Lines found on page {page.PageNumber}");
+        foreach (var line in page.Lines)
+        {
+            Console.WriteLine($"  Line {line.Text}");
+        }
+
+        if (page.SelectionMarks.Count != 0)
+        {
+            Console.WriteLine($"Selection marks found on page {page.PageNumber}");
+            foreach (var selectionMark in page.SelectionMarks)
+            {
+                Console.WriteLine($"  Selection mark is '{selectionMark.State}' with confidence {selectionMark.Confidence}");
+            }
+        }
+    }
 }
 ```
 
@@ -59,8 +87,9 @@ string modelId = "<modelId>";
 string filePath = "<filePath>";
 
 using var stream = new FileStream(filePath, FileMode.Open);
+var options = new RecognizeCustomFormsOptions() { IncludeFieldElements = true };
 
-RecognizeCustomFormsOperation operation = await client.StartRecognizeCustomFormsAsync(modelId, stream);
+RecognizeCustomFormsOperation operation = await client.StartRecognizeCustomFormsAsync(modelId, stream, options);
 Response<RecognizedFormCollection> operationResponse = await operation.WaitForCompletionAsync();
 RecognizedFormCollection forms = operationResponse.Value;
 
@@ -80,6 +109,33 @@ foreach (RecognizedForm form in forms)
         Console.WriteLine($"  Value: '{field.ValueData.Text}'");
         Console.WriteLine($"  Confidence: '{field.Confidence}'");
     }
+
+    // Iterate over tables, lines, and selection marks on each page
+    foreach (var page in form.Pages)
+    {
+        for (int i = 0; i < page.Tables.Count; i++)
+        {
+            Console.WriteLine($"Table {i+1} on page {page.Tables[i].PageNumber}");
+            foreach (var cell in page.Tables[i].Cells)
+            {
+                Console.WriteLine($"  Cell[{cell.RowIndex}][{cell.ColumnIndex}] has text '{cell.Text}' with confidence {cell.Confidence}");
+            }
+        }
+        Console.WriteLine($"Lines found on page {page.PageNumber}");
+        foreach (var line in page.Lines)
+        {
+            Console.WriteLine($"  Line {line.Text}");
+        }
+
+        if (page.SelectionMarks.Count != 0)
+        {
+            Console.WriteLine($"Selection marks found on page {page.PageNumber}");
+            foreach (var selectionMark in page.SelectionMarks)
+            {
+                Console.WriteLine($"  Selection mark is '{selectionMark.State}' with confidence {selectionMark.Confidence}");
+            }
+        }
+    }
 }
 ```
 

sdk/formrecognizer/Azure.AI.FormRecognizer/src/RecognizedForm.cs

@@ -7,7 +7,10 @@
 namespace Azure.AI.FormRecognizer.Models
 {
     /// <summary>
-    /// Represents a form that has been recognized by a trained model.
+    /// Represents a form that has been recognized by a trained or prebuilt model.
+    /// The <see cref="Fields"/> property contains the form fields that were extracted from the
+    /// form. Tables, text lines/words, and selection marks are extracted per page and found in the
+    /// <see cref="Pages"/> property.
     /// </summary>
     public class RecognizedForm
     {

sdk/formrecognizer/Azure.AI.FormRecognizer/tests/FormRecognizerClient/RecognizeCustomFormsLiveTests.cs

@@ -660,14 +660,14 @@ public async Task StartRecognizeCustomFormsWithMultiplePageArgument(string page1
 
         [RecordedTest]
         [ServiceVersion(Min = FormRecognizerClientOptions.ServiceVersion.V2_1_Preview_3)]
-        public async Task StartRecognizeCustomFormsWithTableVariableRows()
+        public async Task StartRecognizeCustomFormsWithTableDynamicRows()
         {
             var client = CreateFormRecognizerClient();
             RecognizeCustomFormsOperation operation;
 
             await using var trainedModel = await CreateDisposableTrainedModelAsync(useTrainingLabels: true, ContainerType.TableVariableRows);
 
-            using var stream = FormRecognizerTestEnvironment.CreateStream(TestFile.FormTableVariableRows);
+            using var stream = FormRecognizerTestEnvironment.CreateStream(TestFile.FormTableDynamicRows);
             using (Recording.DisableRequestBodyRecording())
             {
                 operation = await client.StartRecognizeCustomFormsAsync(trainedModel.ModelId, stream);

sdk/formrecognizer/Azure.AI.FormRecognizer/tests/Infrastructure/FormRecognizerLiveTestBase.cs

@@ -122,7 +122,7 @@ protected async Task<DisposableTrainedModel> CreateDisposableTrainedModelAsync(b
                 ContainerType.Singleforms => TestEnvironment.BlobContainerSasUrl,
                 ContainerType.MultipageFiles => TestEnvironment.MultipageBlobContainerSasUrl,
                 ContainerType.SelectionMarks => TestEnvironment.SelectionMarkBlobContainerSasUrl,
-                ContainerType.TableVariableRows => TestEnvironment.TableVariableRowsContainerSasUrl,
+                ContainerType.TableVariableRows => TestEnvironment.TableDynamicRowsContainerSasUrl,
                 ContainerType.TableFixedRows => TestEnvironment.TableFixedRowsContainerSasUrl,
                 _ => TestEnvironment.BlobContainerSasUrl,
             };

sdk/formrecognizer/Azure.AI.FormRecognizer/tests/Infrastructure/FormRecognizerTestEnvironment.cs

@@ -32,8 +32,8 @@ public FormRecognizerTestEnvironment()
         /// <summary>The name of the environment variable for the Blob Container SAS URL to use for storing documents that have selection marks used for live tests.</summary>
         internal const string SelectionMarkBlobContainerSasUrlEnvironmentVariableName = "FORM_RECOGNIZER_SELECTION_MARK_BLOB_CONTAINER_SAS_URL";
 
-        /// <summary>The name of the environment variable for the Blob Container SAS URL to use for storing documents that have tables with variable rows used for live tests.</summary>
-        internal const string TableVariableRowsBlobContainerSasUrlEnvironmentVariableName = "FORM_RECOGNIZER_TABLE_VARIABLE_ROWS_BLOB_CONTAINER_SAS_URL";
+        /// <summary>The name of the environment variable for the Blob Container SAS URL to use for storing documents that have tables with dynamic rows used for live tests.</summary>
+        internal const string TableDynamicRowsBlobContainerSasUrlEnvironmentVariableName = "FORM_RECOGNIZER_TABLE_VARIABLE_ROWS_BLOB_CONTAINER_SAS_URL";
 
         /// <summary>The name of the environment variable for the Blob Container SAS URL to use for storing documents that have tables with fixed rows used for live tests.</summary>
         internal const string TableFixedRowsBlobContainerSasUrlEnvironmentVariableName = "FORM_RECOGNIZER_TABLE_FIXED_ROWS_BLOB_CONTAINER_SAS_URL";
@@ -55,7 +55,7 @@ public FormRecognizerTestEnvironment()
         public string BlobContainerSasUrl => GetRecordedVariable(BlobContainerSasUrlEnvironmentVariableName, options => options.IsSecret("https://sanitized.blob.core.windows.net"));
         public string SelectionMarkBlobContainerSasUrl => GetRecordedVariable(SelectionMarkBlobContainerSasUrlEnvironmentVariableName, options => options.IsSecret("https://sanitized.blob.core.windows.net"));
         public string MultipageBlobContainerSasUrl => GetRecordedVariable(MultipageBlobContainerSasUrlEnvironmentVariableName, options => options.IsSecret("https://sanitized.blob.core.windows.net"));
-        public string TableVariableRowsContainerSasUrl => GetRecordedVariable(TableVariableRowsBlobContainerSasUrlEnvironmentVariableName, options => options.IsSecret("https://sanitized.blob.core.windows.net"));
+        public string TableDynamicRowsContainerSasUrl => GetRecordedVariable(TableDynamicRowsBlobContainerSasUrlEnvironmentVariableName, options => options.IsSecret("https://sanitized.blob.core.windows.net"));
         public string TableFixedRowsContainerSasUrl => GetRecordedVariable(TableFixedRowsBlobContainerSasUrlEnvironmentVariableName, options => options.IsSecret("https://sanitized.blob.core.windows.net"));
         public string TargetResourceId => GetRecordedVariable(TargetResourceIdEnvironmentVariableName);
         public string TargetResourceRegion => GetRecordedVariable(TargetResourceRegionEnvironmentVariableName);

sdk/formrecognizer/Azure.AI.FormRecognizer/tests/Infrastructure/TestFile.cs

@@ -55,8 +55,8 @@ public static class TestFile
         /// <summary>A three-page invoice file in which the second page is blank.</summary>
         public const string InvoiceMultipageBlank = "multipage_invoice1.pdf";
 
-        /// <summary>A form with a table that has variable rows and empty cells.</summary>
-        public const string FormTableVariableRows = "label_table_variable_rows1.pdf";
+        /// <summary>A form with a table that has dynamic rows and empty cells.</summary>
+        public const string FormTableDynamicRows = "label_table_dynamic_rows1.pdf";
 
         /// <summary>A form with a table that has fixed rows and empty cells.</summary>
         public const string FormTableFixedRows = "label_table_fixed_rows1.pdf";