extractImages method

Extracts all image objects from one or all pages of the document.

When pageIndex is null, the stream yields one PdfPageImages per page in index order. Pages with no image objects emit an entry with an empty PdfPageImages.images list so callers can track page coverage without gaps.

When pageIndex is specified, the stream yields exactly one PdfPageImages for that page.

Bitmap mode

When includeBitmap is false (the default), PdfImage.bgra, PdfImage.bitmapWidth, and PdfImage.bitmapHeight are null on every returned PdfImage. Only metadata (PdfImage.metadata) and the bounding box (PdfImage.bounds) are populated. This is the cheap, memory-efficient path for enumerating images.

When includeBitmap is true, the rendered BGRA bitmap is fetched for every image object on each page. For documents with many large photographs this can produce very large allocations. Prefer calling renderImage selectively after inspecting PdfImageMetadata for image dimensions and colorspace.

Image masks

Image mask objects (metadata.bitsPerPixel == 1) are included in the output and are not suppressed automatically. Callers can identify them via image.metadata.bitsPerPixel == 1.

Error handling

Throws RangeError if pageIndex is out of range. Throws StateError if the document has been closed before or during extraction.

close terminates any active stream: the stream stops emitting events and the subscription is silently cancelled. Callers do not need to cancel streams manually before calling close.

Platform support: Native (dart:ffi) only. Stubs on unsupported platforms throw UnsupportedError immediately.

Example — collect all JPEG images from a document:

await for (final page in doc.extractImages()) {
  for (final img in page.images) {
    if (img.filters.contains('DCTDecode')) {
      final bitmap = await doc.renderImage(img.pageIndex, img.objectIndex);
      // use bitmap…
    }
  }
}