@spec crop_box(t()) ::
  {:ok, PdfElixide.Geometry.Rect.t() | nil} | {:error, PdfElixide.Error.t()}

Returns the page's /CropBox — the region a viewer displays and prints — as a normalized PdfElixide.Geometry.Rect in unrotated user space. It is inherited and reported unclipped, on the same terms as media_box/1.

Returns nil when the box is absent or null. A box whose entry is not an array, or is an array of fewer than four elements, yields %PdfElixide.Error{reason: :invalid_pdf}; as with media_box/1, an element that is not a number is not reported and reads as 0.0.

The box is reported as declared, so it may extend past the sheet. Extraction stops at the two intersected — visible_box/1 — not at this box. See What the crop box hides from extraction for what that frame omits.

@spec crop_box!(t()) :: PdfElixide.Geometry.Rect.t() | nil

Same as crop_box/1 but raises an error if it fails.

@spec has_text_layer(t()) :: {:ok, boolean()} | {:error, PdfElixide.Error.t()}

Returns whether the page carries a text layer, as opposed to being image-only or blank.

This is the signal text/1 cannot give: an empty string means "no text was extracted", which a scanned page and a genuinely blank page produce alike. A false here says the page has nothing to extract, so a caller can route it to OCR instead of treating the empty result as content.

It is a static probe, not an extraction — no text is assembled and no fonts are loaded — and it approximates towards true, so the two answers are not equally strong:

• false is reliable. The page declares no fonts and no form XObjects, or its content stream shows no text and invokes no XObject.
• true is not a promise that text/1 returns anything. A page whose only XObject holds no text still answers true, and so does a page whose content stream cannot be decoded.

One asymmetry is worth knowing: a page with no fonts whose sole XObject is an image answers false. Text drawn in invisible render mode (Tr 3) is not considered either way.

@spec has_text_layer?(t()) :: boolean()

Same as has_text_layer/1 but returns the bare boolean, raising on failure.

Unlike PdfElixide.Document.has_structure_tree?/1 and PdfElixide.Document.has_xfa?/1, this degrades nothing: every error raises, not just a failure of the handle — see the "Errors versus exceptions" section of PdfElixide.Error.

Sweep a document with it:

Enum.reject(doc, &PdfElixide.Document.Page.has_text_layer?/1)

@spec height(t()) :: {:ok, float()} | {:error, PdfElixide.Error.t()}

Returns the page's height in points.

This is media_box/1's :height, in unrotated user space, and like width/1 it is never negative and is not swapped for a rotated page. See rotation/1.

@spec height!(t()) :: float()

Same as height/1 but raises an error if it fails.

@spec inks(t(), PdfElixide.Document.inks_opts()) ::
  {:ok, [String.t()]} | {:error, PdfElixide.Error.t()}

Lists the Separation and DeviceN ink names the page declares.

These are the values :exclude_inks accepts. By default only the page's own /Resources is read; PdfElixide.Document.inks/3 explains what that misses, what :deep costs, and which colorants never appear.

@spec inks!(t(), PdfElixide.Document.inks_opts()) :: [String.t()]

Same as inks/2 but raises an error if it fails.

@spec label(t()) :: {:ok, String.t()} | {:error, PdfElixide.Error.t()}

Returns the page's logical page label (e.g. "i", "1", "A-1").

This is the human-facing page number the PDF may define, independent of the zero-based physical index. Pages outside any declared label range fall back to their decimal page number.

Every call re-reads the document's label ranges, so use PdfElixide.Document.page_labels/1 to label a whole document.

@spec label!(t()) :: String.t()

Same as label/1 but raises an error if it fails.

@spec media_box(t()) ::
  {:ok, PdfElixide.Geometry.Rect.t()} | {:error, PdfElixide.Error.t()}

Returns the page's /MediaBox — the sheet it is imposed on — as a PdfElixide.Geometry.Rect in unrotated user space.

The rect is normalized: :x and :y are the bottom-left corner and :width and :height are non-negative, even for a file that writes the two corners in the reverse order. It is not turned to match rotation/1. See Page boxes and the coordinate origin for inherited boxes, non-zero origins and the coordinate frame.

A page with no /MediaBox anywhere above it, or whose entry is not an array, or is an array of fewer than four elements, is malformed and yields %PdfElixide.Error{reason: :invalid_pdf} — no default page size is substituted. One malformation is not reported: an element that is not a number reads as 0.0, so such a page reports a smaller box rather than failing. See crop_box/1 for the part of the sheet a viewer shows.

@spec media_box!(t()) :: PdfElixide.Geometry.Rect.t()

Same as media_box/1 but raises an error if it fails.

@spec rotation(t()) :: {:ok, rotation()} | {:error, PdfElixide.Error.t()}

Returns the page's /Rotate — the clockwise rotation a viewer applies when displaying it — as 0, 90, 180 or 270.

A page without /Rotate inherits it from the nearest ancestor that declares one and otherwise reads as 0. See Which ancestor an inherited box comes from for the full inheritance behavior.

Two normalizations are worth knowing:

• a value outside 0..359 wraps, so -90 reads as 270;
• a value that is not a multiple of 90 is invalid per §7.7.3.3 and reads as 0 — it is not rounded down, so 45 is 0, not 90.

media_box/1, width/1 and height/1 are not swapped to match. Rotation also affects the frame of some extracted bounding boxes; see Rotated pages and extracted geometry.

@spec rotation!(t()) :: rotation()

Same as rotation/1 but raises an error if it fails.

@spec visible_box(t()) ::
  {:ok, PdfElixide.Geometry.Rect.t()} | {:error, PdfElixide.Error.t()}

Returns the page's visible region — its /CropBox intersected with its /MediaBox — as a normalized PdfElixide.Geometry.Rect in unrotated user space.

Unlike crop_box/1 this always answers a box: the media box stands in whenever the crop box is absent, null, written with fewer than four elements, written with an element that is not a number, or leaves nothing once intersected. Only an unreadable /MediaBox fails, with %PdfElixide.Error{reason: :invalid_pdf}.

This is the frame text extraction stops at — see What the crop box hides from extraction for which extractors it bounds. It is not what render/1,2 draws: on a page with a malformed /CropBox the two part. Measure a raster from the :width and :height of the returned PdfElixide.Document.RenderedPage, and see "What the raster covers" in the Rendering guide.

@spec visible_box!(t()) :: PdfElixide.Geometry.Rect.t()

Same as visible_box/1 but raises an error if it fails.

@spec width(t()) :: {:ok, float()} | {:error, PdfElixide.Error.t()}

Returns the page's width in points.

This is media_box/1's :width, in unrotated user space. Like it, the value is never negative and is not swapped for a rotated page: a page with rotation/1 of 90 or 270 displays as height × width. See rotation/1.

@spec width!(t()) :: float()

Same as width/1 but raises an error if it fails.