# katjas/pdfrenderer architecture

> Architecture diagram of the GitHub repository katjas/pdfrenderer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/katjas/pdfrenderer
- Repository: https://github.com/katjas/pdfrenderer

## Overview

1. **Overall purpose**
   This repository is a Java PDF rendering library, forked from `pdf-renderer`. Its core job is to take PDF bytes, parse the document structure, interpret page content, and paint pages onto a `Graphics2D` target.

2. **Primary runtime flow**
   The main data flow is: raw PDF bytes → `PDFFile` / `PDFParser` / `PDFObject` graph → `PDFPage` → `PDFRenderer` → Java2D drawing commands. The example in the README shows the typical boundary: application code owns the byte source and the destination `Graphics2D`, while the library handles parsing and rendering.

3. **Document parsing layer**
   `PDFFile`, `PDFParser`, `PDFXref`, `PDFObject`, `PDFDestination`, `NameTree`, and `OutlineNode` make up the document model and navigation layer. This subsystem reads the PDF structure, cross-reference tables, outlines, destinations, and page/page-tree information before any rendering happens.

4. **Rendering and page composition**
   `PDFRenderer`, `PDFPage`, `PDFCmd`, `PDFShapeCmd`, `PDFPaint`, and `PDFTextFormat` form the page interpretation layer. Content streams are converted into drawing commands, text operations, fills/strokes, and image placements, then executed against Java2D. This is where page appearance is assembled.

5. **Image decoding pipeline**
   The `decode` package handles PDF filter streams and image-related decompression: ASCII85, ASCIIHex, Flate, LZW, RunLength, DCT/JPEG, JPX, JBIG2, CCITT Fax, and predictor handling. This is a major subsystem because PDF pages often carry compressed images and mask data that must be decoded before painting.

6. **Encryption and decryption boundary**
   The `decrypt` package isolates PDF security handling. `PDFDecrypterFactory`, `StandardDecrypter`, `CryptFilterDecrypter`, and `IdentityDecrypter` decide how encrypted objects and streams are read. The repository also includes explicit error types for unsupported encryption and authentication failures, so encryption is a distinct parse-time concern.

7. **Font subsystem**
   The `font` package is one of the largest subsystems and handles built-in fonts, Type 1/1C, Type 3, TrueType, CID fonts, and font descriptors/encodings. It also contains TTF parsing (`font/ttf`) and CID mapping resources. Font resolution is a separate pipeline from page parsing because text rendering depends on font lookup, glyph mapping, and fallback behavior.

8. **Color management**
   The `colorspace` package implements PDF color spaces beyond basic RGB/gray, including CMYK, CalRGB, CalGray, Lab, Indexed, Pattern, alternate/mask spaces, and ICC-related resources. This layer sits between decoded page/image data and final Java2D colors, and the README notes color handling as an area with known limitations and fixes.

9. **PDF functions and PostScript evaluation**
   The `function` package supports sampled and procedural PDF functions, including Type 0, 2, 3, and 4. Type 4 uses a small PostScript interpreter under `function/postscript`, which matters for alternate color spaces, shading, and other PDF features that compute values dynamically rather than storing them directly.

10. **Patterns, shadings, and graphics effects**
   The `pattern` package contains tiling patterns and shading support, which feed into rendering when fills are not simple solid colors. This is part of the graphics interpretation layer and works alongside the color space and function subsystems.

11. **Actions and annotations**
   The `action` and `annotation` packages cover interactive PDF features such as links, go-to actions, launch/URI actions, widgets, stamps, free text, and markup annotations. These are mostly document-level features that are parsed from page metadata and then exposed or partially rendered, rather than part of core page painting.

12. **Resources and external dependencies**
   The repo bundles font resources, ICC profiles, and `stdclasses` assets, plus a third-party JBIG2 decoder JAR under `stdclasses/unpublic`. The README also mentions use of ImageIO-based JPEG handling and local TTF font lookup on the host system, so rendering can depend on both bundled assets and environment-installed fonts.

13. **Testing and examples**
   `src/test/myrenderer` contains a simple rendering demo harness, and `test/src/.../PostScriptOPTest.java` exercises the PostScript function subsystem. This suggests the project’s test surface is focused on rendering behavior and function evaluation rather than a large application-level test suite.

14. **Build and packaging**
   The repository includes both `pom.xml` and `build.xml`, so it supports Maven and Ant-based builds. That reinforces that this is a library artifact, not a standalone application: downstream code is expected to instantiate `PDFFile`, obtain pages, and render them into its own UI or image pipeline.

