pdf-codec: render a page (or region) to pixels, for OCR and vision consumers

[fcbwilliams]

What we need

A way to get pixels out of a PDF page (or a sub-region of one), so a caller can hand them to OCR or a vision model. Not the model call itself — see "what we are not asking for" below.

readPdf gives us positioned items and images-read.ts gives us embedded XObjects properly decoded, which covers a great deal. Two cases it cannot reach, and both are common in real client material:

1. A scanned document has no text layer to read

Measured on 2026-09-10, on five real product brochures rasterised to image-only PDFs with gs -sDEVICE=pdfimage24 -r150 (which is what a scanned document looks like to a parser): 102 pages, every one empty, 0 characters of text. The embedded XObject per page is extractable, so for a straightforwardly scanned page a caller can pull the page image out and OCR it — that part works today.

2. A chart drawn as vectors is not an image at all

This is the case with no workaround. The same five brochures, unrasterised, carry 291 image draw operations and 2,030 path operations across 102 pages. A chart exported from Excel or Illustrator into a PDF frequently arrives as ContentVector rects, lines and paths plus positioned text runs — there is no XObject to extract, the labels come out in an order that reads as scrambled, and no amount of text extraction recovers "revenue rose in EMEA and fell in APAC".

Rendering the region those vectors occupy is the only way to read it. That is true of any consumer of this library that wants to interpret a vector figure, not just us.

Shape we'd suggest

Something like renderPdfPage(pdfBytes, pageIndex, { scale | dpi, clipPt? }) returning PNG bytes, where clipPt is an optional region in the same point coordinates LayoutFrame already uses — so a caller that has located a figure region (via document-outline.js's segmentPdfRegions, which already classifies items into column/table/figure and attaches captions) can render just that figure rather than a whole page.

Two constraints we'd flag from our own environment, since they may shape where this lives:

Weight. pdf-codec is already ~13 MB unpacked, and the README is explicit that the root barrel's font payload is most of a Cloudflare Worker's 3 MB gzipped budget. A rasteriser is not small. The existing pdf-codec/read narrow entry with its build-failing static-graph test is exactly the right pattern — but rasterisation might warrant its own package (pdf-raster?) so that consumers who only extract never pay for it.

Runtime. This is the hard part and the reason we are asking rather than doing it ourselves. Our target is Cloudflare Workers, where there is no canvas and no OffscreenCanvas. The options we can see are a WASM rasteriser, or Cloudflare's Browser Rendering binding (which is per-session metered and slow), or keeping rasterisation client-side where the browser's canvas is free. Your existing workerd test suite makes you far better placed than us to judge which is viable — and if the answer is "Node and browser only, not workerd", saying so explicitly in the API's docs is itself useful, because it tells us where to put the call.

What we are NOT asking for

No OCR, no vision, no network calls in the codec. Keep that property — it is one of the best things about these packages, and we do not want a document library that reaches the internet. Hand us pixels and we will call the model ourselves; the results come back into the content model via the interpretation annotation requested separately.

Priority

Lower than the interpretation-model issue for us. We can extract embedded XObjects today with what pdf-codec already has, which covers scanned pages; the vector-figure case is the one with no path forward at all, and it is the one we will come back to.

[fcbwilliams]

Clarifying the runtime requirement: pluggable, not a chosen target

I framed this above as "which runtime?" — Node canvas vs WASM vs Cloudflare Browser Rendering. That was the wrong question, and the answer from our side is that the library should not enforce a deployment scenario at all. Flexibility is the requirement.

So rather than pdf-codec picking a rasteriser, the shape we would suggest is that it defines the interface and takes one:

type PageRasteriser = (page: RasterRequest) => Promise<Uint8Array>; // PNG bytes
renderPdfPage(pdfBytes, pageIndex, { scale, clipPt }, rasteriser)

with whichever backends make sense shipped as separate, individually-optional packages — a canvas one for Node and the browser, a WASM one for workerd, and room for a consumer to supply Cloudflare Browser Rendering or anything else without the library knowing.

That keeps three properties worth keeping: the core stays as dependency-light as it is today, a consumer targeting only Node never pays for a WASM blob, and nobody is blocked because their runtime was not the one chosen. It also sidesteps the size concern in the original post — the weight lands in whichever backend a consumer actually installs, not in pdf-codec.

The geometry side (clipPt in the same point coordinates LayoutFrame uses, so a caller can render just a figure region located via segmentPdfRegions) is unchanged from the original request, and that part is the bit we most need.

Unchanged too: no OCR, no vision, no network calls anywhere in the codec. Hand us pixels.