[FormRecognizer] Implemented page range selection feature for prebuilt and custom models (Azure#19906)

Author: kinelski

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

@@ -4,6 +4,7 @@
 
 ### New Features
 - Expanded the set of document languages that can be provided to the `StartRecognizeContent` API.
+- Added property `Pages` to `RecognizeBusinessCardsOptions`, `RecognizeCustomFormsOptions`, `RecognizeInvoicesOptions`, and `RecognizeReceiptsOptions` to specify the page numbers to recognize.
 
 ### Breaking changes
 - The client defaults to the latest supported service version, which currently is `2.1-preview.3`.

sdk/formrecognizer/Azure.AI.FormRecognizer/api/Azure.AI.FormRecognizer.netstandard2.0.cs

@@ -174,6 +174,7 @@ public RecognizeBusinessCardsOptions() { }
         public Azure.AI.FormRecognizer.FormContentType? ContentType { get { throw null; } set { } }
         public bool IncludeFieldElements { get { throw null; } set { } }
         public Azure.AI.FormRecognizer.FormRecognizerLocale? Locale { get { throw null; } set { } }
+        public System.Collections.Generic.IList<string> Pages { get { throw null; } }
     }
     public partial class RecognizeContentOptions
     {
@@ -187,20 +188,23 @@ public partial class RecognizeCustomFormsOptions
         public RecognizeCustomFormsOptions() { }
         public Azure.AI.FormRecognizer.FormContentType? ContentType { get { throw null; } set { } }
         public bool IncludeFieldElements { get { throw null; } set { } }
+        public System.Collections.Generic.IList<string> Pages { get { throw null; } }
     }
     public partial class RecognizeInvoicesOptions
     {
         public RecognizeInvoicesOptions() { }
         public Azure.AI.FormRecognizer.FormContentType? ContentType { get { throw null; } set { } }
         public bool IncludeFieldElements { get { throw null; } set { } }
         public Azure.AI.FormRecognizer.FormRecognizerLocale? Locale { get { throw null; } set { } }
+        public System.Collections.Generic.IList<string> Pages { get { throw null; } }
     }
     public partial class RecognizeReceiptsOptions
     {
         public RecognizeReceiptsOptions() { }
         public Azure.AI.FormRecognizer.FormContentType? ContentType { get { throw null; } set { } }
         public bool IncludeFieldElements { get { throw null; } set { } }
         public Azure.AI.FormRecognizer.FormRecognizerLocale? Locale { get { throw null; } set { } }
+        public System.Collections.Generic.IList<string> Pages { get { throw null; } }
     }
 }
 namespace Azure.AI.FormRecognizer.Models

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

@@ -303,7 +303,7 @@ public virtual async Task<RecognizeReceiptsOperation> StartRecognizeReceiptsAsyn
                     formContentType,
                     recognizeReceiptsOptions.IncludeFieldElements,
                     recognizeReceiptsOptions.Locale,
-                    null, // TODO: pass pages.
+                    recognizeReceiptsOptions.Pages.Count == 0 ? null : recognizeReceiptsOptions.Pages,
                     receipt,
                     cancellationToken).ConfigureAwait(false);
                 string location = ClientCommon.GetResponseHeader(response.Headers, Constants.OperationLocationHeader);
@@ -344,7 +344,7 @@ public virtual RecognizeReceiptsOperation StartRecognizeReceipts(Stream receipt,
                     formContentType,
                     recognizeReceiptsOptions.IncludeFieldElements,
                     recognizeReceiptsOptions.Locale,
-                    null, // TODO: pass pages.
+                    recognizeReceiptsOptions.Pages.Count == 0 ? null : recognizeReceiptsOptions.Pages,
                     receipt,
                     cancellationToken);
                 string location = ClientCommon.GetResponseHeader(response.Headers, Constants.OperationLocationHeader);
