Image Rendering Options for olmOCR: PNG, WebP, and Playwright Methods

olmOCR provides four primary image rendering utilities—render_pdf_to_base64png, render_pdf_to_base64webp, render_pdf_with_playwright, and convert_image_to_pdf_bytes—that convert PDF pages or HTML content into raster images using command-line tools like pdftoppm, img2pdf, and headless Chromium via Playwright.

The allenai/olmocr repository includes specialized utilities for transforming PDF documents and HTML content into machine-readable image formats. Whether you need lossless PNGs for model input, compressed WebP for bandwidth-constrained pipelines, or HTML-to-PDF rendering for synthetic data generation, olmOCR's image rendering options provide efficient, layout-preserving rasterization through thin wrappers around mature CLI tools.

Core Image Rendering Methods

olmOCR implements four distinct rendering paths, each optimized for specific use cases and output formats. All utilities reside in olmocr/data for PDF-to-image conversion and olmocr/synth for HTML-based synthesis.

PNG Base-64 Rendering with render_pdf_to_base64png

The render_pdf_to_base64png function in olmocr/data/renderpdf.py generates lossless PNG images encoded as base-64 strings. This method invokes pdftoppm to rasterize PDF pages, making it ideal for inspection and downstream model input where fidelity is critical. The function automatically calculates the correct DPI based on your specified target longest dimension to preserve page geometry.

WebP Base-64 Rendering with render_pdf_to_base64webp

For bandwidth-constrained environments, render_pdf_to_base64webp (also in olmocr/data/renderpdf.py) produces WebP images as base-64 strings. This utility first generates a PNG using the same pipeline as the PNG renderer, then decodes it via Pillow and re-encodes to WebP format, delivering significantly smaller file sizes while maintaining visual quality suitable for training data.

Playwright-Based HTML Rendering

The render_pdf_with_playwright function located in olmocr/synth/mine_html_templates.py handles arbitrary HTML content using headless Chromium. This approach renders HTML to PDF first, then converts to PNG, enabling synthetic document generation from templates. This is particularly useful for the mine_html_templates pipeline when generating training data from programmatically created HTML layouts.

Image-to-PDF Conversion with convert_image_to_pdf_bytes

To package OCR results or combine multiple rasterized pages, convert_image_to_pdf_bytes in olmocr/image_utils.py converts image files (or lists of images) into PDF binary streams. This utility leverages the img2pdf command-line tool to produce standards-compliant PDF documents suitable for archival or further processing.

The Rendering Pipeline Architecture

olmOCR's rendering utilities follow a consistent four-step pipeline that ensures accurate preservation of original page layouts, including mathematical notation, tables, and figures.

1. Determine target resolution – The system calls get_pdf_media_box_width_height (in olmocr/data/renderpdf.py) to extract the page dimensions using pdfinfo, identifying the longest side for scaling calculations.

2. Rasterize content – For PDF inputs, pdftoppm executes with DPI computed from the requested target_longest_image_dim parameter to generate high-fidelity raster data.

3. Encode output – Raw PNG payloads undergo base-64 encoding to produce JSON-embeddable strings suitable for web interfaces and API responses.

4. Optional format conversion – When WebP is requested, the pipeline decodes the intermediate PNG using Pillow and re-encodes to WebP before base-64 encoding, optimizing for storage efficiency.

Practical Implementation Examples

Rendering PDF Pages to Base-64 PNG

Use render_pdf_to_base64png when you need lossless rasterization for document analysis:

from olmocr.data.renderpdf import render_pdf_to_base64png

# Render page 1 of "paper.pdf" to a PNG with maximum dimension 2048px

png_b64 = render_pdf_to_base64png(
    "./paper.pdf", 
    page_num=1, 
    target_longest_image_dim=2048
)

# Embed directly in JSON payloads for API transmission

payload = {"image_base64": png_b64}

Generating Compressed WebP Images

For reduced bandwidth usage, switch to the WebP renderer:

from olmocr.data.renderpdf import render_pdf_to_base64webp

# Generate WebP with 1024px longest side for efficient transmission

webp_b64 = render_pdf_to_base64webp(
    "./paper.pdf", 
    page=1, 
    target_longest_image_dim=1024
)

Synthetic Document Generation with Playwright

Generate images from HTML templates for training data augmentation:

import asyncio
from olmocr.synth.mine_html_templates import render_pdf_with_playwright

html_content = "<html><body><h1>Document Title</h1><p>Sample text</p></body></html>"
output_path = "/tmp/rendered.pdf"

# Render HTML to PDF, then capture as 800x600 PNG

result = asyncio.run(
    render_pdf_with_playwright(
        html_content=html_content,
        output_pdf_path=output_path,
        png_width=800,
        png_height=600,
    )
)

if result.success:
    print("Rendered PNG (base64):", result.base64_png)

Converting Images to PDF Format

Package multiple processed images into a single PDF document:

from olmocr.image_utils import convert_image_to_pdf_bytes

# Combine multiple page images into one PDF

image_paths = ["/tmp/page1.png", "/tmp/page2.png", "/tmp/page3.png"]
pdf_bytes = convert_image_to_pdf_bytes(image_paths)

# Write to disk

with open("combined_output.pdf", "wb") as f:
    f.write(pdf_bytes)

Summary

• olmOCR provides four specialized rendering utilities in olmocr/data/renderpdf.py and olmocr/synth/mine_html_templates.py for converting PDF and HTML content to images.
• PNG and WebP rendering use pdftoppm and pdfinfo for accurate page dimension extraction and lossless rasterization, with WebP offering smaller file sizes through Pillow re-encoding.
• Playwright integration enables synthetic document generation from HTML templates via headless Chromium rendering.
• Image-to-PDF conversion uses img2pdf to consolidate multiple images into standardized PDF documents.
• All methods rely on external CLI tools (pdftoppm, pdfinfo, img2pdf, Playwright) that must be present in the execution environment.

Frequently Asked Questions

What external dependencies are required for olmOCR image rendering?

olmOCR requires pdfinfo and pdftoppm (typically provided by Poppler utils) for PDF dimension extraction and rasterization, img2pdf for image-to-PDF conversion, and the Playwright Python package with headless Chromium for HTML rendering. These tools are invoked as subprocesses by the rendering utilities in olmocr/data/renderpdf.py and olmocr/synth/mine_html_templates.py.

How does olmOCR determine the resolution for rendered images?

The resolution calculation occurs in get_pdf_media_box_width_height within olmocr/data/renderpdf.py. This helper extracts the page's media box dimensions using pdfinfo, identifies the longest side, and computes the appropriate DPI for pdftoppm based on your specified target_longest_image_dim parameter, ensuring the output image maintains the original page proportions at your desired maximum dimension.

When should I use WebP instead of PNG in olmOCR?

Use render_pdf_to_base64webp when transmitting images over network connections or storing large volumes of training data where file size matters. WebP typically achieves 25-35% smaller files than PNG with minimal quality loss, making it optimal for bandwidth-constrained pipelines. Use PNG when you require maximum fidelity for detailed visual analysis or when computational overhead of format conversion must be minimized.

Can olmOCR render arbitrary HTML to images?

Yes, through render_pdf_with_playwright in olmocr/synth/mine_html_templates.py. This function accepts arbitrary HTML content, renders it to a temporary PDF using headless Chromium, and then captures the output as a PNG image. This capability supports synthetic data generation workflows where you need to convert HTML templates (such as those from the mine_html_templates pipeline) into training images for document understanding models.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}