PDF Resources Dictionary
A dictionary attached to each PDF page (or inherited from a parent in the page tree) listing all external resources needed to render that page: fonts, images, colour spaces, extended graphics states, and XObjects.
Every page in a PDF document that contains visible content needs resources — fonts to render text, images to display, colour spaces to interpret colours, and extended graphics state dictionaries to control opacity and blend modes. These resources are declared in the page's Resources dictionary, a structured index that maps short local names to the actual resource objects stored elsewhere in the PDF file.
The Resources dictionary is the bridge between a page's content stream (which refers to resources by short names like `/F1` or `/Im3`) and the actual resource objects (font programs, image data, colour profile streams) stored in the PDF's cross-reference table. Without the Resources dictionary, a PDF viewer would not know where to find the data needed to render the page.
Understanding the Resources dictionary is important for anyone debugging PDF rendering problems, building PDF generation tools, or analysing why a page renders differently in different viewers.
Structure of the Resources dictionary
The Resources dictionary is stored in each page dictionary under the `/Resources` key. It contains sub-dictionaries for each resource category:
``` << /Resources << /Font << /F1 12 0 R % font resource named F1, object 12 /F2 45 0 R >> /XObject << /Im1 7 0 R % image named Im1, object 7 /Bg 8 0 R % form XObject named Bg >> /ColorSpace << /CS1 [/ICCBased 20 0 R] >> /ExtGState << /GS1 << /ca 0.5 /CA 0.5 >> % 50% opacity graphics state >> /Pattern << /P1 30 0 R >> /Shading << /Sh1 31 0 R >> /ProcSet [/PDF /Text /ImageB /ImageC /ImageI] >> >> ```
The categories are: - `/Font` — Fonts used in text operators (`Tf`) - `/XObject` — Images and Form XObjects referenced by `Do` - `/ColorSpace` — Named colour spaces used by `cs` and `CS` operators - `/ExtGState` — Extended graphics state dictionaries used by `gs` operator - `/Pattern` — Pattern resources for tiling or shading fills - `/Shading` — Shading resources for smooth colour gradients - `/Properties` — Optional content (layer) property dictionaries - `/ProcSet` — Legacy compatibility indicator (deprecated in PDF 1.4, still present in many PDFs)
Inherited resources and the page tree
The PDF page tree allows resource dictionaries to be **inherited** from parent nodes. If a page does not have its own `/Resources` dictionary, the viewer looks up the page tree to find the nearest ancestor with one.
This inheritance mechanism is useful for documents where all pages use the same set of fonts and colour spaces — the shared resources can be declared once at the page tree root, rather than duplicating them in every page's resource dictionary.
``` %% Page tree root << /Type /Pages /Kids [10 0 R, 11 0 R, 12 0 R] /Count 3 /Resources % shared by all pages unless overridden << /Font << /Body 50 0 R /Heading 51 0 R >> /ProcSet [/PDF /Text] >> >>
%% Individual page — inherits root resources, adds its own image << /Type /Page /Parent 5 0 R /Resources << /XObject << /Im1 7 0 R >> % additional resource for this page only >> /Contents 20 0 R >> ```
In the example above, page 10 can use fonts F1 and F2 from the parent's resources, plus image Im1 from its own resources dictionary. The viewer merges inherited and page-level resources, with page-level entries overriding inherited ones of the same name.
When splitting a PDF, resource inheritance can cause problems — if a page inherited fonts from the parent page tree root, the split page no longer has access to those fonts. Good PDF splitting tools resolve inheritance before splitting, copying inherited resources into each output page's own dictionary.
Extended graphics state resources
The `/ExtGState` sub-dictionary deserves special attention because it is how many important rendering parameters are specified, including transparency.
An extended graphics state dictionary can contain many parameters, but the most commonly used are:
- `/ca` — Non-stroking (fill) opacity: 0.0 (fully transparent) to 1.0 (fully opaque) - `/CA` — Stroking opacity - `/BM` — Blend mode: `/Normal`, `/Multiply`, `/Screen`, `/Overlay`, etc. - `/SMask` — Soft mask (for complex transparency effects) - `/Font` — Font and size (can be set in graphics state rather than Tf operator) - `/LW` — Line width - `/LC` — Line cap style - `/LJ` — Line join style
When a PDF content stream contains a semi-transparent element (a watermark, a faded background, an opacity-adjusted overlay), the `gs` operator is used to apply an ExtGState with the appropriate opacity values before drawing:
``` /GS1 gs % apply graphics state GS1 (which sets ca=0.3) /Watermark Do % draw Form XObject at 30% opacity ```
The `/GS1` name references the entry in the page's `/ExtGState` resource dictionary. This is the PDF mechanism underlying all transparency effects — drop shadows, translucent overlays, faded watermarks.
Diagnosing resource-related rendering problems
Many PDF rendering problems — missing fonts, missing images, incorrect colours — trace back to resource dictionary issues. Common scenarios:
**"Font not found" / text renders with substitute font** — The `/Font` resource entry points to a font dictionary without an embedded font program (`/FontFile`, `/FontFile2`, or `/FontFile3` key in the font descriptor). The viewer substitutes a similar font, potentially changing character widths and layout. Fix: embed all fonts at PDF creation time, or use a tool like Acrobat Pro's Preflight to embed missing fonts.
**"Image not found" / blank space where image should be** — The `/XObject` resource entry references an object that does not exist (cross-reference error) or was removed during optimisation. Fix: regenerate the PDF from source, or use <a href="https://qpdf.sourceforge.io/" target="_blank" rel="noopener">QPDF</a> with `--check` to detect broken cross-references.
**Incorrect transparency / all elements fully opaque** — The `/ExtGState` resource is missing, invalid, or the PDF viewer does not support the transparency model (PDF 1.4+). In some contexts (PostScript output, old RIPs), transparency requires flattening — see <a href="https://pdftheguide.com/glossary/pdf-transparency" target="_blank" rel="noopener">PDF Transparency</a>.
**"Unknown operator" error in content stream** — A resource referenced by name in the content stream does not have a corresponding entry in the Resources dictionary. Often caused by PDF generators that create content streams before finalising resource dictionaries and fail to add all referenced resources.
To inspect a PDF's resources: use <a href="https://github.com/itext/rups" target="_blank" rel="noopener">RUPS</a> for visual exploration, or `pikepdf.open("file.pdf").pages[0].Resources` in Python for programmatic access.
Frequently asked questions
What is the Resources dictionary in a PDF?
The Resources dictionary is attached to each PDF page and lists all external objects the page needs to render correctly: fonts (/Font), images and Form XObjects (/XObject), colour spaces (/ColorSpace), transparency/blend settings (/ExtGState), and patterns (/Pattern). The content stream references these resources by short local names; the Resources dictionary maps those names to the actual objects stored in the PDF file.
Why do some PDFs render differently in different viewers?
Resource-related rendering differences occur when: (1) a font is not embedded and viewers substitute different fonts; (2) a colour space profile is not embedded and viewers apply different default colour profiles; (3) a transparency blend mode or extended graphics state is not supported by the viewer; (4) a Form XObject uses features the viewer does not implement. Embedding all fonts and using standard colour spaces (sRGB for screen content, CMYK with an embedded ICC profile for print) minimises viewer-specific rendering differences.
Can resources be shared across all pages in a PDF?
Yes — through the page tree inheritance mechanism. Resources defined in a parent page tree node are inherited by all descendant pages. For documents where all pages use the same fonts and colour spaces, declaring shared resources at the root page tree node avoids duplicating them in every page's Resources dictionary, reducing file size. PDF generation tools vary in how aggressively they share resources — some create per-page resource dictionaries even for shared fonts, causing unnecessary file size.
How do I find out what fonts a PDF uses?
Several methods: (1) In Adobe Acrobat, File > Properties > Fonts tab lists all fonts with their embedding status. (2) Command-line: `pdffonts input.pdf` (from Poppler's pdffonts tool) lists all fonts with type, encoding, and embedding status. (3) Python: `pikepdf.open("file.pdf").pages[0].Resources.Font` lists fonts on the first page. Fonts listed as "not embedded" will render with substitutes on systems that do not have those fonts installed.