@@ -383,7 +383,7 @@ public virtual async Task<RecognizeReceiptsOperation> StartRecognizeReceiptsFrom
                 Response response = await ServiceClient.AnalyzeReceiptAsyncAsync(
                     recognizeReceiptsOptions.IncludeFieldElements,
                     recognizeReceiptsOptions.Locale,
-                    null, // TODO: pass pages.
+                    recognizeReceiptsOptions.Pages.Count == 0 ? null : recognizeReceiptsOptions.Pages,
                     sourcePath,
                     cancellationToken).ConfigureAwait(false);
                 string location = ClientCommon.GetResponseHeader(response.Headers, Constants.OperationLocationHeader);
@@ -422,7 +422,7 @@ public virtual RecognizeReceiptsOperation StartRecognizeReceiptsFromUri(Uri rece
                 Response response = ServiceClient.AnalyzeReceiptAsync(
                     recognizeReceiptsOptions.IncludeFieldElements,
                     recognizeReceiptsOptions.Locale,
-                    null, // TODO: pass pages.
+                    recognizeReceiptsOptions.Pages.Count == 0 ? null : recognizeReceiptsOptions.Pages,
                     sourcePath,
                     cancellationToken);
                 string location = ClientCommon.GetResponseHeader(response.Headers, Constants.OperationLocationHeader);
@@ -467,7 +467,7 @@ public virtual async Task<RecognizeBusinessCardsOperation> StartRecognizeBusines
                     formContentType,
                     recognizeBusinessCardsOptions.IncludeFieldElements,
                     recognizeBusinessCardsOptions.Locale,
-                    null, // TODO: pass pages.
+                    recognizeBusinessCardsOptions.Pages.Count == 0 ? null : recognizeBusinessCardsOptions.Pages,
                     businessCard,
                     cancellationToken).ConfigureAwait(false);
                 string location = ClientCommon.GetResponseHeader(response.Headers, Constants.OperationLocationHeader);
@@ -508,7 +508,7 @@ public virtual RecognizeBusinessCardsOperation StartRecognizeBusinessCards(Strea
                     formContentType,
                     recognizeBusinessCardsOptions.IncludeFieldElements,
                     recognizeBusinessCardsOptions.Locale,
-                    null, // TODO: pass pages.
+                    recognizeBusinessCardsOptions.Pages.Count == 0 ? null : recognizeBusinessCardsOptions.Pages,
                     businessCard,
                     cancellationToken);
                 string location = ClientCommon.GetResponseHeader(response.Headers, Constants.OperationLocationHeader);
@@ -547,7 +547,7 @@ public virtual async Task<RecognizeBusinessCardsOperation> StartRecognizeBusines
                 Response response = await ServiceClient.AnalyzeBusinessCardAsyncAsync(
                     recognizeBusinessCardsOptions.IncludeFieldElements,
                     recognizeBusinessCardsOptions.Locale,
-                    null, // TODO: pass pages.
+                    recognizeBusinessCardsOptions.Pages.Count == 0 ? null : recognizeBusinessCardsOptions.Pages,
                     sourcePath,
                     cancellationToken).ConfigureAwait(false);
                 string location = ClientCommon.GetResponseHeader(response.Headers, Constants.OperationLocationHeader);
@@ -586,7 +586,7 @@ public virtual RecognizeBusinessCardsOperation StartRecognizeBusinessCardsFromUr
                 Response response = ServiceClient.AnalyzeBusinessCardAsync(
                     recognizeBusinessCardsOptions.IncludeFieldElements,
                     recognizeBusinessCardsOptions.Locale,
-                    null, // TODO: pass pages.
+                    recognizeBusinessCardsOptions.Pages.Count == 0 ? null : recognizeBusinessCardsOptions.Pages,
                     sourcePath,
                     cancellationToken);
                 string location = ClientCommon.GetResponseHeader(response.Headers, Constants.OperationLocationHeader);
@@ -631,7 +631,7 @@ public virtual async Task<RecognizeInvoicesOperation> StartRecognizeInvoicesAsyn
                     formContentType,
                     recognizeInvoicesOptions.IncludeFieldElements,
                     recognizeInvoicesOptions.Locale,
