@spec image_data(ExPdfium.Document.t(), non_neg_integer(), non_neg_integer()) ::
  {:ok, ExPdfium.Bitmap.t()} | {:error, atom()}

Decode the image object at object_index (see page_objects/2 / images/2) to a pixel bitmap.

Returns {:ok, %ExPdfium.Bitmap{}}. Unlike render_page/3 (always 4-channel), an extracted image keeps its native channel order — format is :gray (1 channel), :bgr (3), or :bgrx / :bgra (4) — so check it before handing data to an image library.

These are the image's raw stored samples: image masks (soft/stencil) and object transforms are not applied, so a masked image comes back without its transparency, and the bitmap size may differ from images/2's reported dimensions. For the composited, as-displayed result, render the page with render_page/3 instead.

Errors: :object_not_found (no object at that index), :not_an_image (the object isn't an image), :image_too_large (the image's declared pixel count exceeds a safety cap, so it isn't decoded), :page_out_of_bounds, :image_failed.

@spec image_raw_data(ExPdfium.Document.t(), non_neg_integer(), non_neg_integer()) ::
  {:ok, binary()} | {:error, atom()}

Return the original, still-encoded stream of the image object at object_index.

This is the image exactly as stored, with its PDF filters not applied: for a "DCTDecode" image the bytes are a ready-to-write JPEG; for "FlateDecode" they are zlib-compressed samples, not a standalone image file. Check filters from images/2 to know which. For always-decodable pixels, use image_data/3.

Errors: :object_not_found, :not_an_image, :page_out_of_bounds, :image_failed.

@spec images(ExPdfium.Document.t(), non_neg_integer()) ::
  {:ok, [map()]} | {:error, atom()}

List the image objects on a 0-indexed page, with how each is stored.

Each is:

%{
  index: non_neg_integer(),         # object index, for image_data/3
  width: non_neg_integer(),         # intrinsic image width, in pixels
  height: non_neg_integer(),        # intrinsic image height, in pixels
  bits_per_pixel: non_neg_integer(),
  filters: [String.t()],            # PDF stream filters, e.g. ["DCTDecode"]
  bounds: t:bounds/0 | nil,         # where it sits on the page, in points
  matrix: t:matrix/0 | nil          # placement transform (scale/rotation/flip)
}

width/height are pdfium's reported pixel dimensions (a 0 means pdfium couldn't read it), and index is valid only until the document is mutated.

Use image_data/3 to get decoded pixels, or image_raw_data/3 for the original encoded bytes — filters tells you the encoding (a "DCTDecode" raw stream is a ready JPEG; "FlateDecode" is zlib-compressed samples, not a standalone file).

matrix is the image's placement transform (see matrix/0). Because it maps the unit square onto the page, a caller can recover the transform baked into the image object — scale, plus any object-level rotation or flip — without re-rendering.

@spec object_display_matrix(
  ExPdfium.Document.t(),
  non_neg_integer(),
  non_neg_integer()
) ::
  {:ok, matrix()} | {:error, atom()}

The composed content→display transformation matrix for a 0-indexed object on a 0-indexed page.

page_objects/2 and images/2 give an object's :matrix in the page's unrotated content space. This composes that matrix with the page-level /Rotate (from page_info/2), returning the single matrix/0 that maps the object's own space straight to display coordinates (origin bottom-left of the page as shown, y up). object_index is the same index page_objects/2 / images/2 report.

That is exactly the transform needed to orient an extracted image as it appears on the page — e.g. to turn a native-resolution image_raw_data/3 JPEG the right way up for OCR — composing the object's own scale/rotation/flip with the page rotation, without re-rendering.

This library deliberately does not rotate pixels for you (that is image processing best left to your image pipeline); it hands you the transform as data. Apply it in Vix/Image, or read the rotation off it to pass an orientation hint to your OCR engine.

Returns {:error, :object_not_found} if there is no such object, or {:error, :no_matrix} if pdfium could not report the object's matrix.

@spec object_display_rotation(
  ExPdfium.Document.t(),
  non_neg_integer(),
  non_neg_integer()
) ::
  {:ok, float()} | {:error, atom()}

The clockwise rotation, in degrees, to apply to an extracted image in a top-left-origin raster library (Vix/libvips, Pillow, ImageMagick) so it appears upright, as the page displays it.

This is the raster-convention companion to object_display_matrix/3. That matrix is in PDF space (origin bottom-left, y up); raster libraries put the origin top-left with y increasing downward, which inverts the rotation sense. So an angle read straight off the PDF matrix (atan2(b, a)) and handed to a raster library comes out 180° wrong on 90°/270° pages — and, because it cancels at 0°/180°, passes casual testing on unrotated documents. This function returns the already-converted clockwise angle, normalized to [0, 360).

{:ok, raw} = ExPdfium.image_raw_data(doc, 0, 0)
{:ok, deg} = ExPdfium.object_display_rotation(doc, 0, 0)
{:ok, img} = Image.from_binary(raw)
{:ok, upright} = Image.rotate(img, deg)   # Vips is clockwise; upright as on the page

For a plain scanned page — a single full-page image, rotated only by the page /Rotate — this equals page_info/2's :rotation. It captures rotation only: any flip or skew carried in the object matrix is not reducible to an angle, so use object_display_matrix/3 for the full transform in that case.

Returns {:error, :object_not_found} or {:error, :no_matrix} exactly as object_display_matrix/3 does.

@spec page_objects(ExPdfium.Document.t(), non_neg_integer()) ::
  {:ok, [map()]} | {:error, atom()}

List every object on a 0-indexed page, in page order.

Each object is %{index: non_neg_integer(), type: atom(), bounds: t:bounds/0 | nil, matrix: t:matrix/0 | nil}, where type is one of :text, :path, :image, :shading, :form (an XObject form), or :unsupported. index is the object's position in the page's object list — pass it to image_data/3 / image_raw_data/3. It is valid only until the document is mutated (a write op can shift object indices).

matrix is the object's transformation matrix (see matrix/0); it is nil only if pdfium cannot report it.