# How PDF to Image Rendering Works with Target Dimensions in OLMocr

> Discover how OLMocr renders PDFs to images, scaling pages to target dimensions while preserving aspect ratio using dynamic DPI. Learn more about PDF to image rendering.

- Repository: [Ai2/olmocr](https://github.com/allenai/olmocr)
- Tags: how-to-guide
- Published: 2026-07-06

---

**In OLMocr, PDF to image rendering scales pages by matching the longest side to a user-specified target pixel dimension (default 2048 px for PNG or 1024 px for WebP) while preserving aspect ratio through dynamic DPI calculation.**

OLMocr is an open-source library for converting PDF documents into machine-readable formats. When performing PDF to image rendering, the library enforces pixel budget constraints by calculating a custom rasterization resolution that ensures the output image never exceeds the target size while maintaining the original page proportions.

## The Three-Step Rendering Pipeline

The implementation in [`olmocr/data/renderpdf.py`](https://github.com/allenai/olmocr/blob/main/olmocr/data/renderpdf.py) processes each PDF page through a precise sequence that bridges physical document units (points) to digital pixels.

### Step 1: Extracting Physical Page Dimensions

The pipeline begins by measuring the source page using `get_pdf_media_box_width_height()`. This function executes the `pdfinfo` CLI utility to extract the *MediaBox* rectangle from the PDF metadata, returning the physical width and height in points (where 1 pt equals 1/72 inch).

```python

# https://github.com/allenai/olmocr/blob/main/olmocr/data/renderpdf.py#L9-L34

longest_dim = max(get_pdf_media_box_width_height(local_pdf_path, page_num))

```

### Step 2: Computing Dynamic Rasterization DPI

Rather than using a fixed DPI, OLMocr calculates a resolution specific to each page. Because 1 pt corresponds to 72 px, the required DPI is computed as:

\[
\text{dpi} = \frac{\text{target\_longest\_image\_dim} \times 72}{\text{longest\_dim}}
\]

This value is passed to `pdftoppm` via the `-r` flag, ensuring the output image's longest side equals exactly the target dimension while the shorter side scales proportionally.

```python

# https://github.com/allenai/olmocr/blob/main/olmocr/data/renderpdf.py#L51-L53

"-r",
str(target_longest_image_dim * 72 / longest_dim),

```

### Step 3: Rasterization and Format Encoding

The `pdftoppm` tool renders the selected page to a PNG stream, which is then base-64-encoded. The `render_pdf_to_base64png()` function handles this directly, while `render_pdf_to_base64webp()` adds an intermediate step that opens the PNG with Pillow and re-encodes it to WebP format before base-64 encoding.

```python

# PNG rendering – https://github.com/allenai/olmocr/blob/main/olmocr/data/renderpdf.py#L39-L60

# WebP conversion – https://github.com/allenai/olmocr/blob/main/olmocr/data/renderpdf.py#L63-L70

```

## Code Examples and Usage

The following examples demonstrate how to convert PDF pages with specific target dimensions:

```python

# Example 1 – Convert page 3 of a PDF to a base-64 PNG whose longest side is 2048 px

from olmocr.data.renderpdf import render_pdf_to_base64png

pdf_path = "/data/papers/sample.pdf"
page_number = 3
png_b64 = render_pdf_to_base64png(pdf_path, page_number, target_longest_image_dim=2048)

```

```python

# Example 2 – Same page, but obtain a WebP image with a 1024 px longest side

from olmocr.data.renderpdf import render_pdf_to_base64webp

webp_b64 = render_pdf_to_base64webp(pdf_path, page_number, target_longest_image_dim=1024)

```

```python

# Example 3 – Quickly query the dimensions of the resulting PNG without full decode

from olmocr.data.renderpdf import get_png_dimensions_from_base64

width, height = get_png_dimensions_from_base64(png_b64)
print(f"Rendered PNG size: {width}×{height}")

```

## Performance Optimization with Dimension Caching

The helper function `get_png_dimensions_from_base64()` reads image dimensions directly from the base-64 string header without fully decoding the PNG. This optimization speeds up downstream filtering when processing large batches of documents, as the pipeline can verify output sizes before expensive deserialization.

## Why Scale by the Longest Dimension?

By calculating DPI based on the longest side, OLMocr guarantees that the output never exceeds the target pixel budget while keeping the original aspect ratio intact. This approach works uniformly for both portrait and landscape page orientations, ensuring consistent resolution across mixed document collections.

## Summary

- **Dynamic DPI calculation**: OLMocr computes a custom resolution for each page using the formula `(target_longest_image_dim * 72) / longest_dim` to ensure the output matches exact pixel specifications.
- **Longest-side scaling**: The system measures the PDF's *MediaBox* via `pdfinfo` and scales based on the longest dimension to preserve aspect ratio across all orientations.
- **Format flexibility**: The `render_pdf_to_base64png()` and `render_pdf_to_base64webp()` functions support different output formats with appropriate defaults (2048 px for PNG, 1024 px for WebP).
- **Header-only dimension queries**: `get_png_dimensions_from_base64()` enables fast size verification without full image decoding.

## Frequently Asked Questions

### What is the default target dimension for PDF to image rendering in OLMocr?

By default, `render_pdf_to_base64png()` uses a target dimension of 2048 pixels for the longest side, while `render_pdf_to_base64webp()` defaults to 1024 pixels. These values can be overridden via the `target_longest_image_dim` parameter.

### How does OLMocr preserve aspect ratio when rendering PDFs to images?

The library calculates a specific DPI value for each page based on its physical dimensions in points. By applying this DPI to `pdftoppm` via the `-r` flag, the tool scales both width and height proportionally, ensuring the longest side matches the target while the shorter side scales accordingly.

### Why does OLMocr use the longest side rather than the width or height for scaling?

Scaling by the longest side provides a consistent pixel budget across both portrait and landscape orientations. This prevents landscape pages from exceeding memory constraints while ensuring portrait pages maintain sufficient resolution, as the aspect ratio remains locked during rasterization.

### Can I retrieve image dimensions without decoding the entire base64 string?

Yes. The `get_png_dimensions_from_base64()` function parses the PNG header within the base-64 string to extract width and height dimensions without performing full base-64 decoding or image deserialization, significantly improving performance when validating large batches.