-                    null, // TODO: pass pages.
+                    recognizeInvoicesOptions.Pages.Count == 0 ? null : recognizeInvoicesOptions.Pages,
                     invoice,
                     cancellationToken).ConfigureAwait(false);
                 string location = ClientCommon.GetResponseHeader(response.Headers, Constants.OperationLocationHeader);
@@ -672,7 +672,7 @@ public virtual RecognizeInvoicesOperation StartRecognizeInvoices(Stream invoice,
                     formContentType,
                     recognizeInvoicesOptions.IncludeFieldElements,
                     recognizeInvoicesOptions.Locale,
-                    null, // TODO: pass pages.
+                    recognizeInvoicesOptions.Pages.Count == 0 ? null : recognizeInvoicesOptions.Pages,
                     invoice,
                     cancellationToken);
                 string location = ClientCommon.GetResponseHeader(response.Headers, Constants.OperationLocationHeader);
@@ -711,7 +711,7 @@ public virtual async Task<RecognizeInvoicesOperation> StartRecognizeInvoicesFrom
                 Response response = await ServiceClient.AnalyzeInvoiceAsyncAsync(
                     recognizeInvoicesOptions.IncludeFieldElements,
                     recognizeInvoicesOptions.Locale,
-                    null, // TODO: pass pages.
+                    recognizeInvoicesOptions.Pages.Count == 0 ? null : recognizeInvoicesOptions.Pages,
                     sourcePath,
                     cancellationToken).ConfigureAwait(false);
                 string location = ClientCommon.GetResponseHeader(response.Headers, Constants.OperationLocationHeader);
@@ -750,7 +750,7 @@ public virtual RecognizeInvoicesOperation StartRecognizeInvoicesFromUri(Uri invo
                 Response response = ServiceClient.AnalyzeInvoiceAsync(
                     recognizeInvoicesOptions.IncludeFieldElements,
                     recognizeInvoicesOptions.Locale,
-                    null, // TODO: pass pages.
+                    recognizeInvoicesOptions.Pages.Count == 0 ? null : recognizeInvoicesOptions.Pages,
                     sourcePath,
                     cancellationToken);
                 string location = ClientCommon.GetResponseHeader(response.Headers, Constants.OperationLocationHeader);
@@ -796,7 +796,7 @@ public virtual RecognizeCustomFormsOperation StartRecognizeCustomForms(string mo
                     guid,
                     formContentType,
                     includeTextDetails: recognizeCustomFormsOptions.IncludeFieldElements,
-                    null, // TODO: pass pages.
+                    recognizeCustomFormsOptions.Pages.Count == 0 ? null : recognizeCustomFormsOptions.Pages,
                     form,
                     cancellationToken);
                 string location = ClientCommon.GetResponseHeader(response.Headers, Constants.OperationLocationHeader);
@@ -838,7 +838,7 @@ public virtual RecognizeCustomFormsOperation StartRecognizeCustomFormsFromUri(st
                 Response response = ServiceClient.AnalyzeWithCustomModel(
                     guid,
                     includeTextDetails: recognizeCustomFormsOptions.IncludeFieldElements,
-                    null, // TODO: pass pages.
+                    recognizeCustomFormsOptions.Pages.Count == 0 ? null : recognizeCustomFormsOptions.Pages,
                     sourcePath,
                     cancellationToken);
                 string location = ClientCommon.GetResponseHeader(response.Headers, Constants.OperationLocationHeader);
@@ -881,7 +881,7 @@ public virtual async Task<RecognizeCustomFormsOperation> StartRecognizeCustomFor
                     guid,
                     formContentType,
                     includeTextDetails: recognizeCustomFormsOptions.IncludeFieldElements,
-                    null, // TODO: pass pages.
+                    recognizeCustomFormsOptions.Pages.Count == 0 ? null : recognizeCustomFormsOptions.Pages,
                     form,
                     cancellationToken).ConfigureAwait(false);
                 string location = ClientCommon.GetResponseHeader(response.Headers, Constants.OperationLocationHeader);
@@ -923,7 +923,7 @@ public virtual async Task<RecognizeCustomFormsOperation> StartRecognizeCustomFor
                 Response response = await ServiceClient.AnalyzeWithCustomModelAsync(
                     guid,
                     includeTextDetails: recognizeCustomFormsOptions.IncludeFieldElements,
-                    null, // TODO: pass pages.
+                    recognizeCustomFormsOptions.Pages.Count == 0 ? null : recognizeCustomFormsOptions.Pages,
                     sourcePath,
                     cancellationToken).ConfigureAwait(false);
                 string location = ClientCommon.GetResponseHeader(response.Headers, Constants.OperationLocationHeader);

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

@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+using System.Collections.Generic;
+
 namespace Azure.AI.FormRecognizer
 {
     /// <summary>
@@ -37,5 +39,18 @@ public RecognizeBusinessCardsOptions()
         /// Supported locales include: en-AU, en-CA, en-GB, en-IN, en-US.
         /// </summary>
         public FormRecognizerLocale? Locale { get; set; }
+
+        /// <summary>
+        /// <para>
+        /// Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers
+        /// and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like
+        /// `Pages = { "1-3", "5-6" }`. Separate each page number or range with a comma.
+        /// </para>
+        /// <para>
+        /// Although this collection cannot be set, it can be modified.
+        /// See <a href="https://docs.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/object-and-collection-initializers#collection-initializers">collection initializer</a>.
+        /// </para>
+        /// </summary>
+        public IList<string> Pages { get; } = new List<string>();
     }
 }

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

