[formrecognizer] add design for specifying page range

[kristapratico]

currently exposing generated code.

Also showcase feature in samples.

[kristapratico]

Decision: Expose pages as a list of string (how it is currently exposed in the SDK, no changes necessary)

Reasoning:

Here are my thoughts on the pages option.

Keep in mind that for this Feb release, it will only be supported on content/layout. But once preview.3 of the service is deployed, it will be supported on all prebuilts and custom models.

Design

I'm siding on not over-complicating this. The service accepts/ will accept many varieties of valid inputs:

I do think the easiest way for a user to input pages would be to have this exposed as a list of string or language-specific equivalent. I find this more intuitive, it kind of feels like i'm selecting the pages to print in a printer menu. If we tried to expose this as an object of some sort, I think there will be too many options and it will just be confusing. e.g. first page, last page, all pages up to k, all pages starting from k, only pages 3, 5, 8, specifying two ranges, etc etc. I also checked to see if any other track 2 libraries had a "pages" option that had been designed already but couldn't find anything (aside from page blobs).

Naming

The two options I've been going back and forth on are to keep it as pages or rename to page_range. Here's my pro/cons list:

pages

pros: matches the REST API parameter, so error messages will make sense when they say "pages parameter invalid". Is consistent with what's returned in the RecognizedForm pages property.

cons: not totally clear (to me) that its used to specify a page range

page_range

pros: possibly more clear about what the parameter is doing.

cons: will not match the values found in a RecognizedForm page_range.

This -> "will not match the values found in a RecognizedForm page_range"

is kind of deal breaker for me on the page_range name. The page range property will not change if only certain pages are selected. page range will continue to be defined as the first and last page of the document, even if the results/fields returned will only be from the selected pages.

Because I was confused at first, I tried to draw this out for each endpoint. Here's what it will look like when it is supported for all endpoints:

---

For a document with 4 pages and an input of pages=["1-2", 4] these would be the results:

Content:

[FormPage(page_number=1), FormPage(page_number=2), FormPage(page_number=4)]

Receipt/business card:

[RecognizedForm(page_range=[1,1]), RecognizedForm(page_range=[2,2]), RecognizedForm(page_range=[4,4])],

each will contain a pages property of length==1 that has the FormPage for its given page number

Invoice:

[RecognizedForm(page_range=[1,4])], the pages property will look like content

Supervised:

[RecognizedForm(page_range=[1,4])], the pages property will look like content

Unsupervised:

[RecognizedForm(page_range=[1,1]), RecognizedForm(page_range=[2,2]), RecognizedForm(page_range=[4,4]))]

each will contain a pages property of length==1 that has the FormPage for its given page number

---