Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/StarTrail-org/PixelRAG/llms.txt

Use this file to discover all available pages before exploring further.

pixelrag_render exposes functions for rendering documents to tiled JPEG images from Python. Three functions — render_url, render_pdf, and render_file — are available as top-level imports from pixelrag_render. The batch variant render_urls is available from the inner module pixelrag_render.render. Under the hood they call browser-based (CDP) or PDF rendering backends and write a structured tile directory for each document, which the embedding and indexing stages then consume. 
from pixelrag_render import render_url, render_pdf, render_file
from pixelrag_render.render import render_urls  # batch variant; not re-exported from the top-level package

​
render_url

def render_url(
    url: str,
    output_dir: str | Path,
    backend: str = "cdp",
    *,
    tile_height: int = 8192,
    quality: int = 85,
    viewport_width: int = 875,
    workers: int = 1,
    **kwargs,
) -> list[Path]:
Render a single URL to tiled JPEG images. Internally delegates to render_urls with a one-element list.

​
Parameters

​
url
string
required
URL to capture. Accepts http://, https://, or file:// schemes.
​
output_dir
str or Path
required
Directory to write the tile subdirectory into.
​
backend
string
default:"cdp"
Rendering backend. "cdp" (default, fastest) uses Chrome DevTools Protocol. "websocket" is accepted as a back-compat alias for "cdp". Any other value raises ValueError.
​
tile_height
integer
default:"8192"
Maximum height of each tile image in pixels. Tall pages are split into multiple tiles.
​
quality
integer
default:"85"
JPEG quality, 1–100.
​
viewport_width
integer
default:"875"
Browser viewport width in pixels.
​
workers
integer
default:"1"
Number of parallel browser processes.
​
**kwargs
any
Additional keyword arguments forwarded to the backend. For example, wait_network_idle=True waits for network quiet before capturing.

​
Returns

list[Path] — tile directories created (one per rendered URL).

​
Example

from pathlib import Path
from pixelrag_render import render_url

tile_dirs = render_url(
    "https://en.wikipedia.org/wiki/Python_(programming_language)",
    output_dir="./tiles",
    tile_height=8192,
    quality=85,
    viewport_width=875,
)
print(tile_dirs)
# [PosixPath('tiles/Python_(programming_language).png.tiles')]

​
render_urls

def render_urls(
    urls: list[str],
    output_dir: str | Path,
    backend: str = "cdp",
    *,
    stems: list[str] | None = None,
    tile_height: int = 8192,
    quality: int = 85,
    viewport_width: int = 875,
    workers: int = 4,
    **kwargs,
) -> list[Path]:
Render a list of URLs to tiled JPEG images in parallel.

​
Parameters

​
urls
list of string
required
URLs to capture.
​
output_dir
str or Path
required
Directory to write tile subdirectories into.
​
backend
string
default:"cdp"
Rendering backend. Only "cdp" is fully supported.
​
stems
list of string or None
default:"None"
Optional list of output directory stems, one per URL. When provided, tiles for urls[i] are written to {output_dir}/{stems[i]}.png.tiles/ instead of deriving a name from the URL. Useful for assigning sequential numeric IDs (e.g. ["0", "1", "2", ...]), as the pixelrag index build pipeline does.
​
tile_height
integer
default:"8192"
Maximum tile height in pixels.
​
quality
integer
default:"85"
JPEG quality, 1–100.
​
viewport_width
integer
default:"875"
Browser viewport width in pixels.
​
workers
integer
default:"4"
Number of parallel browser processes.
​
**kwargs
any
Additional keyword arguments forwarded to the backend.

​
Returns

list[Path] — tile directories created (one per URL).

​
Example

from pixelrag_render.render import render_urls

urls = [
    "https://en.wikipedia.org/wiki/Nikola_Tesla",
    "https://en.wikipedia.org/wiki/Marie_Curie",
    "https://en.wikipedia.org/wiki/Albert_Einstein",
]

# Render with sequential numeric stems so article_id == position
tile_dirs = render_urls(
    urls,
    output_dir="./tiles",
    stems=["0", "1", "2"],
    workers=4,
)
# Creates: tiles/0.png.tiles/, tiles/1.png.tiles/, tiles/2.png.tiles/

​
render_pdf

def render_pdf(
    path: str | Path,
    output_dir: str | Path,
    *,
    dpi: int = 200,
    pages: list[int] | None = None,
    quality: int = 85,
    stem: str | None = None,
) -> list[Path]:
Render a PDF file to tiled JPEG images. Each page becomes one tile image.

​
Parameters

​
path
str or Path
required
Path to the PDF file on disk.
​
output_dir
str or Path
required
Directory to write the tile subdirectory into.
​
dpi
integer
default:"200"
Rendering resolution. At 200 DPI, A4 pages render at approximately 1650×2200 px.
​
pages
list of int or None
default:"None"
1-based list of page numbers to render. None renders all pages.
​
quality
integer
default:"85"
JPEG quality, 1–100.
​
stem
string or None
default:"None"
Override the tile directory name (default: PDF filename stem, e.g. "report" for report.pdf).

​
Returns

list[Path] — a list containing the tile directory path.

​
Example

from pixelrag_render import render_pdf

tile_dirs = render_pdf(
    "report.pdf",
    output_dir="./tiles",
    dpi=200,
    pages=[1, 2, 3],   # render only first 3 pages
    stem="my_report",  # → tiles/my_report.png.tiles/
)

​
Output Structure

Every rendering function writes a {stem}.png.tiles/ subdirectory under output_dir: 
output_dir/
└── {stem}.png.tiles/
    ├── tiles.json        # manifest: page_height, tile_height, tile list, complete flag
    ├── tile_0000.jpg     # first 8192 px tile
    ├── tile_0001.jpg     # second 8192 px tile (if page is taller)
    └── ...
The tiles.json manifest records the article ID, page height, viewport width, tile height, and tile filenames. The chunking stage (pixelrag chunk) reads this manifest to produce the 1024 px chunk files and chunks.json that the embedding stage consumes.
For web URLs, the default stem is derived from the URL. Pass explicit stems when you need predictable directory names — for example, sequential integers that double as article_id values for the serve API.

Build docs developers (and LLMs) love

Get started for freeTalk to us