@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+using System.Collections.Generic;
+
 namespace Azure.AI.FormRecognizer
 {
     /// <summary>
@@ -31,5 +33,18 @@ public RecognizeCustomFormsOptions()
         /// content type detection.
         /// </summary>
         public FormContentType? ContentType { get; set; }
+
+        /// <summary>
+        /// <para>
+        /// Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers
+        /// and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like
+        /// `Pages = { "1-3", "5-6" }`. Separate each page number or range with a comma.
+        /// </para>
+        /// <para>
+        /// Although this collection cannot be set, it can be modified.
+        /// See <a href="https://docs.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/object-and-collection-initializers#collection-initializers">collection initializer</a>.
+        /// </para>
+        /// </summary>
+        public IList<string> Pages { get; } = new List<string>();
     }
 }

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

@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+using System.Collections.Generic;
+
 namespace Azure.AI.FormRecognizer
 {
     /// <summary>
@@ -37,5 +39,18 @@ public RecognizeInvoicesOptions()
         /// Supported locales include: en-US.
         /// </summary>
         public FormRecognizerLocale? Locale { get; set; }
+
+        /// <summary>
+        /// <para>
+        /// Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers
+        /// and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like
+        /// `Pages = { "1-3", "5-6" }`. Separate each page number or range with a comma.
+        /// </para>
+        /// <para>
+        /// Although this collection cannot be set, it can be modified.
+        /// See <a href="https://docs.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/object-and-collection-initializers#collection-initializers">collection initializer</a>.
+        /// </para>
+        /// </summary>
+        public IList<string> Pages { get; } = new List<string>();
     }
 }

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

@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+using System.Collections.Generic;
+
 namespace Azure.AI.FormRecognizer
 {
     /// <summary>
@@ -37,5 +39,18 @@ public RecognizeReceiptsOptions()
         /// Supported locales include: en-AU, en-CA, en-GB, en-IN, en-US.
         /// </summary>
         public FormRecognizerLocale? Locale { get; set; }
+
+        /// <summary>
+        /// <para>
+        /// Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers
+        /// and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like
+        /// `Pages = { "1-3", "5-6" }`. Separate each page number or range with a comma.
+        /// </para>
+        /// <para>
+        /// Although this collection cannot be set, it can be modified.
+        /// See <a href="https://docs.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/object-and-collection-initializers#collection-initializers">collection initializer</a>.
+        /// </para>
+        /// </summary>
+        public IList<string> Pages { get; } = new List<string>();
     }
 }