HexaPDF Documentation

HexaPDF provides a wide range of capabilities for PDF work:

Creation & Manipulation

• Creating new PDFs and merging multiple files.
• Manipulating existing files and optimizing file size.
• Canvas API: A low-level API that maps directly to PDF internal operators for path drawing (lines, curves, etc.).
• Document Composition Engine: High-level layout features including flowing text, automatic page breaks, styles, and multi-column layouts.

Extraction & Inspection

• Extracting metadata, text, images, and attached files.
• PDF object validation.

Security & Interactivity

• Encryption: Supports PDF 2.0 features like AES256.
• Digital Signatures.
• PDF Forms (AcroForm): Supports Adobe Reader-like appearance generation.
• Annotations and Document Outlines.

Choosing between HexaPDF and Prawn depends on your primary goal:

Use HexaPDF if:

• You need a full PDF library that can read, manipulate, and modify existing PDF files (e.g., removing annotations or changing the object structure).
• You need advanced features like PDF forms (AcroForm), encryption (including AES256), digital signatures, or file attachments.
• You want to use existing PDFs as templates.
• You need a high-level document composition engine with automatic layout (flowing text, multi-column, etc.).

Use Prawn if:

• Your primary goal is strictly generating content from scratch and you do not need to manipulate existing PDF structures.

HexaPDF is benchmarked using two distinct layouting approaches:

1. Low-level Layouting (L): Uses the HexaPDF::Layout::TextLayouter facility and processes the entire input file at once. This is generally the fastest method for HexaPDF.
2. High-level Composition (C): Uses HexaPDF::Composer to construct the document. To manage peak memory usage, this method processes the input in chunks of 1000 lines at a time.

Note: HexaPDF performs better when the whole input is provided at once, though it maintains acceptable runtimes for line-by-line input.

You can generate graphs from benchmark output using the plot.sh script. The script requires the name of the benchmark directory as its first argument. Any additional arguments provided to plot.sh are passed directly to the underlying script.sh file.

./plot.sh raw_text "1x 5x"

The simple text rendering benchmark tests raw text output performance by writing the text of Homer's Odyssey onto A4 pages with a 72-point margin. It uses basic text drawing methods without line wrapping or text measuring.

To run the benchmark for HexaPDF (and other supported libraries), use the following command structure:

script-executable TXT_FILE OUTPUT_FILE [TTF_FILE]

Where:

• script-executable: The executable script for the library being tested.
• TXT_FILE: The source text file (e.g., the Odyssey text).
• OUTPUT_FILE: The destination PDF file.
• [TTF_FILE]: (Optional) A path to a TrueType font file. If omitted, the benchmark typically uses standard PDF Type1 fonts like Times-Roman.

To run a specific type of benchmark, execute the script.sh file located within that benchmark's directory. Each directory in the benchmark/ folder represents a different benchmark type and contains its own necessary files.

Note: These scripts are designed for Linux environments. They may work on macOS or via WSL on Windows 10.

optimization/script.sh

The line wrapping benchmark evaluates performance for line wrapping and general layouting using text from Project Gutenberg. You can run individual benchmark scripts using the following command structure:

script-executable TXT_FILE WIDTH OUTPUT_FILE [TTF_FILE]

Arguments:

• TXT_FILE: The source text file (e.g., Homer's Odyssey).
• WIDTH: The page width in points (e.g., 400, 200, 100, or 50).
• OUTPUT_FILE: The destination path for the generated PDF.
• [TTF_FILE] (Optional): A path to a TrueType font file (e.g., DejaVu Sans).

The table benchmark tests the performance of various PDF table implementations (HexaPDF, Prawn, ReportLab, fpdf2) by laying out a table with three columns (text, image, text) and varying row counts, including automatic page breaking.

To run a benchmark script, execute the script file directly with the following positional arguments:

1. NR_ROWS: The number of rows to include in the table.
2. IMAGE_FILE: The path to an image file to be used in the table.
3. OUTPUT_FILE: The path where the resulting PDF should be saved.

script-executable NR_ROWS IMAGE_FILE OUTPUT_FILE

HexaPDF is a pure Ruby library. To install it, ensure you have Ruby version 3.0 or higher installed, then use the following command:

gem install hexapdf

Requirements:

• Ruby 3.0 or higher.
• The library has one external dependency, geom2d (provided by the HexaPDF authors).
• If using the hexapdf command-line application, cmdparse is also required.