A raster image (photo, logo, scanned picture) extracted from a PDF page, with its zero-based page index, on-page bounding box, and dimensions.

The pixel data is not carried on the struct; instead :ref is a handle to the underlying image, and you encode it on demand with to_binary/2 (bytes) or save/3 (to a file), choosing :png or :jpeg:

{:ok, png} = PdfElixide.Document.Image.to_binary(image)              # PNG bytes
{:ok, jpg} = PdfElixide.Document.Image.to_binary(image, format: :jpeg)
:ok = PdfElixide.Document.Image.save(image, "out.png")              # format inferred
:ok = PdfElixide.Document.Image.save(image, "out.jpg", format: :jpeg)

:format reports how the image was stored in the PDF — :jpeg (a JPEG blob) or :raw (decoded pixels) — which tells you whether a JPEG encode is lossless: for a :jpeg source the original bytes are passed through untouched (except CMYK JPEGs, which must be re-encoded to RGB), while a :raw source is always encoded fresh. The :color_space and :bits_per_component fields describe the image as it was stored.

For the raw stored bytes (rather than an encoded PNG/JPEG), use data/1, which returns {:jpeg, bytes} (the original JPEG blob) or {:raw, bytes, pixel_format} (bare pixels — not a standalone file; pair them with :width, :height, and :color_space, or reach for to_binary/2 when you want an encoded image).

:matrix is the transformation the image was drawn under (matrix/0). For an image the page paints directly, :bbox is that matrix applied to the unit square and squared up to the axes — so for a rotated or skewed image the box is looser than the placement — and :rotation_degrees is the angle the matrix turns through. An image painted inside a Form XObject is the exception, and matrix/0 says how the three disagree there.

data/1, to_binary/2 and save/3 take the handle's lock shared and close/1 takes it exclusively, so encoding one image from several processes runs in parallel; see the Concurrency guide.

Which images are extracted

An image is left out of the list rather than reported as an error when it is under 8 pixels wide or tall, or when its stored encoding cannot be decoded. Flate, LZW, run-length, CCITT fax, JPEG and JPEG 2000 (/JPXDecode) decode; JBIG2 does not, nor does a JPEG 2000 codestream whose component count is anything but 1, 3 or 4. A JPEG 2000 image arrives as :raw pixels whose pixel_format comes from its codestream rather than from the colour space the PDF declares for it.

PdfElixide.Document.images/1 and PdfElixide.Document.images/2 return {:ok, list} either way, so a page whose only picture was skipped is indistinguishable from a page with none — nothing is raised and nothing is logged.

JPEG 2000 transparency is the one case that comes back wrong rather than missing. The alpha channel declared through /SMaskInData is ignored, so a four-component codestream carrying RGB plus alpha is reported as :cmyk, and to_binary/2 and save/3 succeed with wrong colours instead of failing. To spot one, compare :color_space against data/1's pixel_format: a :device_rgb image whose pixels are :cmyk is one. (An :indexed image reports :rgb pixels too, but correctly — its palette really is expanded to RGB.)

A page that cannot be reached, or whose /Resources cannot be resolved, does return {:error, t:PdfElixide.Error.t/0}. A page whose content stream fails to parse does not: it returns {:ok, []}, like a page with no images.