Idiomatic Rust bindings for Pdfium

pdfium-render provides an idiomatic high-level Rust interface to Pdfium, the C++ PDF library used by the Google Chromium project. Pdfium can render pages in PDF files to bitmaps, load, edit, and extract text and images from existing PDF files, and create new PDF files from scratch.

    use pdfium_render::prelude::*;

    /// Renders each page in the PDF file at the given path to a separate JPEG file.
    fn export_pdf_to_jpegs(path: &impl AsRef<Path>, password: Option<&str>) -> Result<(), PdfiumError> {
        // Bind to a Pdfium library in the same directory as our Rust executable.
        // See the "Dynamic linking" section below.

        let pdfium = Pdfium::default();

        // Load the document from the given path...

        let document = pdfium.load_pdf_from_file(path, password)?;

        // ... set rendering options that will be applied to all pages...

        let render_config = PdfRenderConfig::new()
            .set_target_width(2000)
            .set_maximum_height(2000)
            .rotate_if_landscape(PdfPageRenderRotation::Degrees90, true);

        // ... then render each page to a bitmap image, saving each image to a JPEG file.

        for (index, page) in document.pages().iter().enumerate() {
            page.render_with_config(&render_config)?
                .as_image()? // Renders this page to an image::DynamicImage...
                .into_rgb8() // ... removes the alpha channel for compatibility with the Jpeg format...
                .save_with_format(
                    format!("page-{}.jpg", index), 
                    image::ImageFormat::Jpeg
                ) // ... and saves the image to a file.
                .map_err(|_| PdfiumError::ImageError)?;
        }

        Ok(())
    }

pdfium-render binds to a Pdfium library at run-time, allowing for flexible selection of system-provided or bundled Pdfium libraries and providing idiomatic Rust error handling in situations where a Pdfium library is not available. A key advantage of binding to Pdfium at run-time rather than compile-time is that a Rust application using pdfium-render can be compiled to WASM for running in a browser alongside a WASM-packaged build of Pdfium.

Examples

Short, commented examples that demonstrate all the major Pdfium document handling features are available at https://github.com/ajrcarey/pdfium-render/tree/master/examples. These examples demonstrate:

• Rendering pages, and portions of pages, to bitmaps.
• Text and image extraction.
• Form field introspection and filling of form fields.
• Document signature introspection.
• Document attachment creation and introspection.
• Document concatenation.
• Page object introspection.
• Page annotation introspection.
• Page link introspection.
• Creation of new documents and new pages.
• Creation of page objects for text, paths, and bitmaps.
• Custom font management.
• Page object transformation.
• Multi-page tiled rendering.
• Watermarking.
• Thread safety.
• Compiling to WASM.

What's new

Release 0.9.3 increments the pdfium_latest feature to pdfium_7881 to match new Pdfium release 7881 at https://github.com/bblanchon/pdfium-binaries, fixes a bug where pdfium-render would fail to compile on targets where c_char is unsigned thanks to an excellent contribution from https://github.com/virtuallynathan, adds the new PdfRenderConfig::set_origin() function for supporting partial page rendering thanks to an excellent contribution from https://github.com/spdrman, adds the new PdfDocument::catalog() and PdfDocument::catalog_mut() functions together with the new PdfCatalog struct for interacting with a document's catalog, and adds a new PdfPageTextObject::set_unscaled_font_size() function that allows directly setting the font size of an existing text object.

Release 0.9.2 changes the visibility of the PdfiumLibraryBindingsAccessor trait from pub(crate) to pub, easing use of the raw FPDF_* API by crate consumers thanks to an excellent observation by https://github.com/martin-kolarik, changes the signature of the PdfBitmap::empty() and PdfBitmap::from_bytes() functions to remove the bindings argument which is no longer required, reworks PdfBitmap::from_bytes() as a safe function and adds a new unsafe PdfBitmap::from_bytes_unchecked() function, both thanks to excellent contributions from https://github.com/alecbarber, and adds a new PdfiumCustomFontProvider trait that can be used to override Pdfium's default platform font provider by passing a trait implementation to the new Pdfium::set_custom_font_provider() function. The font provider is called each time Pdfium needs to perform font substitution, allowing fine-grained control over font matching, loading, and caching. A new examples/custom_font_provider.rs example demonstrates the new functionality.

Release 0.9.1 increments the pdfium_latest feature to pdfium_7763 to match new Pdfium release 7763 at https://github.com/bblanchon/pdfium-binaries, relaxes lifetime restrictions on PdfPageTextSegment and PdfPageTextChars thanks to an excellent contribution from https://github.com/owl-from-hogvarts, adds a new console_log crate feature to control initialization of console_log-based logging to the console browser in WASM builds thanks to an excellent contribution from https://github.com/tectin0, and adds a new PdfPageTextObject::is_visible() utility function in response to an excellent suggestion by https://github.com/cobnett3.

Release 0.9.0 fixes a bug in the PdfClipPath::len() function thanks to an excellent contribution from https://github.com/rockyzhengwu, adds compilation target support to the PDFIUM_STATIC_LIB_PATH environment variable when linking pdfium-render to a statically-compiled Pdfium library thanks to an excellent contribution from https://github.com/richarddd, removes all deprecated items, simplifies lifetime handling across all object instances, and implements the Send and Sync traits for all object instances, allowing documents, pages, and page objects to be more easily used in multi-threaded applications. Note that Pdfium itself makes no guarantees about thread safety and should be assumed not to be thread safe; for more discussion on the limitations of multi-threading in Pdfium, see the "Multi-threading" section below. For a complete list of deprecated items that have been removed, see https://github.com/ajrcarey/pdfium-render/issues/36.

