# `PdfElixide.Document.StructuredPage.Region`
[🔗](https://github.com/r8/pdf_elixide/blob/v0.23.0/lib/pdf_elixide/document/structured_page/region.ex#L1)

A group of spans sharing one role on a structured page, with their joined
text and union bounding box.

`t:kind/0` lists the roles. Spans are grouped by role, column and section.
Body text and marginal labels can have columns: `0` for left and `1` for
right, each read top to bottom.

Gaps, blank lines and indents do not split regions, so consecutive body
paragraphs can merge. Labels in the same column can also merge across
intervening body text. To read paragraphs, use
`PdfElixide.Document.to_plain_text/2`, or split `spans` at wider gaps between
their boxes.

Regions follow their first spans in top-to-bottom, then left-to-right order.
A right column starting higher appears before the left column; group or sort
by `column` when you need left-column-then-right reading order.

`bbox` is the union of the spans' boxes in the page's raw, unrotated user
space, like `PdfElixide.Document.spans/2` — see [Rotated pages and extracted
geometry](guides/page-geometry.md#rotated-pages-and-extracted-geometry).
`section` is set only on a tagged page, from the nearest `/Sect`, `/Art` or
`/Part` structure element, and is stable across pages so a chapter continuing
onto the next page keeps one value.

# `kind`

```elixir
@type kind() ::
  :body
  | :marginal_label
  | :header
  | :footer
  | :page_number
  | :artifact
  | {:heading, 1..6}
```

The role of a region.

  * `:body` — ordinary text, including any margin text the document does not
    mark as an artifact.
  * `:marginal_label` — a short standalone numeral such as a verse or section
    number: either text of at most four digits or lowercase roman letters, or
    content a tagged PDF marks `/Lbl`.
  * `:header`, `:footer`, `:page_number`, `:artifact` — content the document
    marks as an `/Artifact` with `/Type /Pagination` and a `/Subtype` of
    `/Header`, `/Footer` or `/PageNumber`; any other artifact is
    `:artifact`. These roles come from that marking alone: a running header
    that merely sits at the top of the page is `:body`.
  * `{:heading, level}` — a tagged `/H1` to `/H6` heading, levels 1 to 6.
    This library does not produce it: such a heading arrives as `:body`.

# `t`

```elixir
@type t() :: %PdfElixide.Document.StructuredPage.Region{
  bbox: PdfElixide.Geometry.Rect.t(),
  column: non_neg_integer() | nil,
  kind: kind(),
  page: non_neg_integer(),
  section: non_neg_integer() | nil,
  spans: [PdfElixide.Document.Span.t()],
  text: String.t()
}
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*