Main entry points: [`src/com/sun/pdfview/PDFObject.java`](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFObject.java) (PDFObject), [`src/com/sun/pdfview/PDFRenderer.java`](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFRenderer.java) (PDFRenderer), [`src/com/sun/pdfview/decode/PDFDecoder.java`](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/decode/PDFDecoder.java) (Decode filters), [`src/com/sun/pdfview/font/PDFFont.java`](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/font/PDFFont.java) (Font core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core parse/render"]
  node_app["Host app<br/>consumer"]
  node_pdffile["PDFFile<br/>document entry<br/>[PDFFile.java]"]
  node_parser["PDFParser<br/>stream parser<br/>[PDFParser.java]"]
  node_xref["PDFXref<br/>xref table<br/>[PDFXref.java]"]
  node_object["PDFObject<br/>pdf object<br/>[PDFObject.java]"]
  node_page["PDFPage<br/>page model<br/>[PDFPage.java]"]
  node_renderer["PDFRenderer<br/>render engine<br/>[PDFRenderer.java]"]
  node_cmd["PDFCmd<br/>draw command<br/>[PDFCmd.java]"]
  node_shape["Shape cmd<br/>shape command<br/>[PDFShapeCmd.java]"]
  node_paint["PDFPaint<br/>paint bridge<br/>[PDFPaint.java]"]
  node_textfmt["Text format<br/>text layout<br/>[PDFTextFormat.java]"]
end

subgraph group_decode["Decode pipeline"]
  node_decode["Decode filters<br/>stream decode<br/>[PDFDecoder.java]"]
  node_imageinfo["Image info<br/>image metadata<br/>[ImageInfo.java]"]
end

subgraph group_font["Fonts"]
  node_fontcore["Font core<br/>font system<br/>[PDFFont.java]"]
  node_ttf["TTF parser<br/>font parsing<br/>[TrueTypeFont.java]"]
end

subgraph group_graphics["Graphics model"]
  node_colorspace["Color space<br/>color model<br/>[PDFColorSpace.java]"]
  node_function["PDF function<br/>value function<br/>[PDFFunction.java]"]
  node_postscript["PostScript eval<br/>expression engine"]
  node_pattern["Patterns<br/>shading/pattern<br/>[PDFPattern.java]"]
end

subgraph group_security["Security"]
  node_decrypter["Decrypter<br/>security policy"]
end

subgraph group_interactive["Interactive PDF"]
  node_action["Actions<br/>interactive feature<br/>[PDFAction.java]"]
  node_annotation["Annotations<br/>interactive feature<br/>[PDFAnnotation.java]"]
end

subgraph group_assets["Bundled assets"]
  node_bundlefonts["Base fonts<br/>resource bundle"]
  node_icc["ICC profile<br/>color profile<br/>[sGray.icc]"]
  node_jbig2["JBIG2 jar<br/>binary asset<br/>[jbig2.jar]"]
end

node_app -->|"open PDF"| node_pdffile
node_pdffile -->|"parse"| node_parser
node_parser -->|"resolve xref"| node_xref
node_xref -->|"load object"| node_object
node_object -->|"build page"| node_page
node_page -->|"render page"| node_renderer
node_renderer -->|"execute cmds"| node_cmd
node_renderer -->|"draw paths"| node_shape
node_renderer -->|"apply paint"| node_paint
node_renderer -->|"place text"| node_textfmt
node_object -->|"decode streams"| node_decode
node_decode -->|"produce image"| node_imageinfo
node_object -->|"decrypt objects"| node_decrypter
node_object -->|"resolve fonts"| node_fontcore
node_fontcore -->|"parse TTF"| node_ttf
node_object -->|"map colors"| node_colorspace
node_colorspace -->|"evaluate funcs"| node_function
node_function -->|"type 4"| node_postscript
node_object -->|"resolve pattern"| node_pattern
node_pattern -->|"shade values"| node_function
node_object -->|"parse actions"| node_action
node_object -->|"parse annots"| node_annotation
node_fontcore -->|"base fonts"| node_bundlefonts
node_colorspace -->|"profile data"| node_icc
node_decode -->|"jbig2 decode"| node_jbig2

click node_pdffile "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFFile.java"
click node_parser "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFParser.java"
click node_xref "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFXref.java"
click node_object "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFObject.java"
click node_page "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFPage.java"
click node_renderer "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFRenderer.java"
click node_cmd "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFCmd.java"
click node_shape "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFShapeCmd.java"
click node_paint "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFPaint.java"
click node_textfmt "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFTextFormat.java"
click node_decode "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/decode/PDFDecoder.java"
click node_imageinfo "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/ImageInfo.java"
click node_decrypter "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/decrypt/PDFDecrypterFactory.java"
click node_fontcore "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/font/PDFFont.java"
click node_ttf "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/font/ttf/TrueTypeFont.java"
click node_colorspace "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/colorspace/PDFColorSpace.java"
click node_function "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/function/PDFFunction.java"
click node_postscript "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/function/postscript/PostScriptParser.java"
click node_pattern "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/pattern/PDFPattern.java"
click node_action "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/action/PDFAction.java"
click node_annotation "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/annotation/PDFAnnotation.java"
click node_bundlefonts "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/font/res/BaseFonts.properties"
click node_icc "https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/colorspace/sGray.icc"
click node_jbig2 "https://github.com/katjas/pdfrenderer/blob/master/stdclasses/unpublic/jbig2.jar"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_pdffile,node_parser,node_xref,node_object,node_page,node_renderer,node_cmd,node_shape,node_paint,node_textfmt,node_bundlefonts,node_icc,node_jbig2 toneBlue
class node_decode,node_imageinfo toneAmber
class node_fontcore,node_ttf toneMint
class node_colorspace,node_function,node_postscript,node_pattern toneRose
class node_decrypter toneIndigo
class node_action,node_annotation toneTeal
```

## Components

### Core parse/render

Document model, page parsing, and Java2D rendering pipeline.

- **Host app**: consumer · Downstream code supplies PDF bytes and a Graphics2D target.
- [PDFFile](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFFile.java): document entry · Top-level document wrapper that opens and exposes PDF structure. · `src/com/sun/pdfview/PDFFile.java`
- [PDFParser](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFParser.java): stream parser · Reads the PDF byte stream and builds object data. · `src/com/sun/pdfview/PDFParser.java`
- [PDFXref](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFXref.java): xref table · Resolves cross-reference entries and object locations. · `src/com/sun/pdfview/PDFXref.java`
- [PDFObject](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFObject.java): pdf object · Represents parsed PDF dictionaries, arrays, streams, and primitives. · `src/com/sun/pdfview/PDFObject.java`
- [PDFPage](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFPage.java): page model · Holds a page's content stream and page-level state for rendering. · `src/com/sun/pdfview/PDFPage.java`
- [PDFRenderer](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFRenderer.java): render engine · Interprets page content and issues Java2D drawing commands. · `src/com/sun/pdfview/PDFRenderer.java`
- [PDFCmd](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFCmd.java): draw command · Base command abstraction for page painting operations. · `src/com/sun/pdfview/PDFCmd.java`
- [Shape cmd](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFShapeCmd.java): shape command · Geometry and path drawing commands used by page composition. · `src/com/sun/pdfview/PDFShapeCmd.java`
- [PDFPaint](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFPaint.java): paint bridge · Bridges PDF paint state into Java2D fill and stroke behavior. · `src/com/sun/pdfview/PDFPaint.java`
- [Text format](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/PDFTextFormat.java): text layout · Tracks PDF text state, spacing, matrices, and glyph placement. · `src/com/sun/pdfview/PDFTextFormat.java`

### Decode pipeline

Stream filters and image decompression used during parsing and rendering.

- [Decode filters](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/decode/PDFDecoder.java): stream decode · Central dispatcher for PDF stream and image filter decoding. · `src/com/sun/pdfview/decode/PDFDecoder.java`
- [Image info](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/ImageInfo.java): image metadata · Carries image dimensions, masks, and decoded image state. · `src/com/sun/pdfview/ImageInfo.java`

### Fonts

Font resolution, glyph mapping, and embedded font resources.

- [Font core](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/font/PDFFont.java): font system · Resolves PDF font definitions into usable glyph sources. · `src/com/sun/pdfview/font/PDFFont.java`
- [TTF parser](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/font/ttf/TrueTypeFont.java): font parsing · Parses TrueType tables and glyph data for embedded or host fonts. · `src/com/sun/pdfview/font/ttf/TrueTypeFont.java`

### Graphics model

Color spaces, functions, patterns, and other rendering effects.

- [Color space](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/colorspace/PDFColorSpace.java): color model · Implements PDF color spaces and conversion into renderable colors. · `src/com/sun/pdfview/colorspace/PDFColorSpace.java`
- [PDF function](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/function/PDFFunction.java): value function · Evaluates sampled and procedural PDF functions used by colors and shadings. · `src/com/sun/pdfview/function/PDFFunction.java`
- [PostScript eval](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/function/postscript/PostScriptParser.java): expression engine · Small interpreter for Type 4 PDF function operators. · `src/com/sun/pdfview/function/postscript/PostScriptParser.java`
- [Patterns](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/pattern/PDFPattern.java): shading/pattern · Tiling patterns and shading objects used during fill rendering. · `src/com/sun/pdfview/pattern/PDFPattern.java`

### Security

PDF encryption and decryption boundary.

- [Decrypter](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/decrypt/PDFDecrypterFactory.java): security policy · Selects the appropriate decryption strategy for encrypted objects. · `src/com/sun/pdfview/decrypt/PDFDecrypterFactory.java`

### Interactive PDF

Actions and annotations parsed from page/document metadata.

- [Actions](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/action/PDFAction.java): interactive feature · PDF link and navigation actions such as GoTo and URI. · `src/com/sun/pdfview/action/PDFAction.java`
- [Annotations](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/annotation/PDFAnnotation.java): interactive feature · Page annotations including links, widgets, stamps, and markup. · `src/com/sun/pdfview/annotation/PDFAnnotation.java`

### Bundled assets

Embedded resources required by the renderer.

- [Base fonts](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/font/res/BaseFonts.properties): resource bundle · Embedded base font outlines and encoding resources. · `src/com/sun/pdfview/font/res/BaseFonts.properties`
- [ICC profile](https://github.com/katjas/pdfrenderer/blob/master/src/com/sun/pdfview/colorspace/sGray.icc): color profile · Bundled grayscale profile used by color management. · `src/com/sun/pdfview/colorspace/sGray.icc`
- [JBIG2 jar](https://github.com/katjas/pdfrenderer/blob/master/stdclasses/unpublic/jbig2.jar): binary asset · Bundled third-party JBIG2 decoder used for image streams. · `stdclasses/unpublic/jbig2.jar`

## Connections

- Host app → PDFFile: open PDF · Application code hands raw bytes to the library's document entry point.
- PDFFile → PDFParser: parse · The document wrapper delegates byte-stream parsing.
- PDFParser → PDFXref: resolve xref · Parsing uses the cross-reference table to locate indirect objects.
- PDFXref → PDFObject: load object · Cross-reference entries materialize parsed PDF objects.
- PDFObject → PDFPage: build page · Page-tree and page content are assembled from PDF objects.
- PDFPage → PDFRenderer: render page · A page is interpreted into a sequence of drawing operations.
- PDFRenderer → PDFCmd: execute cmds · The renderer dispatches page commands in order.
- PDFRenderer → Shape cmd: draw paths · Shape commands handle path and geometry painting.
- PDFRenderer → PDFPaint: apply paint · Fill and stroke state is translated into Java2D paint behavior.
- PDFRenderer → Text format: place text · Text state drives glyph positioning and spacing.
- PDFObject → Decode filters: decode streams · Stream and image data are filtered during object parsing.
- Decode filters → Image info: produce image · Decoded image data is packaged for later painting.
- PDFObject → Decrypter: decrypt objects · Encrypted objects and streams are routed through the security layer.
- PDFObject → Font core: resolve fonts · Font dictionaries and descriptors are turned into usable font objects.
- Font core → TTF parser: parse TTF · TrueType fonts are parsed for tables, glyphs, and metrics.
- PDFObject → Color space: map colors · Color-space resources are resolved from PDF object graphs.
- Color space → PDF function: evaluate funcs · Some color spaces and shadings depend on PDF functions.
- PDF function → PostScript eval: type 4 · Type 4 functions are executed by the embedded PostScript interpreter.
- PDFObject → Patterns: resolve pattern · Pattern and shading resources are loaded from document objects.
- Patterns → PDF function: shade values · Shadings can use functions to compute color transitions.
- PDFObject → Actions: parse actions · Interactive link and navigation actions are extracted from objects.
- PDFObject → Annotations: parse annots · Page annotations are loaded from document metadata.
- Font core → Base fonts: base fonts · Built-in font resources back the font subsystem.
- Color space → ICC profile: profile data · Bundled ICC resources support color conversion.
- Decode filters → JBIG2 jar: jbig2 decode · JBIG2 images rely on the bundled third-party decoder.