Binding to Pdfium

pdfium-render does not include Pdfium itself. You have several options:

• Bind to a dynamically-built Pdfium library provided by the operating system.
• Bind to a dynamically-built Pdfium library packaged alongside your Rust executable.
• Bind to a statically-built Pdfium library linked to your executable at compile time.

When compiling to WASM, packaging an external build of Pdfium as a separate WASM module is essential.

Dynamic linking

Binding to a pre-built Pdfium dynamic library at runtime is the simplest option. On Android, a pre-built libpdfium.so is packaged as part of the operating system (although recent versions of Android no longer permit user applications to access it); alternatively, you can package a dynamic library appropriate for your operating system alongside your Rust executable.

Pre-built Pdfium dynamic libraries suitable for runtime binding are available from several sources:

• Native (i.e. non-WASM) builds of Pdfium for all major platforms: https://github.com/bblanchon/pdfium-binaries/releases
• Android, iOS, macOS, and WASM builds of Pdfium: https://github.com/paulocoutinhox/pdfium-lib/releases

If you are compiling a native (i.e. non-WASM) build, and you place an appropriate Pdfium library in the same folder as your compiled application, then binding to it at runtime is as simple as:

    use pdfium_render::prelude::*;

    let pdfium = Pdfium::new(
        Pdfium::bind_to_library(Pdfium::pdfium_platform_library_name_at_path("./")).unwrap()
    );

A common pattern used in the examples at https://github.com/ajrcarey/pdfium-render/tree/master/examples is to first attempt to bind to a Pdfium library in the same folder as the compiled example, and attempt to fall back to a system-provided library if that fails:

    use pdfium_render::prelude::*;

    let pdfium = Pdfium::new(
        Pdfium::bind_to_library(Pdfium::pdfium_platform_library_name_at_path("./"))
            .or_else(|_| Pdfium::bind_to_system_library())
            .unwrap() // Or use the ? unwrapping operator to pass any error up to the caller
    );

This pattern is used to provide an implementation of the Default trait, so the above can be written more simply as:

    use pdfium_render::prelude::*;

    let pdfium = Pdfium::default();

Static linking

The static crate feature offers an alternative to dynamic linking if you prefer to link Pdfium directly into your executable at compile time. This enables the Pdfium::bind_to_statically_linked_library() function which binds directly to the Pdfium functions compiled into your executable:

    use pdfium_render::prelude::*;

    let pdfium = Pdfium::new(Pdfium::bind_to_statically_linked_library().unwrap());

As a convenience, pdfium-render can instruct cargo to link to either a dynamically-built or a statically-built Pdfium library for you. To link to a dynamically-built library, set the PDFIUM_DYNAMIC_LIB_PATH environment variable when you run cargo build, like so:

    PDFIUM_DYNAMIC_LIB_PATH="/path/containing/your/dynamic/pdfium/library" cargo build

pdfium-render will pass the following flags to cargo:

    cargo:rustc-link-lib=dylib=pdfium
    cargo:rustc-link-search=native=$PDFIUM_DYNAMIC_LIB_PATH

To link to a statically-built library, set the path to the directory containing your library using the PDFIUM_STATIC_LIB_PATH environment variable when you run cargo build, like so:

    PDFIUM_STATIC_LIB_PATH="/path/containing/your/static/pdfium/library" cargo build

pdfium-render will pass the following flags to cargo:

    cargo:rustc-link-lib=static=pdfium
    cargo:rustc-link-search=native=$PDFIUM_STATIC_LIB_PATH

These two environment variables save you writing a custom build.rs yourself. If you have your own build pipeline that links Pdfium statically into your executable, simply leave these environment variables unset.

PDFIUM_STATIC_LIB_PATH also supports per-target configuration by appending the target triple with underscores. For example, when cross-compiling for multiple targets:

    PDFIUM_STATIC_LIB_PATH_aarch64_apple_darwin="/path/to/arm64/pdfium" \
    PDFIUM_STATIC_LIB_PATH_x86_64_apple_darwin="/path/to/x64/pdfium" \
    cargo build --target aarch64-apple-darwin

The target-specific variable takes precedence over the generic one, allowing you to set a default path with PDFIUM_STATIC_LIB_PATH and override it for specific targets.

Note that the path you set in either PDFIUM_DYNAMIC_LIB_PATH or PDFIUM_STATIC_LIB_PATH should not include the filename of the library itself; it should just be the path of the containing directory. You must make sure your library is named in the appropriate way for your target platform (libpdfium.so or libpdfium.a on Linux and macOS, for example) in order for the Rust compiler to locate it.

Depending on how your Pdfium library was built, you may need to also link against a C++ standard library. To link against the GNU C++ standard library (libstdc++), use the optional libstdc++ feature. pdfium-render will pass the following additional flag to cargo:

    cargo:rustc-link-lib=dylib=stdc++

To link against the LLVM C++ standard library (libc++), use the optional libc++ feature. pdfium-render will pass the following additional flag to cargo:

    cargo:rustc-link-lib=dylib=c