DEV Community

Cover image for Adding PDF support to a Rust image converter — what I learned about libvips and PDF rendering
Serhii Kalyna
Serhii Kalyna

Posted on

Adding PDF support to a Rust image converter — what I learned about libvips and PDF rendering

#rust #webdev #imageprocessing #buildinpublic

Been building Convertify — a free image converter in Rust + Axum + libvips. This week I added PDF to JPG/PNG support. Thought I'd write up what actually happened because it was more interesting than expected.

The naive approach

My existing image pipeline is straightforward — VipsImage::new_from_file(path), some processing, image_write_to_file(out_path). Images just work. I assumed PDFs would be similar.

First attempt:

let image = VipsImage::new_from_file(&format!("{}[dpi={}]", file_path, dpi))?;
Enter fullscreen mode Exit fullscreen mode

This actually works. libvips accepts PDF paths with a dpi parameter and returns a VipsImage. For a single-page PDF it's almost trivially simple.

Multi-page gets interesting

The problem is multi-page PDFs. You need to render each page separately and either return them as individual files or bundle them into a ZIP. My load_pdf function probes the file first to get the page count:

let probe = VipsImage::new_from_file(&file_path)?;
let quantity_pages = probe.get_n_pages();
Enter fullscreen mode Exit fullscreen mode

Then for each page:

let image = VipsImage::new_from_file(&format!(
    "{}[dpi={},page={}]",
    file_path, dpi, num_page
))?;
Enter fullscreen mode Exit fullscreen mode

The page parameter is zero-indexed. Simple enough. The output goes into individual files which then get zipped:

let mut zip = ZipWriter::new(file);
for page_file in &name_pages {
    zip.start_file(page_file, options)?;
    let data = std::fs::read(format!("./tmp/{page_file}"))?;
    zip.write_all(&data)?;
    std::fs::remove_file(format!("./tmp/{page_file}"))?;
    registry.lock().await.remove(page_file); // cleanup registry too
}
zip.finish()?;
Enter fullscreen mode Exit fullscreen mode

The rendering engine question

libvips doesn't have its own PDF renderer — it delegates to either poppler or pdfium depending on how it was compiled. On most Linux distros you get poppler via the libvips-dev package. On a clean Ubuntu 24 EC2 instance this just worked, but I hit a subtle issue: some PDFs rendered correctly in Acrobat but had slightly different text positioning in my output. Turns out poppler's Splash rasterizer and pdfium's Skia backend produce noticeably different results on complex layouts.

If you're doing this in production and care about rendering quality, check what backend your libvips was compiled against:

vips --version
# also check what PDF loader is available:
vips -l | grep pdf
Enter fullscreen mode Exit fullscreen mode

If pdfiumload is available alongside pdfload, you can use pdfium explicitly. The quality difference on text-heavy PDFs is visible — Skia's analytical coverage rasterizer produces cleaner edges than Splash.

DPI clamping

I added a DPI clamp on the server side — users can request any DPI but I limit it to 72–300:

let dpi = match params.get("dpi") {
    Some(value) => match value.parse::<i32>() {
        Ok(num) => num.clamp(72, 300),
        Err(_) => 150,
    },
    None => 150,
};
Enter fullscreen mode Exit fullscreen mode

The reason: a 600 DPI A4 page produces a ~139 MB raw RGBA buffer. libvips streams this in tiles so it doesn't OOM, but it's still slow and the output file is huge. 300 DPI is the sweet spot for print-quality output — 2480×3508 pixels for A4, ~900 KB as JPG.
The cleanup bug I fixed this week
Completely unrelated to PDF but worth mentioning — noticed in the logs that cleanup_files was reporting it deleted hundreds of files when ./tmp was actually empty.
The bug: I was counting files to delete as to_delete.len() before actually attempting deletion. Page files from multi-page PDFs get removed immediately after zip creation, but their registry entries stuck around. So the cleaner found stale registry entries with no corresponding files on disk and counted them as successfully deleted.
Fix — count only files actually removed from disk, handle NotFound separately:

match tokio::fs::remove_file(&path).await {
    Ok(_) => {
        old_files_deleted += 1;
        reg.remove(&file_name);
    }
    Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
        reg.remove(&file_name); // stale registry entry, skip count
    }
    Err(e) => {
        eprint!("Failed to delete {file_name}: {e}");
    }
}
Enter fullscreen mode Exit fullscreen mode

What's next

PDF frontend is now live — DPI selection (72/150/300) and multi-page ZIP download are both shipped. You can try it at convertifyapp.net/pdf-to-png and convertifyapp.net/pdf-to-jpg.

Still considering whether to expose pdfium explicitly as a build option for better rendering quality, or just document the poppler default behavior. For now poppler works fine for the majority of PDFs people actually upload.

Top comments (0)